Here are sample spreadsheets you can use to test the order import functionality:

If present, the ID will be used to identify existing orders for updates.

When creating new orders, the ID is used to group multiple rows together into a single order. The value does not need to be an existing Shopify order ID. You can use any arbitrary value (e.g. 1, 2, 3) to indicate which rows belong to the same order. Each unique ID value will become a separate order.

The order name is used as a key to identify existing orders during import. Order names should be unique. If left empty, Shopify will generate the next sequential order number automatically. When importing new orders, you can leave this blank or use any value you like. Either the ID or Name column should have a value so that multi-row orders can be grouped correctly.

When matching existing orders, the leading # is optional. A value of 1001 will match Shopify's #1001. Matching is also case-insensitive and ignores surrounding whitespace, so order numbers exported from other systems can be imported without rewriting them. Only one leading # is normalized - ##1001 is treated as a different value.

The behavior to use when updating inventory:

Phone number must include country code and be valid for the respective country. Can be different from the customer's phone number. Shopify has strict validation for phone numbers - see DAT001 error code for details.

Contact email for the order. Can be different from the customer's email address. Must be a valid email format.

Internal notes about the order that are visible in Shopify Admin but not to customers.

Comma-separated list of tags for filtering and organization purposes.

The timestamp when the order was created. This field is export-only and cannot be imported. ISO-formatted timestamps are also supported.

The timestamp when the order was last modified. This field is export-only and cannot be imported. ISO-formatted timestamps are also supported.

The date and time when the order was processed. This appears in Shopify Admin and analytics reports. ISO-formatted timestamps are also supported. If no timezone is specified, your shop's timezone will be used.

The timestamp when the order was cancelled. Empty if the order is not cancelled. ISO-formatted timestamps are also supported.

The reason for cancelling the order. Used during UPDATE to trigger order cancellation. See Cancelling Orders for details and a full example.

Supported values (case-insensitive):

Whether to refund the customer to their original payment method when cancelling an order. Only used in combination with Cancel: Reason.

Whether to send a cancellation notification email to the customer. Only used in combination with Cancel: Reason.

Whether to restock inventory when cancelling an order. Only used in combination with Cancel: Reason.

Three-letter currency code in ISO 4217 format.

The channel where the order originated. When importing, you can set any custom value except Shopify reserved words (web, pos, iphone, android, shopify_draft_order).

This field is export-only and cannot be imported.

The total discount applied to the order in the shop's base currency.

The total shipping price for the order in the shop's base currency.

Shopify-generated customer ID. Accepts both numeric IDs (e.g., 987654) and Shopify GIDs (e.g., gid://shopify/Customer/987654). If specified, the order will be linked directly to that existing customer.

When importing orders, customers are resolved in the following priority order:

Customer's email address. Used to find existing customers or create new ones if no customer ID is provided.

Customer's phone number with country code. Used as fallback to find existing customers if email is empty. When importing orders without a customer email, the app will automatically search for existing customers using this phone number to maintain customer relationships. Shopify has strict validation for phone numbers - see DAT001 error code for details.

The customer's first name. This field is optional, if you only have one name you should place it in the Customer: Last Name field instead.

The customer's last name. This field is required when creating a customer.

Notes about the customer visible in Shopify Admin.

The IP address recorded by Shopify when the customer placed the order. Useful for fraud detection and geographic analysis. This field is export only and cannot be set during import.

First name for the billing address. This field is optional, if you only have one name you should place it in the Billing: Last Name field instead.

Last name for the billing address. This field is required when creating a billing address.

Company name for billing address, if applicable.

Phone number for billing address with country code. Shopify has strict validation for phone numbers - see DAT001 error code for details.

First line of billing address. Required for billing address creation.

Second line of billing address (optional).

City for billing address. Required for billing address creation.

Province/state name for billing address. Must match Shopify's geographic classifier.

Two-character province/state code. See the complete list of codes.

Country name for billing address. If no country code is provided, Altera will attempt to convert the country name to a code automatically (e.g., "USA", "U.S.A.", "United States", "UK", "Great Britain" are all recognized). If both country and country code are provided, the country code takes precedence. See the complete list of codes.

Two-character country code for billing address (e.g., US, CA, GB). This field takes precedence over the country name field. If not provided, Altera will attempt to convert the country name to a code. See the complete list of codes.

Postal/zip code for billing address.

If your zip code starts with zeros (like 01234), Excel may strip the leading zeros. To prevent this, start the zip code with a single quote: '01234. The quote will be automatically removed during import.

First name for the shipping address. This field is optional, if you only have one name you should place it in the Shipping: Last Name field instead.

Last name for the shipping address. This field is required when creating a shipping address.

Company name for shipping address, if applicable.

Phone number for shipping address with country code. Shopify has strict validation for phone numbers - see DAT001 error code for details.

First line of shipping address.

Second line of shipping address (optional).

City for shipping address.

Province/state name for shipping address.

Two-character province/state code. See the complete list of codes.

Country name for shipping address. If no country code is provided, Altera will attempt to convert the country name to a code automatically (e.g., "USA", "U.S.A.", "United States", "UK", "Great Britain" are all recognized). If both country and country code are provided, the country code takes precedence. See the complete list of codes.

Two-character country code for shipping address (e.g., US, CA, GB). This field takes precedence over the country name field. If not provided, Altera will attempt to convert the country name to a code. See the complete list of codes.

Postal/zip code for shipping address.

If your zip code starts with zeros (like 01234), Excel may strip the leading zeros. To prevent this, start the zip code with a single quote: '01234. The quote will be automatically removed during import.

When importing line items, the app will attempt to match products and variants using the following fields in order of priority:

For Products:

For Variants:

You only need to provide one of these identifiers per product/variant. The app will automatically fall back to alternative matching methods if the primary identifier is not found.

If this column is in the sheet it cannot be blank. For exports, "Line Item" lines will be shown first, then the remaining lines will be shown in chronological order.

Possible values:

Several Line: columns are reused by non-Line-Item rows and carry different meanings depending on Line: Type:

Refund Line and Fulfillment Line rows reuse the original line item's product, variant, and tax data and add their own Refunds: or Fulfillments: columns. Fulfillment Line rows have negative Line: Quantity and Line: Total to represent the items leaving inventory. Transaction rows leave all Line: columns blank - all data lives in the Transaction: columns.

Tip: To export the Shopify Shipping Method, include line items in your export and look at the Line: Title column on rows where Line: Type is Shipping Line. The carrier code is in Line: Name and the price is in Line: Price.

Controls what action to perform on the line item when updating an existing order. This field is only used when the main Command field is set to UPDATE or MERGE.

When you set Line: Command to MERGE, the app will add new line items to the order using Shopify's Order Edit API. This allows you to:

Important Notes:

Unique identifier for the line item. Generated by Shopify for existing items, can be any unique number for new orders.

For Fulfillment Line and Refund Line rows, the Line: ID should match the Line: ID of the line item being fulfilled or refunded. This allows the app to precisely associate fulfillments and refunds with the correct line items. If Line: ID is not provided, the app will fall back to matching by other fields (see Fulfillment Line Matching).

For Shipping Line rows, this is the Shopify shipping line ID. For Discount and Transaction rows, this column is blank.

Shopify product ID for the line item. If not found, the app will try to match by handle or SKU.

Used as secondary method to identify products when Product ID is not available.

For regular line items, this is the title of the order line item. Can be set independently of the linked product title.

For shipping lines (when Line: Type is "Shipping Line"), this is the shipping method name as shown to the customer at checkout (e.g. Standard Shipping, Express Delivery). This is the equivalent of the Shipping Method column in Shopify's built-in order export.

For discount line items (when Line: Type is "Discount"), this field specifies the discount type:

Shopify variant ID for the line item. If not found, the app will try to match by SKU.

The title of the product variant included in the line item.

For shipping lines (Line: Type is "Shipping Line"), this field contains the shipping line source (e.g. shopify).

For discount lines (Line: Type is "Discount"), this field is set to automatic when the discount was applied automatically at checkout. It is blank for manually entered discount codes.

The SKU of the product variant. Used to identify products when ID and handle are not available.

The quantity of the line item purchased.

For Fulfillment Line rows, this value is negative to represent the quantity leaving inventory through that fulfillment. Discount, Shipping Line, and Transaction rows leave this column blank.

The price of one line item unit.

For shipping lines (Line: Type is "Shipping Line"), this field contains the shipping price.

When importing percentage discounts (Line: Type is "Discount" and Line: Title is "percentage"), put the percentage rate in this field (e.g., 15 for 15% off).

Discount amount applied to the line item. Always a negative value (e.g., -5.00). The Shopify API does not support setting per-line-item discounts when creating orders.

On Discount rows, this column holds the total order-level discount and is only populated on the first Discount row of the order - additional Discount rows leave it blank to avoid double-counting.

When importing, if line items have Line: Discount values but no explicit Discount row is present, the discount amounts will be automatically summed and applied as an order-level fixed discount. This prevents discount data from being lost during store-to-store migrations (e.g., when orders have automatic discounts or script-based discounts that don't have a discount code).

If a Discount row is already present in the spreadsheet, Line: Discount values on line items are ignored because the Discount row already captures the total discount amount for the order. Rolling up both would double-count the discount.

Calculated as (Quantity × Price) + Discount. This field is export-only and cannot be imported.

For Shipping Line rows, this is the shipping price. For Fulfillment Line rows, this is the negated original line total to mirror the negative Line: Quantity. On the first Discount row, it carries the total order-level discount (matching Line: Discount).

Weight per line item in grams.

Vendor name of the product purchased.

The full name of the line item, including variant details. This is typically the product title combined with variant options.

For shipping lines (Line: Type is "Shipping Line"), this field contains the shipping carrier code from Shopify (e.g. Standard, Express).

For discount lines (Line: Type is "Discount"), this field contains the discount code or automatic discount name (e.g., BIENVENUE20 or FINHIVER15).

Information about how discounts are allocated to this specific line item in the shop's base currency. This field is export-only and cannot be imported.

The line item discount divided by the line item quantity, giving the per-unit discount amount. This is the per-unit version of Line: Discount and is also negative. This field is export-only and cannot be imported.

Custom properties or attributes associated with the line item. Write each property on its own line as a key: value pair, with a single colon separating the key from the value. Use a real line break to separate each pair (in a spreadsheet cell, press Alt+Enter or Option+Enter to add a line break). When viewing the spreadsheet in Excel you may need to expand the row height to see the full value.

Each line must contain exactly one colon. If a key or value needs to include a literal colon (for example a URL), escape it as \: - for example link: https\://example.com. A line with more than one unescaped colon is rejected with error DAT020. A common cause is a source file that writes a literal \n (backslash + n) as text instead of a real line break, which leaves two pairs on one line.

The total amount of tax applied to this line item across all tax rates.

The name or title of the first tax applied to this line item.

The rate (as a decimal) of the first tax applied to this line item. Example: 0.08 = 8%.

The monetary amount of the first tax applied to this line item. If left empty but a tax rate is provided, the app will automatically calculate the tax amount using either the line item price or the linked variant's price.

The name or title of the second tax applied to this line item.

The rate (as a decimal) of the second tax applied to this line item. Example: 0.02 = 2%.

The monetary amount of the second tax applied to this line item. If left empty but a tax rate is provided, the app will automatically calculate the tax amount using either the line item price or the linked variant's price.

The name or title of the third tax applied to this line item.

The rate (as a decimal) of the third tax applied to this line item. Example: 0.01 = 1%.

The monetary amount of the third tax applied to this line item. If left empty but a tax rate is provided, the app will automatically calculate the tax amount using either the line item price or the linked variant's price.

Up to 100 tax lines are supported per line item. Use the same column naming pattern with higher numbers: Line: Tax 4 Title, Line: Tax 4 Rate, Line: Tax 4 Price, Line: Tax 5 Title, and so on up to Line: Tax 100 Price.

The quantity of this line item that can still be fulfilled. This is typically the ordered quantity minus any already fulfilled quantity.

The name of the fulfillment service responsible for fulfilling this line item. Common values include manual, amazon, shipwire, etc.

The price of the line item before any taxes are applied.

The Presentment Currency category contains export-only versions of the order's money fields in the presentment currency, which is the currency shown to the customer at checkout. For stores using Shopify Markets with multiple currencies, these values may differ from the shop's base currency. This category is opt-in: enable it on the export configuration page to include these columns in your file.

The order subtotal in the presentment currency, before shipping, taxes, and order-level discounts.

The monetary amount of the first tax line in the presentment currency.

The monetary amount of the second tax line in the presentment currency.

The monetary amount of the third tax line in the presentment currency.

Presentment-currency amounts for additional tax lines on the order. Columns named Tax 4: Presentment Price through Tax 10: Presentment Price are auto-included in the export when an order has more than three tax lines, mirroring the shop-currency Tax N: Price columns.

The total tax for the order in the presentment currency, summed across all tax lines.

The total discount applied to the order in the presentment currency.

The total shipping price for the order in the presentment currency.

The total duties for the order in the presentment currency.

The total of any additional fees on the order in the presentment currency.

The total amount refunded on the order in the presentment currency.

The outstanding balance still owed on the order in the presentment currency.

The full order total in the presentment currency, including taxes, shipping, duties, and fees, after discounts.

The unit price that was presented to the customer at checkout in their local currency.

The three-letter currency code (ISO 4217) for the presentment price. This shows which currency the customer saw and paid in at checkout.

The discount amount applied to the line item in the presentment currency. Always a negative value, matching the sign convention of Line: Discount.

The order-level discount amount allocated to this line item in the presentment currency. See Line: Discount Allocation for details on how allocations work.

The per-unit discount amount in the presentment currency, calculated as Line: Presentment Discount divided by Line: Quantity.

The line item total in the presentment currency, calculated as (Quantity × Presentment Price) + Presentment Discount.

Transaction data can be included in your spreadsheet in two ways:

Both formats are equivalent - Altera will process them the same way.

Shopify-generated transaction identifier. This field is export-only and cannot be imported.

When importing orders, only one SALE transaction is allowed per order. If your spreadsheet contains multiple SALE transactions for a single order, only the first SALE transaction will be imported. All other transaction types (authorization, capture, refund, void) will be imported normally.

The amount of the transaction in the order currency.

Currency code for the transaction. Should match the order currency.

The name of the payment gateway used for the transaction. The value will be prefixed with manual to avoid triggering real transactions. Eg, paypal will be imported as manual (paypal).

To import fulfillments, add rows with Line: Type set to Fulfillment Line. Each fulfillment line represents one line item being fulfilled. Multiple fulfillment lines with the same Fulfillment: ID are grouped into a single fulfillment.

You can also add fulfillment data directly on Line Item rows by filling in the Fulfillment: columns. This is a shortcut that fulfills each line item for its full quantity. Use dedicated Fulfillment Line rows when you need more control, such as partial fulfillments or grouping specific items into separate shipments.

Each Fulfillment Line row must be associated with the Line Item it fulfills. The app uses the following logic to match them:

When using composite key matching, make sure the values on your Fulfillment Line rows match the corresponding Line Item rows exactly.

Used to group fulfillment lines into fulfillments. Rows with the same Fulfillment: ID will be grouped into the same fulfillment.

When exporting, this will contain the Shopify-generated fulfillment ID. When importing, you can use any value - it is only used by the app for grouping and will not be saved to Shopify. For example, you could use F1, F2, etc. to organize your fulfillments.

When updating existing orders with a numeric Shopify fulfillment ID, the app will update the tracking information on that specific fulfillment. When using a custom (non-numeric) ID, the app will create new fulfillments.

Name of the tracking company. Must match Shopify's supported tracking companies. Read tracking information updates for how to change tracking information for existing orders.

Tracking number provided by the shipping company. Read tracking information updates for how to change tracking information for existing orders.

URL for tracking the shipment provided by the shipping company. Read tracking information updates for how to change tracking information for existing orders.

Name of the location where the fulfillment is shipped from.

If TRUE, Shopify will send a notification email to the customer when the fulfillment is created or updated.

The type of payment terms applied to the order. If you are using payment terms you need to use one of the following values:

Shopify does not support custom 'Net X' payment terms. For example, 'Net 14' is not supported.

The date and time when payment terms were issued to the customer. ISO-formatted timestamps are also supported. If no timezone is specified, your shop's timezone will be used. This field is used with the Net X payment terms types. If you do not set this field, the app will use the current date.

The date when payment is due according to the payment terms. ISO-formatted timestamps are also supported. If no timezone is specified, your shop's timezone will be used. This field is only required if you use the Fixed date payment terms type.

The date and time when payment terms were completed or paid in full. Empty if payment is still pending. ISO-formatted timestamps are also supported.

Indicates whether the payment for the order is past due.

Use these columns to link an order to a B2B Company Location. The order will appear in the company's order history in Shopify admin and the customer's account page.

Before importing orders with company links:

At a minimum, set:

When the location can be uniquely identified on its own (e.g. by its Shopify ID, or by a name/external ID that is unique across all companies on the store), that's enough.

When the same location name or external ID exists across multiple companies, also set one of Company: ID, Company: External ID, or Company: Name to scope the lookup. Without a company column, ambiguous matches fail with ORD021.

Each column you set is matched on its own - there is no fallback between columns. If you set Company: ID and the ID doesn't exist, the row fails; it does not try Company: External ID or Company: Name next. Pick the column that matches the source of truth for your data and leave the others blank.

The same applies to the location columns: Company: Location ID is tried first if set, then Company: Location External ID, then Company: Location Name. When a Company: column is also set, the location lookup is restricted to that company.

Rows fail with ORD021 when:

The company link can only be set when an order is created. Shopify's order update API doesn't allow changing the company location of an existing order - use REPLACE if you need to re-link an existing order. MERGE and UPDATE rows that set Company columns will skip the link and emit ORD023; other changes on the row are still applied.

The Shopify internal ID for the B2B Company. Accepts the numeric ID or the full GID (gid://shopify/Company/5301829). Must match an existing company on the store, otherwise the row fails with ORD021.

The exact name of the B2B Company. Must match an existing company on the store, otherwise the row fails with ORD021. Set this column when you don't have the Shopify ID or an external ID for the company.

The externally-supplied ID for the company. Useful when migrating from another platform that already has its own IDs. Must match an existing company on the store, otherwise the row fails with ORD021.

The Shopify internal ID for the B2B Company Location. Accepts the numeric ID or the full GID (gid://shopify/CompanyLocation/8826651). The order will be attached to this location's purchasing entity. If a Company: column is also set, the location must belong to that company, otherwise the row fails with ORD021.

The exact name of the company location. When set without a Company: column and more than one company on the store has a location with this name, the row fails with ORD021. Set Company: ID, Company: External ID, or Company: Name alongside to disambiguate.

The externally-supplied ID for the company location. When set without a Company: column and more than one company on the store has a location with this external ID, the row fails with ORD021. Set Company: ID, Company: External ID, or Company: Name alongside to disambiguate.

Shopify-generated refund ID. Used to group refund lines together.

Note explaining the reason for the refund.

The name of the location to restock items into when Refund: Restock is TRUE. If left empty, the import defaults to the shop's primary location.

Combined with the default Inventory Behaviour of bypass, the destination store's inventory is not adjusted when importing historical orders. Set Inventory Behaviour to decrement_obeying_policy if you want the order to actually decrement inventory and the restock to add it back.

Metafields can be imported and exported with orders to store custom metadata and additional attributes. You can export:

For detailed information about working with metafields, see our Metafields guide.

You can use these filters to limit which orders are exported:

When updating existing orders, only a limited set of fields can be modified. Most order information becomes read-only after the order is created, but you can update these specific fields:

This update behavior aligns with Matrixify, so existing Matrixify templates should work without changes. If you see any differences, please let us know.

The following fields can be updated on existing orders:

When updating tracking information for fulfillments, the following logic applies:

This ensures that tracking information is always properly associated with the correct fulfillment, whether you're updating existing fulfillments or creating new ones.

You can mark orders with a pending payment status as paid by including a successful sale transaction in your update spreadsheet. This uses Shopify's orderMarkAsPaid mutation to record the full outstanding balance as paid.

To mark an order as paid:

The Transaction: Amount, Transaction: Currency, and Transaction: Gateway columns are optional when updating - the payment will always be recorded for the full outstanding amount regardless of the values in these columns.

Important Notes:

You can cancel existing orders by setting the Cancel: Reason field during an update. This uses Shopify's orderCancel mutation to cancel the order, optionally restocking inventory and refunding the customer.

To cancel an order:

The reason for cancelling the order. Supported values (case-insensitive):

Important Notes:

You can add new line items to existing orders by setting the Line: Command field to MERGE for the line items you want to add. This functionality uses Shopify's Order Edit API to add items to orders after they've been created.

To add line items to an existing order:

This will add 2 units of SKU WIDGET-123 and 1 unit of SKU GADGET-456 to order #1001.

This will add two custom line items (Gift Wrapping and Rush Processing) to order #1001.

This adds both a variant-linked item (WIDGET-123) and a custom item (Setup Fee) to the same order.

For more information about error codes, see our Error Codes documentation.