Order items
Other languages available for this guide
🇫🇷 La version française de ce guide
🇪🇸 La versión española de esta guía
🇮🇹 La versione italiana di questa guida
This article explains how to prepare files for import in the “ordersitems” scope. Representing individual items in orders or shopping carts, orders items are used to fill the contents of Orders and Abandoned carts.
Records in the “ordersitems” scope can't be updated. Instead, you need to be prepared to reimport all orders items for each “order_id” you update in the “orders” or “abandonedcarts” scope. Updates to these two scopes always result in Splio purging all associated order items (it is one of the initial steps of import).
If you import a new order items file linked to an existing order, it will be added to the existing order items (if there is any).
Prerequisites
- Basic knowledge of the CSV format and UTF-8 encoding.
- A UTF-8-enabled text editor.
- A spreadsheet software.
- The sub-sequence must be defined in the config file under the “orders” scope.
Preparation of an Ordersitems file
Use your favorite spreadsheet software or UTF-8 enabled text editor to prepare and edit the file. Spreadsheet is the recommended tool whenever you need to trim or move columns.
- Always remember to save using the UTF-8 encoding without BOM.
- Please limit the size of your file to 200K objects.
Header and Columns
The first line of the file called the header, is used to determine the content of the following lines. Therefore, it should be constructed only from the names of columns.
Remember that if Splio encounters a column name it cannot recognize, it will skip the file.
| Column | Mandatory | Data Type / Maximum length | Description |
|---|---|---|---|
| order_id | Yes | Text (max. 50 characters) | External identifier of an order, this column binds “ordersitems” to specific “orders” (or “abandonedcarts”); this column is mandatory and should reference an already existing order, otherwise a blank “orders” entry will be created. |
| product_id | Yes | Text | External id of the product on the order or in the shopping cart. This column is mandatory. If the product does not yet exist in the data base, Splio will create a default (empty) record. Updating products does not erase associated orders items. |
| unit_price | No | Decimal | The price charged for a single unit of the product. This field will be the one taken into account for any Loyalty rule based on the price of the product. |
| discount_amount | No | Decimal | The total discount amount. |
| tax_amount | No | Decimal | The total tax amount. |
| total_line_amount | No | Decimal | The total amount for this order line. |
| currency | Yes | Text (max. 3 characters) | three-letter ISO code of the currency in which all prices and amounts are given. If absent the universe’s default is used. |
| quantity | No | Unsigned integer | The quantity of the product. This field will be the one taken into account for any Loyalty rule based on the quantity of the product. |
| card_code | No | Text | the code of a loyalty card, creates a link between the item and the loyalty card. |
| c0 | No | Text (max. 255 characters) | A custom column defined in your universe for orders items. You can include up to 32 columns referred to as “c0” to “c31”. |
- Note that all column names are always lowercase.
- Please remember that Splio checks import files for mandatory columns. You need to include both “order_id” and “product_id” for the import to succeed.
- The “card_code” column is used to bind an order item to a loyalty card code. You can insert it in either “orders” or “ordersitems” files to create loyalty events. However, you must import the card codes with “ordersitems” if you want to use loyalty rules based on products.
- For decimal numbers, you can use either “.” as separator.
Important: when uploading product prices, always include two decimal digits after the separator (dot), as in “10.99”.
Example of an Ordersitems file
Examine the following example of a file containing 3 items which belong to the same order:
order_id;product_id;unit_price;quantity;tax_amount;total_line_amount;currency;c3
"70x1bMhtt-1531745300";"00131300020004";"182.49";"1";"36.50";"218.99";"EUR";"Accessories"
"70x1bMhtt-1531745300";"0027011018374";"9.16";"5";"9.16";"54.96";"EUR";"Food"
"70x1bMhtt-1531745300";"0077890206324";"154.50";"2";"61.80";"370.80";"Accessories"
The fields represent the unique identifier of the order, identifier of the product, its net price, quantity, applied tax, sum total of each line, and a custom category field.
Name your file
When saving your file, use a name composed of the universe name, scope (“ordersitems”), sub-sequence, and current date. For example:
myuniverse_ordersitems_pets_20180712.csv
This filename belongs to the universe “myuniverse”, sub-sequence “pets” defined for orders, and is dated July 12, 2018. Note that this date marks the file, it does not have to correspond to the items.
If you wish to know more, consult the “File Naming guidelines” section in the Overview document.
You can now upload the file to SFTP/FTPS.
Updated 3 months ago