Contents
Making your initial upload
If you are a Smart Insight customer, you can still choose to upload your sales data to our SFTP servers. Please note, however, that this is a legacy option that has several disadvantages compared to using the Sales Data API. If you still prefer to use our SFTP, please contact Emarsys Support.
Once your sales data file is ready and formatted as per our specifications, upload it through the Sales Data page.
To open the Sales Data page, go to Admin > Data Sources, and in the Sales Data box click either Set up sales data uploads (if this is your file upload) or Manage sales data (if you have already uploaded at least one sales data file).
Duplicate data
- If you upload the same file here more than once, this will not result in duplicate data if the file name does not change.
- If you upload the same file with a different name (e.g. an updated timestamp), or upload different files containing the same orders, then the data will be duplicated.
The columns in the header of your sales data file must be in the order that was agreed during the Smart insight onboarding implementation. If they are not, the upload will fail.
The columns are displayed in order at the top of the Sales Data page, for example:
Manual upload via the Sales Data page is the preferred method for making your initial upload of 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.
- If issues are detected, they will be listed as warnings and errors. Fix them and try the upload again.
- If no issues are detected, finalize the upload by clicking Activate upload.
You will not be able to upload your sales data file as long as it contains errors; you must fix these first.
Setting up regular updates
If you are a Smart Insight customer, you can still choose to upload your sales data to our SFTP servers. Please note, however, that this is a legacy option that has several disadvantages compared to using the sales data API. If you still prefer to use our SFTP, please contact Emarsys Support.
Once you made a single upload of your historical sales data, you need to set up regular updates. The easiest way to automate regular sales data imports to Emarsys is to use our Sales Data API.
Open the Sales Data page by going to Admin > Data Sources, in the Sales Data box click Manage sales data. Then click Show API upload details, which will display all information you need to set up the import with minimal effort.
Sales data uploads are incremental, meaning new uploads add to existing sales data and do not overwrite them.
Duplicate data
There are two workarounds to fix this issue:
- Split the content of the file into 2 files and upload them again, or
- Duplicate one of the lines in the file and upload it again.
Any of these workarounds will result in duplicate data in Smart Insight. To solve this problem, you have to purge the Smart Insight database and upload your clean historical sales data again.
Sales Data API specifications
Endpoint
POST https://admin.scarabresearch.com/hapi/merchant/<merchant-id>/sales-data/api
Path parameters
| Name | Type | Description |
|---|---|---|
| merchant-id | string | Your 16-letter merchant ID provided by Emarsys. |
Header parameters
The request should contain an Authorization header with the following value:
Bearer <token>
<token> is a security token, which can be obtained by clicking the Show API upload details button on the Sales Data page.
Request body
You must upload the sales data .csv file as a binary (data-binary) payload in the request body. See Formatting your sales data file for details about the accepted format.
Request example (curl)
curl --request POST \
--header 'Authorization: Bearer <token> \
--header 'Content-type: text/csv' \
--header 'Accept: text/plain' \
--data-binary @/myhome/salesdata-2018-03-26.csv \
https://admin.scarabresearch.com/hapi/merchant/<id>/sales-data/api
Live streaming
By default our servers bundle, validate and submit the events in hourly batches. If the API is not called after each purchase event in a separate request (nor more often than every 5 minutes), you can append the parameter ?live=false to the endpoint URL. As a result, sales data will be processed more frequently than once per hour.
Compression
Gzip compression is supported. To upload gzip compressed files, use the Content-Encoding: gzip header.
Responses
| HTTP Code | Message |
|---|---|
| 200 | Upload is accepted (with possible warnings). |
| 200 | Event(s) queued by Live API. See the status within one hour at Emarsys > Admin > Data Sources > Sales Data |
| 400 | Upload is rejected due to errors. |
| 401 | Security token is invalid or missing. |