> ## Documentation Index
> Fetch the complete documentation index at: https://help.maestra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Import Orders from a File

Order import lets you load your customers' orders into Maestra Platform in bulk — line items, statuses, prices, discounts, and more. You'll need it when you first migrate data from another system, or when you upload orders on a regular schedule because there's no direct integration.

Imports run under **Customer Data Platform → Imports**. Click **New import** to open the settings.

Before you import, make sure your account has:

* a [custom field](/api-integrations/how-to-create-a-custom-field) of type **External ID** on the **Order** entity;
* an [external system](/administration/how-to-create-an-external-system) for identifying products;
* the [integration point](/api-integrations/how-to-create-and-configure-an-integration-point) and [touchpoint](/customers-orders-and-products/actions/channels-and-touchpoints/touchpoints/how-to-create-a-touchpoint) the orders will be assigned to.

## Step 1. Choose the import type

Pick the import type — **Orders and actions → Orders**.

## Step 2. Prepare and upload the file

Below the **Upload a file for import** field, you'll find a reference of every field you can load, plus a sample file template. Use them as the starting point for your own data.

Work out which fields you need. The file has to contain every required field:

| Field | Required | Description |
| - | - | - |
| Order ID in `{External system}` | ✅ At least one | The order's unique ID. Needs a custom field of type **External ID** on the **Order** entity, created in advance |
| Order created/updated date and time | ✅ | When the order was last changed, in UTC |
| Customer identifier | ✅ At least one | Email, phone, card number, Maestra ID, or external customer ID |
| Product ID in `{External system}` | ✅ | The product's ID in the external system |
| Product quantity | ✅ | Number of units in the order line |
| Base product price<br />Customer price for the order line | ✅ One of the two | Price per unit, or the line's final price (not counting line cancellations or returns) |
| Order line status | ✅ | The line's current status — for example, paid, canceled, or returned |
| Order and order line custom fields | ❌ | Any custom fields configured on the account for the **Order** and **Order line** entities |

Build the file. Use the first row for field names — the wording is up to you.

* Format: `.csv` or `.txt`.
* Each row is one order line. An order with several lines takes several rows with the same external order ID.

See [Preparing a file for import](/import-data/preparing-a-file-for-import) for the full set of recommendations.

Upload the file and click **Continue**.

## Step 3. Map the file's fields

Maestra Platform maps the file's columns to its own fields automatically. Check the result and adjust it by hand if you need to:

* In the **Import** column, tick the fields you want to load. Unticked columns are skipped.
* In the **Maestra field** column, map each file column to a field on the account. Optional fields left unmapped are skipped.

<Tip>
  If a custom field you need doesn't exist yet, create it with the **Create custom field** button.
</Tip>

Click **Continue**.

<Warning>
  Make sure the order ID and product ID fields point to the right [external system](/administration/how-to-create-an-external-system).
</Warning>

## Step 4. Configure the import

This step sets extra parameters for the import:

* **Data source** — the integration point the data came through. Affects how the customer's actions are attributed. Defaults to the Maestra admin panel.
* **Touchpoint** — the channel or integration the action is tied to. By default it's derived from the integration point. To tie the orders to a specific website or store, pick the touchpoint manually.
* **Comment** — a description of the import. Makes it easier to find in the list later.

## Step 5. Review and start the import

Before you start, Maestra Platform shows the first rows of the file with the mapping already applied. Check that the data looks the way you expect — that the right values landed in the right fields.

If everything's correct, click **Start import**.

## How to track the import

Once started, the import appears in the list on the **Import** page. For each task you'll see:

* start date,
* import type,
* source file with its comment,
* load progress,
* rows imported and errors,
* who started it.

If errors came up during the import, some rows were skipped. Open the import details to see which rows had a problem and why. Fix them in the file and run the import again.

## How to update an order's status

When you import an order again with the same external ID, Maestra Platform updates its status and the other line fields.

<Warning>
  Once an order that used a promo code or points is canceled, you can't move it to any other status. That's how the promo code and points get returned to the customer correctly, without the benefit being applied twice.

  If you still need to change the status, create a new order with a different external ID.
</Warning>

## The result

Once the task finishes, the orders show up in customer profiles and are ready to use in segmentation, campaigns, and analytics.

If errors came up, some rows may have been skipped. Open the task details to see the problem rows and the reason, fix them in the file, and run the import again.