API - Purchase History
Introduction
What is Purchase history and what can I use it for?
In order to get started basic knowledge of Carma’s list and contact management is required. Readers are assumed to have some familiarity with Carma’s graphical interface.
General workflow
- 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 carma UI.
NOTE! The file must not contain a header row. The first row should contain data.
| File Column | Carma Field | Description |
| 0* | Originalid | Your id of the contact the data should be associated with |
| 1* | Sku/column1 | Stock Keeping Unit/custom value |
| 2* | itemPrice | Price of one unit with point (.) for decimals, i.e. 20.50 |
| 3** | Transaction Time | Time in ISO-8601 format; yyyy-MM-dd HH:mm:ss |
| 4** | No of Items | |
| 5 | Total price | itemPrice*noOfItems |
| 6 | Column2 | custom value |
| 7 | Column3 | custom value |
| 8 | Column4 | custom value |
| 9 | Column5 | custom value |
| 10 | Column6 | custom value |
| 11 | Column7 | custom value |
| 12 | Column8 | custom value |
| 13 | Column9 | custom value |
| 14 | Column10 | custom value |
| 15 | Column11 | custom value |
| 16 | Column12 | custom value |
| 17 | Column13 | custom value |
| 18 | Column14 | custom value |
| 19 | Column15 | custom value |
| 20 | Column16 | custom value |
| 21 | Column17 | custom value |
| 22 | Column18 | custom value |
| 23 | Column19 | custom value |
| 24 | Column20 | custom value |
| 25 | Column21 | custom value |
| 26 | Column22 | custom value |
| 27 | Column23 | custom value |
| 28 | Column24 | custom value |
| 29 | Column25 | custom value |
| 30 | Column26 | custom value |
*Mandatory fields
** Not mandatory, but strongly recommended
NOTE! 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)
- 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”
}
- 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.
- 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”
}