Emarsys allows you to import sales data of any type, including daily sales files, returns and cancellations, and offline data from your physical stores.

To upload sales data into Emarsys, open your account and go to Admin > Data Sources. 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 new uploads add to existing sales data and do not overwrite them.


Formatting your sales data file

Sales data is expected to be a UTF-8 encoded .csv file (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 describes a single element (one specific item in some quantity and at some total price) of the order. There are a number of standard columns which are necessary for reporting, and you can also add your own custom columns.

Standard columns

Field Required Type Example Description
item Yes String BOOK0012 The unique product identifier, exactly as it appears in the item column of the product catalog.
price Yes Float 110.30 The total price of the order line (the unit price multiplied by the quantity) in the default currency defined in the Account Details box of your Data Sources page.
order Yes String 111-U8 The unique identifier of the order (an order may contain multiple order lines).
timestamp 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. 2016-06-06), then the time is assumed to be 00:00:00.
customer Yes (one of email or customer is needed, but not both) 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 (one of email or customer is needed, but not both) Email example@email.com The email address of the customer making the order, if you identify your customers by email address. Do not use this column if customer is already present. Note that due to privacy concerns, the email addresses in the uploaded historical sales data are stored encoded, so the original email address cannot be restored.
quantity Yes Float 5 Quantity (number) of purchased item(s).

Custom Columns

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 not be empty and may not contain data with the wrong type, otherwise the file will not validate.

Column Name Pattern Type Example Column Name
i_* Integer i_customer_age
f_* Float f_customer_height
t_* Timestamp t_date_of_manufacture
s_* String s_book_author

Field Types

Type Format
Integer Normal integer, no decimal or thousands separator.
Float Uses dot (.) as decimal sign, no thousands separator.
Timestamp Date of the form YYYY-MM-DD or timestamp of the form YYYY-MM-DDTHH:MM:SSZ, e.g. 2016-06-06 or 2016-06-06T14:02:00Z. If only a date is specified, the time is assumed to be 00:00:00.
String Optionally quoted string, ", To escape a quote character within a field, double it: "".
Email Email address format, eg: example@email.com

Sales Data Examples

The following example shows orders for a shoe store with two custom columns:


Uploading sales data manually

Once you are sure that your file containing your sales data has been correctly formatted as described above, you should upload it through the Sales Data page. It is safe to submit the same file multiple times, as this will not result in duplicate data.

A manual upload is the preferred method for uploading data such as 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 sales 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:


Using the sales data API

The easiest way to import sales data regularly to Emarsys is to use our simple HTTP API endpoint. The Sales Data page provides on-screen documentation and code samples so you need only minimal effort to set up the import.

The sales data should be uploaded by issuing a POST request to the following endpoint:

  • https://admin.scarabresearch.com/hapi/merchant/<merchant-id>/sales-data/api

<merchant-id> represents your 16-letter merchant ID provided by Emarsys. The request should contain an Authorization header with the following value:

  • Bearer <token>

<token> is a security token, which can be obtained by clicking on the Show API upload details button.

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.