Purchase history setup

First, if you want to learn about the benefits of Purchase history, start here.

​In order to get started basic knowledge of Symplify’s list and contact management is required. Readers are assumed to have some familiarity with Symplify’s graphical interface.

This article will help you through:

 

Prepare your file

In order to start an import you will need to prepare a file. The format of the purchase history data is very strict. It must have this exact format or the import will fail. The delimiter must be semicolon (;) and the columns must have the order specified below. There are some columns that are mandatory and some that are optional. If you want to include optional fields all optional fields prior to you field in the order must be included. The data may be empty, so you can just add semicolons for the intermediate optional fields that you do not want to add. The custom fields can be named for the user in the Symplify UI.

​NOTE! The file must not contain a header row. The first row should contain data.

ph-columns.png

* Mandatory fields

** Not mandatory, but strongly recommended

In order for data in custom fields to be parsed correctly, dates must be formatted in ISO-8601 and prices should be formatted as 000000.00 (decimal point).

The data is append only, so if the same data is imported twice the second import will append, not overwrite the previous import.

Make sure that your file is in a valid CVS format. For instance, you cannot have a single ” in the data ( as in 6″ monitor) in the data as this will make the CVS file invalid.

Setup using FTP file transfer

When your file has been prepared, upload it to your Symplify FTP.
Your contact at Symplify will help you verify the file and finish the set up.

Learn about crediting rows (below).

Setup using API transfer

Batch imports triggered by the API adds an overhead to each included file. You should therefor send larger files less often, rather than smaller files frequently.
Recommended minimum import interval is hourly but a new import should not be initiated until a previous import is done (check the batch status).

If import files are triggered too frequently, the service will respond with a HTTP 429. Your import may also be throttled and placed in queue. In other words, several sequentially imported files will cause an import delay.

Please observe these recommendations to avoid issues.

 

Making the request

After the file has been prepared is it time to make the first request to the API. You will need the ID of the list you want to asssociate the purchase history data with.

After this information have been gathered is it time to make the request. The response, if everything went well, will contain a unique id that will be used later.


To start the import a POST request with metadata describing the import is sent:

POST <server>/rest/<customerId>/purchasehistory/<listid>/imports

Example response body

{“id”: “bd48b5cc-b118-4062-8d06-09efa765592b”}

 

Uploading your data​

After the initial request have been made and an ID have been returned it’s time to upload your data. Use the id obtained in the response of the first request to upload your data:

POST <server>/rest/<customerId>/purchasehistory/<listid>/imports/<id>/data
CONTENT-TYPE: text/csv
<data from file>

 Example response body

{“batchId”: “101111”}

​NOTE! The data is append only, so if the same data is imported twice the second import will append, not overwrite the previous import.

 

Check batch status

When the file has successfully been uploaded you can query the API to trace the imports progress. Use the batchId from the previous request. You can keep polling the method until you receive a response with the status set to “FINISHED”. Do not poll too often as that will put unnecessary strain on the system. Polling once every 30 seconds or every minute is normally sufficient. 

GET <server>/rest/<customerId>/batches/<batchId>

Response body

{
“id”: 101111,
“type”: “IMPORT”,
“customerId”: 0,
“startTime”: 1394636797030,
“endTime”: 1394636799710,
“affected”: 500,
“processed”: 500,
“total”: 501,
“status”: ” PENDING|IN_PROGRESS|FINISHED”
}

Credited rows

A credit row is when the Quantity is a negative number.

When a credit row is imported, the number (Qty) is reduced to zero regardless of how many PH lines it requires.

Example

Orignalid;Sku;Qty
A100;iPhone;2
A100;iPhone;3
A100;iPhone;2

If you then import a credit row with “-3” (Qty) the following is meant to happen:

Orignalid;Sku;Qty
A100;iPhone; (credited)
A100;iPhone;2 (reduced by 1)
A100;iPhone;2

​In other words, lines 1 and 2 is decreased in adjustment to the “-3” in the credit line.

“COLUMN1” is special in the way that, in combination with the column “Transaction Date” it can be used to identify a specific row to set as credited (if count <0). It should then (if you want to be able to handle credit-lines) be a unique product identifier.

​After import a fully credited row is listed in a “blue” color on the recipient contact card.

Credited rows will be neglected by PH segments based on “purchased” rules, and solely targeted by PH segments based on “Credited” rules.

 

Adding purchase history rows with the API


We recommend that you use batch imports for synchronization with multiple purchase history lines. However, for smaller quantities, you can also import purchase history rows with this API resource (Maximum 100 rows at a time) :

POST <server>/rest/<customerId>/purchasehistory/rows


{
"rows":[
{
"originalId": "A100",
"transactionDate": "2020-10-30T10:00:00-04:00",
"itemPrice": "5.00",
"count" : 3,
"totalPrice": "15.00",
"column1": "",
"column2": "",
"column3": "",
"column4": "",
"column5": "",
"column6": "",
"column7": "",
"column8": "",
"column9": "",
"column10": "",
"column11": "",
"column12": "",
"column13": "",
"column14": "",
"column15": "",
"column16": "",
"column17": "",
"column18": "",
"column19": "",
"column20": "",
"column21": "",
"column22": "",
"column23": "",
"column24": "",
"column25": "",
"column26": ""
}
]
}

 

Was this article helpful?
0 out of 0 found this helpful