To upload historical sales data, and to keep your sales data synchronized, open your Emarsys account and go to Admin > Data Sources and in the SALES DATA box, click Manage sales data. This will take you to the Sales data page.
Here you can upload your sales data manually or through an HTTP API. Sales data uploads are incremental, meaning newer uploads add to existing sales data and do not overwrite them.
- Formatting your sales data file
- Uploading your historical sales data
- Keeping your sales data synchronized
Formatting your sales data file
Sales data is expected to be a UTF-8 encoded .csv file, similar to the product catalog (if you are not sure how such file should look, a sample file can be downloaded at the bottom of this page). Each record in the file is an order line which should correspond to a single item purchased. There are a number of standard columns which are necessary for reporting, and you can also add your own custom columns.
||Yes||String||BOOK0012||The unique product identifier, exactly as it appears in the
||Yes||Float||110.30||The total price of the given items (the unit price multiplied by the quantity) in the currency defined in the Account Details box of your Data Sources page.|
||Yes||String||111-U8||The unique identifier of the order (an order may contain multiple order lines).|
||Yes||Timestamp||2016-06-06T14:02:00Z||The date (and optionally the time) of the transaction (in UTC timezone). If only the date is specified (e.g.
||Yes (one of
||String||12343-14B||The anonymous unique identifier of the customer making the order, if your CRM uses one. This must be an external key pointing to the externalID field in your Emarsys database.|
||email@example.com||The email address of the customer making the order, if you identify your customers by email address. Do not use this column if
||Yes||Float||5||Quantity (number) of purchased item(s).|
There may be optional custom columns in addition to the standard columns specified. Custom column names have a single character prefix which denotes their type, followed by an underscore (
_) and the name of the custom column. Custom columns may be empty. However, if they contain data with the wrong type, the file will not validate.
|Column Name Pattern||Type||Example Column Name|
|Integer||Normal integer, no decimal or thousands separator.|
|Float||Uses dot (
|Timestamp||Date of the form YYYY-MM-DD or timestamp of the form YYYY-MM-DDTHH:MM:SSZ, e.g.
|String||Optionally quoted string,
|Email address format, eg: firstname.lastname@example.org|
Sales Data Examples
The following example shows orders for a shoe store with two custom columns:
item,price,order,timestamp,customer,quantity,s_color,f_size,t_published 103-nike-1,24.95,112343,2016-06-06T14:02:00Z,093275854,1,blue,14.5, 105-adidas-66,99.95,112343,2016-06-06,493027334,3,black,14.5,2016-09-20T15:00:00Z 107-nike-24,50.99,66234,2016-06-06T17:00:00Z,672985375,1,pink,13.5,2016-08-01
Uploading your historical sales data
Once you are sure that your file containing your sales data has been correctly formatted as described above, you should upload it through the Data Sources page. It is safe to submit the same file multiple times, as this will not result in duplicate data.
You can also use the API for the initial upload (see below), but a manual upload is the preferred approach to uploading historical sales data during the onboarding process, as it allows you to validate the file and correct any errors straight away. Proceed as follows:
- On the Sales data page, click Validate/upload file.
- Browse for your historical data file and select it.
- Emarsys will first validate your file and then upload it.
If there were problems validating the file, the warnings and errors will be visible immediately:
Keeping your sales data synchronized
Once you have made your initial upload, the Web Extend scripts will keep Emarsys synchronized with the daily activity of your webshop, but you will still need to set up a schedule for any other sales data not tracked by them. This could include returns and cancellations, as well as offline data from your physical stores. We have provided a simple HTTP API for you to do this.
The sales data should be uploaded by issuing a POST request to the following endpoint:
<merchant-id> represents your 16-letter merchant ID provided by Emarsys. The request should contain an
Authorization header with the following value:
<token> is a security token, which can be obtained by clicking on the Show API upload details button on the Sales Data page, which you can access from the Data Sources page.
The response will have an HTTP status code of 200 if the upload was accepted (possibly with warnings), and 400 if the upload was rejected because the format or content of the sales data was invalid. The detailed error and warning messages can be seen on the Sales Data page, which you can access from the Data Sources page. If the security token was invalid or missing, a response with 401 status will be returned.
- Here you can download a sample sales data import file.