Skip to main content
All CollectionsData TransferCSV Format by X-Cart Data Type
CSV Import: Orders
CSV Import: Orders

The format and the fields description for orders import.

A
Written by Anna Verbichenko
Updated over 6 months ago

The orders import feature is a part of the free Orders Import add-on. It is not included in the X‑Cart core.

An orders CSV file for import must have the name orders-xxxxxx.csv, where the part -xxxxxx can be anything you want or can be omitted.

Examples of correct product CSV file names:

  • orders.csv;

  • orders-13-01-01.csv;

  • orders-from-my-provider.csv

Below is a list of supported fields and their respective value types for category import.

Fields supported by the Orders Import add-on

Field in CSV file

What this field describes

Value type

orderNumber*

Order number. Serves as an identifier.

Integer

customerEmail*

The email of a customer who placed the order.

String

Customer billing address fields. The following address fields might or might not be present in your X-Cart installation depending on your address fields configuration.

Field in CSV file

What this field describes

Value type

customerAnonymous

If Yes, the customer is an anonymous person (guest).

Yes/No

customerAddressSame

Use "Yes" if the customer billing and shipping addresses are the same; otherwise, use "No."

Yes/No

customerFirstnameBillingAddressField

Customer first name in the billing address.

String

сustomerLastnameBillingAddressField

Customer last name in the billing address.

String

customerStreetBillingAddressField

Customer street in the billing address.

String

customerCityBillingAddressField

Customer city in the billing address.

String

customerCountryCodeBillingAddressField

Customer country code (ISO 3166-1 alpha-2 format (2 characters)) in the billing address.

String,
Max. length: 2

customerStateIdBillingAddressField

Customer state name if X-Cart has a defined state for the customer. Otherwise, use customerCustomStateBillingAddressField.
Example: Oklahoma

String

customerCustomStateBillingAddressField

Сustomer state name in the case X-Cart does not have a defined state for the country

String

customerZipcodeBillingAddressField

Customer zip code in the billing address

String

customerPhoneBillingAddressField

Customer phone number in the billing address

String

customerVatNumberBillingAddressField

Customer VAT number in the billing address. Requires the VAT add-on to be installed.

String

Customer shipping address fields. The following address fields might or might not be present in your X-Cart installation depending on your address fields configuration.

Field in CSV file

What this field describes

Value type

customerFirstnameShippingAddressField

A customer first name in the shipping address

String

customerLastnameShippingAddressField

Customer last name in the shipping address

String

customerStreetShippingAddressField

Customer street in the shipping address

String

customerCityShippingAddressField

Customer city in the shipping address

String

customerCountryCodeShippingAddressField

Customer country code (ISO 3166-1 alpha-2 format (2 characters)) in the shipping address

String,
Max. length: 2

customerStateIdShippingAddressField

Customer state name if X-Cart has a defined state for the customer. Otherwise, use customerCustomStateShippingAddressField.
Example: Oklahoma

String

customerCustomStateShippingAddressField

Customer state name in the case X-Cart does not have a defined state for the country

String

customerZipcodeShippingAddressField

Customer zipcode in the shipping address

String

customerPhoneShippingAddressField

Customer phone number in the shipping address.

String

customerVatNumberShippingAddressField

Customer VAT number in the shipping address. Requires the VAT add-on to be installed.

String

Order item fields. Each field is a Multirow field, and each row represents one specific product.

Field in CSV file

What this field describes

Value type

itemName*

Order item name

String,
Multirow

itemSKU*

Order item SKU

String,
Multirow,
Max. length: 32

itemAttributes

Order item product attributes

Multiple,
Multirow

itemPrice*

Order item selling price

Float,
Multirow

itemQuantity*

Quantity of items included in the order

Integer,
Multirow

itemSubtotal*

Order item subtotal value (without order item surcharges).

Float,
Multirow

itemTotal*

Order item total value

Float,
Multirow

subtotal*

Order subtotal (without order surcharges)

Float

Order surcharges. Each surcharge field consists of UPPERCASED surcharge code and (surcharge) suffix. The following two fields are examples of the general order surcharges and may or may not be present in your X-Cart installation.

Field in CSV file

What this field describes

Value type

DISCOUNT (surcharge)

Order discount surcharge in an absolute value. Example: -3. This example value stands for a $3.00 discount if the order currency is USD.

Float

SHIPPING (surcharge)

Order shipping surcharge. Example: 3.02.

Float

total*

Order total with surcharges included

Float

currency*

Code of the order currency. Example: USD.

String,
Max. length: 3

shippingMethod

Order shipping method name

String

trackingNumber

Order tracking number

String

Order payment transactions. The following fields prefixed by 'paymentTransaction' are Multirow, and each row represents a single payment transaction. Thus, an order should have at least one payment transaction.

Field in CSV file

What this field describes

Value type

paymentTransactionMethod*

Order payment transaction method internal name

String

paymentTransactionStatus*

Order payment transaction status.
Possible values are:

  • 'I' (Initialized)

  • 'P' (In Progress)

  • 'S' (Success)

  • 'W' (Pending)

  • 'F' (Failed)

  • 'C' (Canceled)

  • 'V' (Void)

String,
Max. length: 1

paymentTransactionValue*

Order payment transaction value

Float

paymentTransactionNote

Order payment transaction processor note. Generally contains errors from the payment processing.

String

paymentTransactionType*

Order payment transaction type.
Possible values are:

  • 'auth' (Only authorize)

  • 'sale' (Authorize and capture)

  • 'capture' (Capture payment)

  • 'capturePart' (Capture payment part. Transaction is closed afterward)

  • 'captureMulti' (Capture payment part. Can be repeated)

  • 'void' (Cancel payment)

  • 'voidPart' (Cancel payment part. Transaction is closed afterward)

  • 'voidMulti' (Cancel payment part. Can be repeated)

  • 'refund' (Refund payment)

  • 'refundPart' (Refund payment part. Transaction is closed afterward)

  • 'refundMulti' (Refund payment. Can be repeated)

String

paymentTransactionId*

Order payment transaction public id

String

paymentTransactionCurrency

Order payment transaction currency. Can be omitted; order currency will be used instead.

String

date

Order creation date. Example: Tue, 12 Jan 2016 13:18:22 +0000

String

recent

Use "Yes" if the admin has processed the order; otherwise, use "No."

Yes/No

paymentStatus*

Order payment status.
Possible values are:

  • 'A' (Authorized)

  • 'P' (Paid)

  • 'PP' (Partially paid)

  • 'D' (Declined)

  • 'C' (Cancelled)

  • 'Q' (Queued)

  • 'R' (Refunded)

String,
Max. length: 3

shippingStatus*

Order shipping status.
Possible values are:

  • 'N' (New order)

  • 'P' (Processing)

  • 'S' (Shipped)

  • 'D' (Delivered)

  • 'WND' (Will not deliver)

  • 'WFA' (Waiting for approval)

  • 'R' (Returned)

String,
Max. length: 3

notes

Order customer notes

String

adminNotes

Order administrator notes

String

Order history details. The following fields prefixed by 'detail' are Multirow, and each row represents a single history item.

Field in CSV file

What this field describes

Value type

detailCode

Order history item code

String

detailLabel

Order history item human-readable label

String

detailValue

Order history item text

String

Fields added by the Multivendor add-on

Field in CSV file

What this field describes

Value type

vendor*

Order vendor email.

String

parent*

Parent order ID.
The field is defined for X-Cart Multivendor in the "Vendors as separate shops" mode.

Integer

children*

Child order numbers. Can be multiple.
The field is defined for X-Cart Multivendor in the "Warehouse" mode.

Integer,
Multiple

commissionValue

Vendor commission value.

Float

commissionStatus

Vendor commission status. Possible values are:

  • 'N'- not paid;

  • 'P' - paid.

String

commissionTaxesOwner

The collector of a sales tax (admin or vendor) based on the setting "Sales tax is the responsibility of".

String

Fields added by the Custom Order Statuses add-on

Field in CSV file

What this field describes

Value type

paymentStatusLabel

Human-readable translation of the payment status

String,
Multilingual

shippingStatusLabel

Human-readable translation of the shipping status

String,
Multilingual

Fields added by the Loyalty Program add-on

Field in CSV file

What this field describes

Value type

REWARDPOINTS (surcharge)***

Order TOTAL discount surcharge in an absolute value added by the Loyalty Programm add-on settings. Example: -3. This example value stands for a $3.00 discount if the order currency is USD.

Float

REWARDPOINTSSUB (surcharge)***

Order SUBTOTAL discount surcharge in an absolute value added by the Loyalty Programm add-on settings. Example: -3. This example value stands for a $3.00 discount if the order currency is USD.

Float

* Required field.

** See CSV Field Notices for more info.

*** Depending on the Loyalty Program add-on settings, you can define the values either for REWARDPOINTS (surcharge) or for REWARDPOINTSSUB (surcharge). Not for both of them at the same time.

Tips:

  • If you are going to import data into X-Cart and do not wish to update certain X-Cart fields during the import process, you should not include these fields in your CSV file for import. Instead, simply remove the respective column(s) from the file.

Related pages:

Did this answer your question?