Before you start

Things you need to know:

We advise that the file name contain transaction to be easily recognized as a transaction file.
The order_id field contents must be sequential as in the below example:

order_id,product_id,item_name,item_price,qty,cart_price,cart_price_including_tax,cart_price_excluding_tax,order_date,email,curr
4056046,861838,Drawer Lock 19 x 22mm Chrome Plated Keyed Alike Differ 1,8.1,2,122.9,147.48,122.9,08/04/2015 09:51,peter.duck@domain1.com,GBP
4056046,651826,Legge 5 Lever Sashlock Stainless Steel Case Size 64mm Backset 44mm,22.5,1,122.9,147.48,122.9,08/04/2015 09:51,peter.duck@domain1.com,GBP
4056047,969754,Exidor 305 Panic Mortice Actuator,72.5,1,72.5,87,72.5,08/04/2015 09:52,nancy.blackett@domain2.com,GBP

Supported file formats are TSV and CSV.
We recommend that data should be encoded as utf-8, however ucs-2 can also be used. If all the characters in your data can be represented in the first 127 characters, then you can use US-ASCII (sometimes called ANSI).

Fields and field mapping

Currently, only email and eid need to be specified in the field mapping.

Only the field names below are used for transaction files. By default, you should use exactly the field names specified. However, you can also specify other field names for the FTP file using the field mapping JSON.

Required fields:	Description
order_id	If omitted for a record, the record is treated as being part of the same cart as the previous record.
email*	Email address associated with the transaction. Required if a Customer ID is not provided.
cid*	Customer identifier associated with the transaction. Required if an email address is not provided.
product_id	Unique ID of the product for that line item in the transaction. This should be the same ID used by Fresh Relevance to capture data from the website.
order_date**	Date of the transaction.
cart_price	Total cost of the transaction, including delivery and any VAT. This must be a numeric value only. Do not include currency symbols.
qty	Quantity of the product for that line item in the transaction.
curr	Currency code associated with the `cart_price` used by the transaction, for example, GBP.
sbr	Site Brand or Product Set associated with the transaction. Only required if your account supports multiple sites. Contact Support if you’re unsure if this is required.
lang	Language associated with the transaction. Only required if your account supports multiple languages. Contact Support if you’re unsure if this is required.
Optional fields, but required for the transaction data to be used in recommendations	Description
item_price	Price of the product for that line item in the transaction.
item_name	Name of the product for that line item in the transaction.
Optional fields	Description
cat	List of product categories associated with that line item in the transaction. You must use a `list_separator` for this field if more than one category is supplied in the same field.
variant_id	The SKU-level variant ID. The specific variant (vid) that was purchased.
opt	Product Option variable data, for example, selected product colour.
ex	Cart Extra custom data, for example, the cart type or delivery cost.
return_reason	If a `return_reason` is specified then this transaction is treated as a return. This means a Return Purchase signal is raised instead of a Purchase. In this case, either the original `order_id` value or a new `order_id` value can be used.

* All transaction import records must contain either an email address (email) or Customer ID (customer_id), but may contain both.

**order_date must be in a recognized format. The following formats are supported:

25/04/2012 14:14

5/4/2012 14:14

8/Apr/2015 09:59

25/04/2012

25/04/2012 14:14

Thu, 19 Apr 2012 11:20:33 GMT +01:00

4 Oct 2012 08:45:35

2012-02-22T11:47:34.874Z

2012-02-22T11:47:34Z

2012-02-22T11:47:34.874

2017-06-30 14:16:02.997

2012-02-22

Example

A sample import file with multiple categories.

Mapping file:

Unmapped fields which are supported are imported with the name specified in the file header.

{"email":{"ftp_field_name":"email"},"cat":{"ftp_field_name":"cat", "list_separator":","}, "item_name":{"ftp_field_name":"item_name_2"}}

Sample file:

"order_id","email","product_id","item_name_2","qty","item_price","cart_price","order_date","cat"
"1000001","address1@example.com","P001F2","Product Name 1","1","£6.99","£11.98","2017-07-23","A,B,C"
"1000002","address1@example.com","K006M3","Product Name 2","1","£4.99","£11.98","2017-07-23","D,B,C"
"1000003","address2@example.com","T014M1","Product Name 3","1","£7.80","£18.90","2017-07-12","D,B,C"
"1000004","address2@example.com","P001F7","Product Name 4","1","£11.10","£18.90","2017-07-12","E,B,C"

Configure the FTP retrieval

Before you start

All files in the FTP directory which match the allowed files pattern you specify are retrieved, processed and deleted from the FTP server. Therefore, the FTP account used requires read, write, and delete permissions.
To avoid confusion with other import processes which are reading from the same FTP server, we recommend that you use separate sub-directories.

To set up a transaction data import:

Expand the User menu and go to Settings > Imports.
Select Transaction Import Channels.
Expand the drop-down menu and select FTP, then select NEXT.
Enter the details for:
- FTP Type
  Only SFTP and FTPes protocols are supported to protect your data and ensure privacy. Regular FTP is not supported.
- FTP Host
- FTP Port
- FTP User Name
- FTP Password
- FTP Directory
- FTP Allowed Files Pattern
- FTP Access Interval
- FTP Field Mapping
- Polling Interval
Optionally, select the Is Service Paused? checkbox to stop the processing of this import job. Clear the checkbox to restart it.
To receive an alert if the import job encounters an error, enter an email address in the Error Alert Email field.
Separate multiple email addresses with a comma. Leave blank to receive no notifications.
Expand the Update Product Database drop-down menu and select from:
1. Always update
2. Only update if product doesn’t exist
3. Never update
Select SAVE.

Import returned products

It’s possible to use the transaction import to upload products a customer has returned by specifying a value in the return_reason column of the import file.

Example field mapping:

{"email":{"ftp_field_name":"email"},"return_reason":{"ftp_field_name":"reason"}}

Example file contents:

"order_id","email","product_id","qty","item_price","cart_price","order_date","reason"
"1000001","address1@example.com","P001F2","1","£6.99","£11.98","2017-07-23","faulty"

After an import for a returned product has completed, the below actions are carried out by the system:

A Return Purchase signal containing the returned product is added to the person record and can be viewed in the person report.
A Return Purchase signal containing the returned product is output through Firehose, if this is enabled in your account.
Returned products can be excluded from displaying in Recommendation SmartBlocks using the Exclude Recent Activity filter.
The returned product is removed from crowd-sourced purchased products data sources used by Recommendation SmartBlocks and product-based reports.
The returned product is removed from product-based person analytics data.

Import person data

Import product data

Import review data

Export data with the Firehose

Create Custom data tables