Master the art of historical order formatting with our scenario-based interactive guides and templates.
Pre-requisite: These tutorials use exact column headers from the final CSV structure. If you haven't downloaded the template, please visit the Phase 1 Data Preparation guide.
Below is the exact structural blueprint required for a successful import. Scroll horizontally to view all 61 supported headers. Select a column header to view its requirements and mapping logic.
The unique identifier for the order (e.g., TC-001). Group multiple lines by repeating this ID.
Start your migration with our pre-formatted template. It contains all 61 exact column headers required by the HistoriQ engine to prevent mapping errors.
61 Columns • UTF-8 Format • Ready to Use
A single customer receipt often contains multiple products. Here is exactly how to format your rows so Shopify groups them into one single Order ID.
The order_number column groups your data. To combine multiple line items into one receipt, create a new row for each product, but keep the exact same value in the order_number column.
| order_number | processed_at | line_item_title | price | transaction_amount |
|---|---|---|---|---|
| TC-001 | 2024-01-10 9:00 | Wireless Keyboard | 49.99 | 63.99 |
| TC-001 | Leave Blank | Wireless Mouse | 25.00 | Leave Blank |
Notice: Global order fields like transaction_amount and processed_at are only required on the very first row of the order.
Control exactly how the order appears in Shopify's financial reports by mapping the correct status.
status ColumnShopify accepts specific keywords. You must use strings like PAID, PARTIALLY_PAID, REFUNDED, VOIDED, PENDING, or AUTHORIZED.
| order_number | status | transaction_amount |
|---|---|---|
| TC-001 | PAID | 63.99 |
| TC-006 | PARTIALLY_PAID | 50.00 |
| TC-007 | REFUNDED | 50.00 |
If importing a REFUNDED or VOIDED order, you can use the cancel columns:
cancel_reason: Options include `customer`, `inventory`, `fraud`, `declined`, `other`.cancel_restock: MUST be FALSE. If left blank, Shopify assumes you want to take a 3-year-old product and add it back to active live inventory!Prevent historical imports from clogging up your warehouse team's shipping queue by mapping fulfillment accurately, and optionally import backdated tracking data.
fulfillment_status ColumnMost legacy POS migrations should default to fulfilled because the customer already walked out of the store.
The order is complete. It will immediately be archived and removed from your open orders queue.
Some items were handed to the customer, but the rest still needs to be shipped.
The historical order still needs to be packed and shipped by your warehouse.
If your old system contains tracking numbers, you can import them directly into the Shopify order timeline. Use the following columns:
fulfillment_tracking_company: Specifies the carrier (e.g. USPS, FedEx).fulfillment_tracking_number: The tracking hash. You can separate multiple with a semicolon ;fulfillment_tracking_url: Optional direct link to the carrier's tracing page.fulfillment_shipment_status: A valid status string (e.g. delivered, in_transit).fulfillment_processed_at: To strictly define exactly *when* the delivery event happened.You can strictly bind the fulfillment record to a specific Shopify Location using the fulfillment_location column.However, passing the name of a 3PL location (such as Amazon FBA Shipwire) will cause the importer to automatically skip the fulfillment.This is a strict fail-safe to prevent your warehouse from accidentally shipping out three-year-old legacy orders to customers!
How does Shopify know *which* product the customer bought? You link historical data to your live Shopify products using SKUs.
| line_item_title | item_sku | barcode |
|---|---|---|
| Wireless Keyboard | SKU-KBD-001 | 12345678 |
The system will automatically link the historical line item to the actual live product in your store. The product image will appear on the historical order.
(e.g., A discontinued product). The system will elegantly fallback and create a "Custom Line Item" using the text provided in the line_item_title column.
Shopify's financial API is strict. If you processed a discount, the math must equate perfectly.
Do not leave the price columns blank. Blank columns are interpreted as errors. You must declare the exact discount types and amounts.
If the item had a retail price, but you gave a discount, fill out the following columns:
| price | discount_title | discount_type | discount_amount |
|---|---|---|---|
| 299.00 | Agency Discount | percentage | 10.00 |
| 199.00 | VIP Loyal | fixed_amount | 20.00 |
discount_type accepts exactly two strings: percentage or fixed_amount.Do not rely on Shopify to recalculate old taxes; force Shopify to accept your exact historical tax numbers.
To force manual tax entries, use these specific columns. If a single product has multiple taxes (e.g. HST and GST), use the `tax_2` columns.
| line_item_tax_price | tax_title | tax_rate | tax_price |
|---|---|---|---|
| 4.00 | Sales Tax | 0.08 | 4.00 |
line_item_tax_price: The sum of taxes just for this specific row item.tax_rate: Must be a decimal (8% = 0.08).tax_price: The total amount collected for this tax on the entire order.If you want historical sales to show up when a customer logs into their Shopify account, you must link the data correctly.
Shopify will automatically link an order to a customer profile if the email column matches an existing customer in your store.
If you migrated your customers first and exported their new Shopify IDs, use the shopify_customer_id column.
Did the customer pay for shipping? Pass that data cleanly into Shopify's native shipping cost fields.
Populate these columns on the first row of the order to register shipping costs.
| shipping_line_title | shipping_line_price | shipping_line_code | shipping_line_source |
|---|---|---|---|
| Express Shipping | 25.00 | EXP1 | fedex_ground |
Retain the physical context of historical orders to ensure geographic reporting works in Shopify Analytics.
Use the `shipping_*` and `billing_*` columns. Provide standard values for `shipping_name`, `shipping_address1`, `shipping_city`, `shipping_province_code` (e.g., CA or ON), `shipping_zip`, and `shipping_country_code` (e.g., US or CA).
tags: Separate multiple tags with commas (e.g., `import,legacy_pos,test`). This is vital for bulk-deletion if you make a mistake.note: Any internal staff notes or customer instructions recorded at checkout.Need help? Contact support and we’ll assist you as soon as possible.