File Format - Order
Order History File Format
The first line of an Order History CSV file must be the header row.
An order instance is a group of rows in the CSV file that are sequential and include the same required fields. Data relating to fields specified under Base Headers and Multi-Column Headers must be specified in the first row of an order instance. Additional rows of an order instance may only include fields specified under Multi-Row Headers.
Required Headers
To successfully import an order CSV file, the following columns must be included in the header row:
| Column Name | Description | Type |
|---|---|---|
Order ID (Required)* | Identification string for an order | string |
Base Headers
The following headers are optional. Fields for these columns must be specified in the first row of an order instance, otherwise data will be lost.
| Column Name | Description | Type |
|---|---|---|
Purchase Date (Required) * | Date which the order was made (Z-normalized RFC3339 format) | string |
Store ID (Required)* | ID of the store where the order was made | string |
Employee ID (Required)* | ID of the employee associated with this order | string |
Customer ID (Required)* | ID of the customer who placed this order | string |
Currency (Required)* | Currency used to pay for this order | string |
Order Status ID (Required)* | ID of the order status of this order. Integers will be resolved to internal identifiers | integer, string |
Order Tax (Required)* | Amount of tax paid for this order (2 decimal places) | number |
Order Total (Required)* | Total cost of this order (2 decimal places) | number |
Payment Method | Payment method used to pay for the order (could be Visa, MC, etc. or Cash/Credit/etc.) | string |
Payment Module Code | Payment module code used when paying for this order | string |
| Groups | See below | |
| Custom Attributes | See below |
Groups
A group is a class of headers that relate to one another, and may allow for multiple pieces of information to be presented. For example, a customer can have multiple emails, addresses, phone numbers, and more.
Order groups include:
Billing Address
There is one way that a billing address can be formatted in your CSV file. The header row may only contain up to one set of billing address headers. Only the first row of an order instance can contain data relating to a billing address. Data in additional rows under a billing address column will be lost. All headers in this group are optional.
The following columns may be included:
| Column Name | Description | Type |
|---|---|---|
Billing Name | Name of the recipient | string |
Billing Address | Street address of the bill | string |
Billing Suburb | Suburb of this billing address | string |
Billing City | City of this billing address | string |
Billing Zone | Zone (such as state or province) of this billing address | string |
Billing Postcode | Postal code of this billing address | string |
Billing Country | Country of this billing address | string |
Delivery Address
There is one way that a delivery address can be formatted in your CSV file. The header row may only contain up to one set of delivery address headers. Only the first row of an order instance can contain data relating to a delivery address. Data in additional rows under a delivery address column will be lost. All headers in this group are optional.
The following columns may be included:
| Column Name | Description | Type |
|---|---|---|
Delivery Name | Name of the recipient | string |
Delivery Address | Street address of the delivery | string |
Delivery Suburb | Suburb of this delivery address | string |
Delivery City | City of this delivery address | string |
Delivery Zone | Zone (such as state or province) of this delivery address | string |
Delivery Postcode | Postal code of this delivery address | string |
Delivery Country | Country of this delivery address | string |
Customer Address
There is one way that a customer address can be formatted in your CSV file. The header row may only contain up to one set of customer address headers. Only the first row of an order instance can contain data relating to a delivery address. Data in additional rows under a delivery address column will be lost. All headers in this group are optional.
The following columns may be included:
| Column Name | Description | Type |
|---|---|---|
Customer Name | Name of the customer | string |
Customer Address | Street address of the customer | string |
Customer Suburb | Suburb of this customer’s address | string |
Customer City | City of this customer’s address | string |
Customer Zone | Zone (such as state or province) of this customer’s address | string |
Customer Postcode | Postal code of this customer’s address | string |
Customer Country | Country of this customer’s address | string |
Shipment
There is one way that a shipment can be formatted in your CSV file. The header row may only contain up to one set of shipment headers. Only the first row of an order instance can contain data relating to a shipment. Data in additional rows under a shipment column will be lost. All headers in this group are optional.
The following columns may be included:
| Column Name | Description | Type |
|---|---|---|
Shipping Method | Method of this shipment | string |
Shipping Module Code | Code representing the shipping module of this shipment | string |
Line Items
There are two ways that line items can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of an order instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Line Items group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Item Product ID | Item N Product ID | ID of the product of this line item. If not provided, lookup via variantId will be performed. | string |
Item Variant ID | Item N Variant ID | ID of the variant of this line item | string |
Item Original Price | Item N Original Price | Original price of this line item (4 decimal places) | number |
Item Paid Price | Item N Paid Price | Price actually paid for this line item (4 decimal places) | number |
Item Tax | Item N Tax | Tax paid for this line item (4 decimal places) | number |
Item Quantity | Item N Quantity | Quantity of this line item purchased (decimal precision: float) | number |
Item Refund Quantity | Item N Refund Quantity | Quantity of the line item that have already been refunded | number |
Where N is some positive integer.
Totals
There are two ways that totals can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of an order instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Totals group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Total Description(Required)* | Total N Description | Kind of total this is (e.g. Total, Subtotal) | string |
Total Sort Order(Required)* | Total N Sort Order | Order in which this total is sorted | integer |
Total Value(Required)* | Total N Value | Amount of this total (4 decimal places) | number |
Where N is some positive integer
Payments
There are two ways that payments can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of an order instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Payments group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Payment ID | Payment N ID | Identification string for a payment | string |
Payment Amount | Payment N Amount | Amount of this payment (4 decimal places) | number |
Payment Type | Payment N Type | Physical method used to pay (Credit, Debit, Cash, Remote) | string |
Payment Token | Payment N Token | Token representing the payment | string |
Payment Vendor | Payment N Vendor | Vendor used to process this payment | string |
Where N is some positive integer.
Custom Attributes
There are two ways that custom attributes can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Custom Attributes group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Custom Attribute ID (Required)* | Custom Attribute N ID | Identifier of the custom attribute | string |
Custom Attribute Value (Required)* | Custom Attribute N Value | Value of the attribute | string |
Custom Attribute Language ID (Required)* | Custom Attribute N Language ID | Language of the attribute. Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer.
Order History CSV Example
See the following Order History CSV sample file.