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.
Spec
The following table shows the accepted CSV columns for the orders entity. Note that any columns including N denote a dynamic integer. A column specified as Field N signifies that you can use columns Field 1, Field 2, …, Field N to allow for multiple values per record of the given field, similar to an array.
| CSV Header | Data Type | Group | Required | Description |
|---|---|---|---|---|
Order ID | string | Yes | External identifier of the record | |
Purchase Date | string | No | Date that this Order was placed (Z-normalized RFC3339 format) | |
Store ID | string | No | ID of the Store in which this Order was placed (externalId resolvable) | |
Employee ID | string | No | ID of the Employee associated with this Order (externalId resolvable) | |
Customer ID | string | No | ID of the Customer who placed this Order (externalId resolvable) | |
Currency | string | No | Currency used to pay for this Order | |
Order Status ID | integerORstring | No | ID of the Order Status of this Order (externalId resolvable). Valid values are:1(Pending)2 (Processing)3 (Completed)4 (Update)5 (Waiting for Verification)6 (Cancelled)7 (Refunded)8 (Waiting For Stock)9 (Partially Shipped)10 (Ready For Pickup)11 (Other)12 (Authenticating)13 (Void)14 (PAYMENT_AUTHORIZED)15 (Deleted)16 (Pending Acknowledgement)17 (Send Payment Link)18 (Failed To Send Payment Link)19 (PAYMENT_CAPTURED)1001 (Client controlled order status.)1002 (Client controlled order status.)1003 (Client controlled order status.)1004 (Client controlled order status.)1005 (Client controlled order status.) | |
Order Tax | number | No | Amount of tax paid for this Order (decimal precision: 2). This can be negative in a return or exchange order | |
Order Total | number | No | Total cost of this Order (decimal precision: 2). This can be negative in a return or exchange order | |
Payment Method | string | No | Payment method used to pay for the Order | |
Payment Module Code | string | No | Payment module code used when paying for the Order | |
Return Reason ID | integerORstring | No | Return reason ID, if any. Refer to https://docs.tulip.com/apidocs/dalv70#tag/RefundReasons | |
Order Type | integerORstring | No | The type of the order. Valid values are:1- for “new”, which is a standard sale5- for “remote_pay”6 - for “exchange”, a mixed purchase and return item order7- for “return”, a return item only order | |
Parent Order ID | integerORstring | No | ID of the Order’s parent (externalId resolvable) | |
Billing Name | string | Billing Address | No | Name for billing address |
Billing Address | string | Billing Address | No | Street address of this bill |
Billing Suburb | string | Billing Address | No | Suburb of this billing address |
Billing City | string | Billing Address | No | City of this billing address |
Billing Zone | string | Billing Address | No | Zone (such as state or province) of this billing address |
Billing Postcode | string | Billing Address | No | Postal code of this billing address |
Billing Country | string | Billing Address | No | Country of this billing address |
Delivery Name | string | Delivery Address | No | Name of the recipient |
Delivery Address | string | Delivery Address | No | Street address of the delivery |
Delivery Suburb | string | Delivery Address | No | Suburb of this delivery address |
Delivery City | string | Delivery Address | No | City of this delivery address |
Delivery Zone | string | Delivery Address | No | Zone (such as state or province) of this delivery address |
Delivery Postcode | string | Delivery Address | No | Postal code of this delivery address |
Delivery Country | string | Delivery Address | No | Country of this delivery addres |
Customer Email Address | string | No | Email address of the customer | |
Customer Name | string | Customer Address | No | Name of the customer |
Customer Address | string | Customer Address | No | Street address of the customer |
Customer Suburb | string | Customer Address | No | Suburb of this customer’s address |
Customer City | string | Customer Address | No | City of this customer’s address |
Customer Zone | string | Customer Address | No | Zone (such as state or province) of this customer’s address |
Customer Postcode | string | Customer Address | No | Postal code of this customer’s address |
Customer Country | string | Customer Address | No | Country of this customer’s address |
Shipping Method | string | Shipment | No | Shipping method name of this shipment, if any |
Shipping Module Code | string | Shipment | No | Code representing the shipping module of this shipment, if any |
Order Discount Reason ID | integer | Order Discounts | No | Reason ID for the discount. Refer to https://docs.tulip.com/apidocs/dalv70#tag/DiscountReasons |
Order Discount Discount ID | integer | Order Discounts | No | Discount ID for the discount. Refer to https://docs.tulip.com/apidocs/dalv70#tag/Discounts |
Order Discount Amount | number | Order Discounts | No | Order discount amount. Can be a currency amount or a percentage amount |
Order Discount Type | string | Order Discounts | No | Type of order discount. Valid values are:currencypercentage |
Order Discount Name | string | Order Discounts | No | Name of the discount, used for display purposes |
Order Discount Source | string | Order Discounts | No | Source of the discount. Valid values are:manual: for discounts that are added manually by users during checkout.script: for discounts that are added via Tulip Promo Engine Scriptsextensibility-hook: for discounts that are used by external systems, such as adding logic based or coupon code based applied discounts to a basket or item |
Order Discount Ref Num | number | Order Discounts | No | Ref num for discount reason |
Order Discount Attribute Description | string | Order Discounts | No | Description of order discount attributes |
Order Discount Attribute Language ID | integer | Order Discounts | No | Language ID of order discount attributes |
Order Discount Attribute N Description | string | Order Discounts | No | |
Order Discount Attribute N Language ID | integer | Order Discounts | No | |
Order Discount N Reason ID | integer | Order Discounts N | No | |
Order Discount N Discount ID | integer | Order Discounts N | No | |
Order Discount N Amount | number | Order Discounts N | No | |
Order Discount N Type | string | Order Discounts N | No | |
Order Discount N Name | string | Order Discounts N | No | |
Order Discount N Source | string | Order Discounts N | No | |
Order Discount N Ref Num | number | Order Discounts N | No | |
Order Discount N Attribute Description | string | Order Discounts N | No | |
Order Discount N Attribute Language ID | integer | Order Discounts N | No | |
Order Discount N Attribute N Description | string | Order Discounts N | No | |
Order Discount N Attribute N Language ID | integer | Order Discounts N | No | |
Item Product ID | string | Line Items | Yes | ID of the product of this line item. If not provided, lookup via Item Variant ID will be performed |
Item Variant ID | string | Line Items | Yes | Variant ID of this Line Item, if applicable (externalId resolvable) |
Item Tax Inclusive | integer | Line Items | No | Indicates if the price included taxes |
Item Is Blind Return | integer | Line Items | No | Whether or not this item was a blind return |
Item Original Price | number | Line Items | No | Original list price of this Line Item prior to reductions (decimal precision: 4) |
Item Paid Price | number | Line Items | No | Price actually paid for this Line Item after being reduced or discounted (decimal precision: 4). This can be negative in a return or exchange order |
Item Tax | number | Line Items | No | Tax paid for this Line Item (decimal precision: 4) |
Item Quantity | number | Line Items | No | Quantity of this Line Item purchased (does not need to be an integer) (decimal precision: float). Always positive, even in return orders |
Item Refund Quantity | integer | Line Items | No | Quantity of the line item that have already been refunded |
Item Line Sequence Number | integerORstring | Line Items | No | Order/sequence of line item in the order |
Item Parent Line Sequence Number | integerORstring | Line Items | No | Order/sequence of a return or exchange items parent item |
Item Parent Order ID | string | Line Items | No | ID of the items parent order ID, in return and exchange scenarios (externalId resolvable) |
Item Custom Attribute N ID | string | Line Items | No | |
Item Custom Attribute N Value | string | Line Items | No | |
Item Custom Attribute N Language ID | integerORstring | Line Items | No | |
Item N Product ID | string | Line Items N | Yes | |
Item N Variant ID | string | Line Items N | Yes | |
Item N Tax Inclusive | integer | Line Items N | No | |
Item N Is Blind Return | integer | Line Items N | No | |
Item N Original Price | number | Line Items N | No | |
Item N Paid Price | number | Line Items N | No | |
Item N Tax | number | Line Items N | No | |
Item N Quantity | number | Line Items N | No | Quantity of this Line Item purchased (does not need to be an integer) (decimal precision: float). Always positive, even in return orders |
Item N Refund Quantity | integer | Line Items N | No | |
Item N Line Sequence Number | integerORstring | Line Items N | No | |
Item N Parent Line Sequence Number | integerORstring | Line Items N | No | |
Item N Parent Order ID | string | Line Items N | No | ID of the Order’s parent (externalId resolvable) |
Item N Custom Attribute N ID | string | Line Items N | No | |
Item N Custom Attribute N Value | string | Line Items N | No | |
Item N Custom Attribute N Language ID | integerORstring | Line Items N | No | |
Total Description | string | Totals | No | Kind of Total this is (for example,Total or Subtotal) |
Total Sort Order | integer | Totals | No | Order in which this Total is sorted |
Total Value | number | Totals | No | Amount of this Total (decimal precision: 4). This can be negative in a return or exchange order |
Total Class | string | Totals | No | Class identification of what type of total this is |
Total N Description | string | Totals N | No | |
Total N Sort Order | integer | Totals N | No | |
Total N Value | number | Totals N | No | |
Total N Class | string | Totals N | No | |
Payment ID | string | Payments | No | External identifier of the record |
Payment Amount | number | Payments | No | Amount of this Order Payment (decimal precision: 4) |
Payment Token | string | Payments | No | Token representing the payment |
Payment Vendor | string | Payments | No | Vendor used to process this payment (Deprecated) |
Payment Currency | string | Payments | No | Currency ID of this Payment (externalId resolvable). Refer to: https://docs.tulip.com/apidocs/dalv70#tag/Currencies |
Payment Status | string | Payments | No | Payment Status ID of this Payment (externalId resolvable). Refer to: https://docs.tulip.com/apidocs/dalv70#tag/OrderPaymentStatuses |
Payment Parent Id | string | Payments | No | The ID of the payments parent in refund scenarios |
Payment Scale | integer | Payments | No | Decimal precision for Amount (currency decimal_places is used if no scale is provided) |
Payment Scaled Amount | integer | Payments | No | Amount of this Order Payment without decimal precision (can be null to autocalculate) |
Payment Scaled Cash Rounding | integer | Payments | No | Amount added or subtracted on cash payments to satisfy the nearest possible denomination |
Payment Cash Drawer External Id | string | Payments | No | The external ID of the cash drawer used for this payment, if a cash payment was made |
Payment Type Id | integer | Payments | No | Type of this Order Payment. Valid values are:1 for purchase2 for refunds |
Payment Custom Attribute N ID | string | Payments | No | |
Payment Custom Attribute N Value | string | Payments | No | |
Payment Custom Attribute N Language ID | integerORstring | Payments | No | |
Payment N ID | string | Payments N | No | External identifier of the record |
Payment N Amount | number | Payments N | No | |
Payment N Token | string | Payments N | No | |
Payment N Vendor | string | Payments N | No | |
Payment N Currency | string | Payments | No | |
Payment N Status | string | Payments | No | |
Payment N Parent | string | Payments | No | |
Payment N Scale | number | Payments | No | |
Payment N Scaled Amount | number | Payments | No | |
Payment N Scaled Cash Rounding | number | Payments | No | |
Payment N Cash Drawer External Id | string | Payments | No | |
Payment N Type Id | number | Payments | No | |
Payment N Custom Attribute N ID | string | Payments N | No | |
Payment N Custom Attribute N Value | string | Payments N | No | |
Payment N Custom Attribute N Language ID | integerORstring | Payments N | No | |
Custom Attribute ID | string | Attribute Values | No | Attribute to be used as key in the key/value pair (externalId resolvable) |
Custom Attribute Value | string | Attribute Values | No | Value to appear in this key/value pair |
Custom Attribute Language ID | integerORstring | Attribute Values | No | Language ID for the language in which this value appears; use 0 if it is not localized (externalId resolvable) |
Custom Attribute N ID | string | Attribute Values N | No | |
Custom Attribute N Value | string | Attribute Values N | No | |
Custom Attribute N Language ID | integerORstring | Attribute Values N | No |
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.
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 for billing address | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | 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 |
| No | Item Variant ID | Item N Variant ID | ID of the variant of this line item | string |
| No | Item Original Price | Item N Original Price | Original price of this line item (4 decimal places) | number |
| No | Item Paid Price | Item N Paid Price | Price actually paid for this line item (4 decimal places) | number |
| No | Item Tax | Item N Tax | Tax paid for this line item (4 decimal places) | number |
| No | Item Quantity | Item N Quantity | Quantity of this line item purchased (decimal precision: float) | number |
| No | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| Yes* | Total Description | Total N Description | Kind of total this is (e.g. Total, Subtotal) | string |
| Yes* | Total Sort Order | Total N Sort Order | Order in which this total is sorted | integer |
| Yes* | Total Value | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Payment ID | Payment N ID | Identification string for a payment | string |
| No | Payment Amount | Payment N Amount | Amount of this payment (4 decimal places) | number |
| No | Payment Type | Payment N Type | Physical method used to pay (Credit, Debit, Cash, Remote) | string |
| No | Payment Token | Payment N Token | Token representing the payment | string |
| No | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| Yes* | Custom Attribute ID | Custom Attribute N ID | Identifier of the custom attribute | string |
| Yes* | Custom Attribute Value | Custom Attribute N Value | Value of the attribute | string |
| Yes* | Custom Attribute Language ID | 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.
Order History Sample - Multi row
Order History Sample - Multi column