Fresh Relevance can load product data from a file which you place on

an SFTP server
an Amazon S3 bucket
a web server that can be accessed through HTTPS.

We also have a product import API which allows you to import your product data through JSON requests.

For example, the following file could be used:

"id","color","curr","price","monthly_price","deal_code","img","url","stock","name","categories"
"54321","green","GBP","34.99","32.49","201802deals","http://example.com/image.jpg","http://example.com/prods/54321","1","Test Product","Mens>Formal Wear>Jackets"

Before you start

Things you need to know:

We advise that the file name contain product to be easily recognized as a product file.
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).

SFTP and AWS Buckets

Only SFTP and FTPes protocols are supported to protect your data and ensure privacy. Regular FTP is not supported.
All files in the ftp directory which match the allowed files pattern 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.

HTTPS import

Only HTTPS protocols are supported to protect your data and ensure privacy. Regular HTTP is not supported.
When importing through HTTPS, files are automatically reimported when they change.
Fresh Relevance requests the file through HTTP. If the ETag header is returned, the file is only be downloaded where this indicates changes.
If the server doesn’t support ETag headers, or it indicates no change, the full file is downloaded. The file contents are then hashed and compared with the previous version which was downloaded. If this hash is different, then the whole file is imported.

Field mapping and data

To configure Product import field mapping:

Expand the User menu and go to Settings > Imports.
Select Product Import Channel.

The mapping file will look something like this:

{
  "prid": {
    "ftp_field_name": "id",
    "field_type": "int"
  },
  "ex.color": {
    "ftp_field_name": "color"
  },
  "curr": {
    "ftp_field_name": "curr"
  },
  "uv": {
    "ftp_field_name": "price",
    "field_type": "double"
  },
  "ex.monthly_price": {
    "ftp_field_name": "monthly_price",
    "field_type": "double"
  },
  "promo": {
    "ftp_field_name": "deal_code",
    "list_separator": ">"
  },
  "img": {
    "ftp_field_name": "img"
  },
  "u": {
    "ftp_field_name": "url"
  },
  "stock": {
    "ftp_field_name": "stock",
    "field_type": "int"
  },
  "n": {
    "ftp_field_name": "name"
  },
  "cat": {
    "ftp_field_name": "categories",
    "list_separator": ">"
  }
}

Multiple categories can be imported to the field cat provided the list_separator is used. Promotion codes can be imported to the field promotion using the list_separator.

Fields with a mapping containing a list_separator attribute are split based on the separator. For example, list_separator":" is treated as a CSV file.

Quotes and spaces are not permitted within this field.

The data can be loaded as a specific data type using the field_type attribute. Allowed values of field_type are:

Value	Description
int	Integer values such as stock level.
double	Non-integer values such as prices.
datetime	Date, for example, `2014-12-02T13:27:00.00Z`
bool	Boolean value. Supported values are yes/no, 1/0, and true/false. Values are not case sensitive.
stock	Converts in stock or yes to 1, and other values to 0. Not case sensitive.
json	Maps `{"key":"value"}` to a dictionary or nest of dictionaries.
jsonpricelist	Allows for the import of json-based customer group price lists. Requires the B2B module.

Normally, empty fields in the import file are loaded and overwrite any existing data in the field. If you want to keep existing data when no data is supplied in the import file, you can set a mapping attribute of "ignore_blank":true. This field is then only loaded if non-blank data is supplied in the file.

Required fields*	Description
product_id	Must use the same coded values as used by Fresh Relevance to capture data from your website.
Optional Fields	Description
n	Name.
qty	Quantity.
img	Image URL.
u	Product page URL.
up	Unit price.
curr	Currency, for example, GBP or USD.
sbr	Site brand of the product. For sites that support this.
lang	Language of the product using international language codes, for example, `en` or `nl`. For sites that support this.
ex.color	Item color. You can access any attribute of `ex` in this way.
cat	Separated list of categories for this product. You can set the separator character used in the field mapping.
promo	Separated list of promotional flags for this product. You can set the separator character used in the field mapping.
related	Separated list of product IDs related this product. You can set the separator character used in the field mapping.

*If you want to update existing product data, then sbr, curr and lang fields may also be required, if your account is set up to support any of these values. You can see what site brands, currencies and languages your account uses in the corresponding report page. To view this, go to Reports> All Reports > System Data > Currencies, Tags, Site Brands and Languages.

Not including these three values may result in the creation of new products, instead of updating products. If your account has multiple site brands, languages, or currencies, then you must supply data for each sbr/curr/lang combination for all products to be updated.

Import product tag values

There's special support for uploading tag values (categories) for each product. These can be used for many purposes, including in Recommendation SmartBlock filters to only show products with particular tag values.

Sample file

product_id,category
002119041012032,mens|trousers|clothing

Sample product import field mapping

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "cat": {
    "ftp_field_name": "category",
    "list_separator": "|"
  }
}

Any existing tag values (categories) for the product are cleared when you upload new tag values to that product.

Import product tag values from multiple fields

You can import tag values from more than one field.

Sample file

product_id,category_a,category_b
002119041012032,mens|trousers|clothing,adults

These can all be loaded into tag values using the following field mapping.

The :1, :2 etc. aren't used - they just make the dictionary keys unique.

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "cat:1": {
    "ftp_field_name": "category_a",
    "list_separator": "|"
  },
  "cat:2": {
    "ftp_field_name": "category_b",
    "list_separator": "|"
  }
}

After the upload, the product has the following tag values:

mens,trousers,clothing,adults

Import product tag groups

You can also import tag values (categories) with tag groups. Tag groups are useful if you want to group tag values together, for example, if you want to pick the style of clothes that a shopper browses most often you could have a tag group called Style, and within that, tag values such as casual, lingerie, formal, and so on. To import tag values for more than one tag group, use a separate field in the input file for each tag group.

Sample file

prod_number       CategoryStyle       CategoryFit        currency_symbol
002119041012032   Casual|Lingerie     Loose|Generous     EUR

Sample product import field mapping

{
  "prid": {
    "ftp_field_name": "prod_number"
  },
  "cat:1": {
    "ftp_field_name": "CategoryStyle",
    "list_separator": "|",
    "category_group": "style"
  },
  "cat:2": {
    "ftp_field_name": "CategoryFit",
    "list_separator": "|",
    "category_group": "fit"
  },
  "curr": {
    "ftp_field_name": "currency_symbol"
  }
}

:1, :2 etc. aren't used - they just make the dictionary keys unique as tag values always go to the field cat.

To replace the existing value of a tag group through the product import, you can include the replace_category_group field in the specific mapping as true. This replaces all existing values in that tag group with the imported value.

This could be useful for indicating clearance items, as these are either going to be Yes or No, but never at the same time. Including the replace ensures only one of these tag groups is present at a time.

Sample file

prod_number        CategoryClearance      CategoryFit      currency_symbol
002119041012032    Yes                    Loose|Generous   EUR

Sample product import field mapping

{
  "prid": {
    "ftp_field_name": "prod_number"
  },
  "cat:1": {
    "ftp_field_name": "CategoryClearance",
    "category_group": "clearance",
    "replace_category_group": true
  },
  "cat:2": {
    "ftp_field_name": "CategoryFit",
    "category_group": "fit",
    "replace_category_group": true
  },
  "curr": {
    "ftp_field_name": "currency_symbol"
  }
}

Import Google Shopping price fields

Fields containing Google Shopping prices can be imported using the google_currency_field attribute.

For example, the following is an extract from a typical Google shopping feed:

prid                     google_price
"002119041012032"        14.99 GBP

This can be imported and split into two separate fields: uv and curr with the following field mapping:

{
  "prid": {
    "ftp_field_name": "prid"
  },
  "uv": {
    "ftp_field_name": "google_price",
    "google_currency_field": "uv"
  },
  "curr": {
    "ftp_field_name": "google_price",
    "google_currency_field": "curr"
  }
}

After the import, uv contains the numeric price and curr contains the currency.

Import fixed values

Fixed values can be imported using the val attribute in the field mapping.

Every record that’s imported has this fixed value set. Here’s an example of a field mapping which sets every imported product to have extend.imported set to yes:

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "up": {
    "ftp_field_name": "item_price"
  },
  "extend.imported": {
    "val": "yes"
  }
}

Import promotion flags

There's special support for uploading flags. These can be used in Recommendation SmartBlock filters to only show products with particular flags. For example, you could use flags for onoffer, new ,or instock.

Sample file

prod_number,promo
002119041012032,FiftyFifty|NewArrival|20150617Sale

Sample product import field mapping

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "promo": {
    "ftp_field_name": "promo",
    "list_separator": "|",
    "ignore_blank": true
  }
}

Any existing promotion flags are cleared when you upload new flags to the promotion flags field for that product.

Import promotion flags from multiple fields

You can upload promotion flags from more than one field to have the system merge them together.

For example, if you have a pipe-separated data file with two fields containing promotion codes. Each promotion code is comma-separated.

promo_a|promo_b
flag1,flag2|flag3

These can all be loaded into the promo field using the following field mapping:

The :1, :2 etc. aren't used - they just make the dictionary keys unique.

{
  "promo:1": {
    "ftp_field_name": "promo_a",
    "list_separator": ","
  },
  "promo:2": {
    "ftp_field_name": "promo_b",
    "list_separator": ","
  }
}

After the upload, the promo field contains:

flag1,flag2,flag3

Import related products

You can upload related products to a product record, and the system associates these Product IDs to the parent product. The related products inherit any Site Brand, Currency and Language that the parent product has. These can then be used by SmartBlocks to load these the corresponding full products.

related_ids
prid123|prid456|prid789

These can then be loaded into the related field using the following field mapping:

{
  "related": {
    "ftp_field_name": "related_ids",
    "list_separator": "|"
  }
}

To import a variant as a related product use .. to separate the prid from the variant ID. For example:

related_ids
prid123..variant1|prid456..variant2|prid789..variant3

Learn more in the section Related products - Advanced control.

Import SKU-level Product Variants

Learn more about Product Variants.

It’s also possible to upload multiple SKU-level variants of the same product. This is done by first including the base product, which is where all the shared data values are stored, then each variant can be included one row at a time.

The variant is identified by the Variant ID (vid) value, which can be any string but must match what is captured by the script. If a row in the imported CSV does not contain a vid field then it’s treated as the base product, if it does have a vid then that row’s data is loaded into a variant.

To enable this, the import field mapping should map the Variant ID (vid) field along with the prid, sbr and curr.

Example variant import field mapping

{
    "prid": {"ftp_field_name": "product_id"},
    "vid": {"ftp_field_name": "variant_id"},
    "up": {"ftp_field_name": "item_price"},
    "n": {"ftp_field_name": "item_name"},
    "stock": {"ftp_field_name": "stock", "field_type": "int"},
}

The imported CSV file should then specify each variant on it's own row. The below example shows importing the base product followed by two color variants. Both variants have no price defined so they inherit this from the base product, but they do have a different name and stock level.

Example CSV product variant import file

"product_id","variant_id","curr","item_price","item_name","stock"
"54321",,"GBP","34.99","Test Product",
"54321","blue","GBP",,"Test Product (Blue)","0"
"54321","pink","GBP",,"Test Product (Pink)","1"

This results in two variants being created. The resulting variants from importing this file are shown below. The product name (n) and stock is different for each variant but the price (uv) is inherited from the base product:

[
    {
        "prid": "54321",
        "vid": "blue",
        "curr": "GBP",
        "n": "Test Product (Blue)",
        "uv": 34.99,
        "up": "£34.99"
        "stock": 0
    }, {
        "prid": "54321",
        "vid": "pink",
        "curr": "GBP",
        "n": "Test Product (Pink)",
        "uv": 34.99,
        "up": "£34.99"
        "stock": 1
    }
]

Import multiple price lists

Requires the B2B module.

A customer group is a code which defines which set of prices are seen by each person. Several prices are imported for the products, for example:

Base price: £26.99
- groupA: £23.99
- groupB: £24.99
- groupC: £25.99

These prices are imported into the product and a corresponding code is imported to the field person.cg to tell the system that that person should see the price for their customer group.

To enable this the import field mapping should map the customer group price list (cg_prices) field. It should have a field_type of jsonpricelist.

Example variant import field mapping

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "up": {
    "ftp_field_name": "item_price"
  },
  "n": {
    "ftp_field_name": "item_name"
  },
  "stock": {
    "ftp_field_name": "stock",
    "field_type": "int"
  },
  "cg_prices": {
    "ftp_field_name": "pricelist",
    "field_type": "jsonpricelist"
  }
}

The imported CSV file must contain a JSON pricelist in that field.

Example TSV product variant import file

"product_id"  "curr"   "item_price"   "item_name"   "stock"    "pricelist"
"54321"       "GBP"    "34.99"        "Test Product"{"VIP": {"uv": 10, "ruv": 15}, "NORMAL": {"uv": 13, "ruv": 16}}

Learn more in Import Person Data.

Import review IDs

If you’re using the Social Proof module, it’s also possible to import the product review key used by your ratings and reviews provider into a product review ID (rid) field, if neither the product ID or SKU values are suitable for this purpose.

Example product review ID import field mapping

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "rid": {
    "ftp_field_name": "review_key"
  }
}

Example product review ID CSV import file

"product_id","review_key"
"ABC","1234"
"DEF","5678"
"GHI","9101"

Example product review ID import result

[
    {
        "prid": "ABC",
        "rid": "1234"
    }, {
        "prid": "DEF",
        "rid": "5678"
    }, {
        "prid": "GHI"
        "rid": "9101"
    }
]

Import review ratings

If you’re using the Social Proof module, it’s also possible to import product ratings through a product import. This can be useful if Fresh Relevance doesn’t have an integration with your review provider. Before using this feature, you must create a Product Review Import channel on the Rating and Review Providers settings page.

Learn more in Import review data.

Example product review import field mapping

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "reviews.rating": {
    "ftp_field_name": "Rating",
    "field_type": "double"
  },
  "reviews.ratingCount": {
    "ftp_field_name": "Rating Count",
    "field_type": "int"
  }
}

Example product review CSV import file

"product_id","Rating","Rating Count"
"ABC","4","100"
"DEF","5","152"
"GHI","4.8","245"

Upload data to filter product recommendations

Before you start

You must review the documentation on filtering before designing data structures to upload for filtering Product Recommendations.

We recommend using one of the following types of data when uploading for product recommendation filtering:

Tag values and tag groups
Promotion flags
Site brands
Price
Product ID
Stock level
Language

If you need to upload custom fields for product filtering, contact your Account Manager or client support to discuss your requirements.

Set locations on products

You can include location data with product imports to associate a location with each product. This can take the form of a latitude and longitude, or a Country code and postal code. You can also resolve one or more location set values for the product, based on the imported location. This finds the nearest location within the location set; you can specify a maximum distance in metres.

Sample CSV import file with latitude and longitude

n,product_id,item_price,longitude,latitude
green,GBP,54321,34.99,-1.4562736,52.9625168
red,GBP,3466787,12.88,-1.4537201,51.9166199
blue,GBP,98798,11.77,-1.3599078,52.0703792

Mapping file to import from latitude and longitude

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "uv": {
    "ftp_field_name": "item_price"
  },
  "location_ids": {
    "latitude_field_name": "latitude",
    "longitude_field_name": "longitude",
    "location_type": "latlng",
    "location_sets": "mystores|template:uk-cities",
    "list_separator": "|",
    "max_distance": 20000
  },
  "n": {
    "ftp_field_name": "n"
  }
}

This mapping includes the location_ids field that tells the import:

that we're using a latitude and longitude (type: latlng).
what fields contain the latitude and longitude values (latitude_field_name and longitude_field_name).
which location sets to resolve (mystores, and a uk-cities system provided set).
Optional.
what separator is used within the location_sets field
Only required if resolving multiple location sets.
what the maximum distance to consider a nearest location is (max_distance: 20000) in metres.

You can also enhance products with location data using country code and postal code values. The country code must be a 2 letter upper case ISO 3166-1 Alpha-2 country code (for example, GB, FR, US, AU). These are resolved to a latitude and longitude and attached to the product.

Sample CSV import file with country code and postal / ZIP code

n,curr,product_id,item_price,postcode,country_code
green,GBP,54321,34.99,SO16 7QJ,GB
red,GBP,3466787,12.88,SA99 1BA,GB
blue,GBP,98798,11.77,W1A 1AA,GB

Mapping file to import from country code and postal / ZIP code

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "uv": {
    "ftp_field_name": "item_price"
  },
  "location_ids": {
    "postcode_field_name": "postcode",
    "country_code_field_name": "country_code",
    "location_type": "postcode",
    "location_sets": "mystores|template:uk-cities",
    "list_separator": "|"
  },
  "n": {
    "ftp_field_name": "n"
  }
}

This mapping includes the location_ids field that tells the import:

that we're using a postcode and country code (type: postcode).
what fields contain the postcode and country code values (postcode_field_name and country_code_field_name).
which location sets to resolve (mystores, and a uk-cities system provided set).
Optional.
what separator is used within the location_sets field.
Only required if resolving multiple location sets.

You can also directly set location IDs during a product import without resolving from a latitude/longitude or a postal code. You might want to do this if you know which locations a particular item should be associated with.

Sample CSV import file by location IDs

n,curr,product_id,item_price,mylocationids
green,GBP,54321,34.99,set1:location1|set:airport1
red,GBP,3466787,12.88,set1:location4|set2:airport5
blue,GBP,98798,11.77,set2:airport7

Mapping file to import by location ID

{
  "prid": {
    "ftp_field_name": "product_id"
  },
  "uv": {
    "ftp_field_name": "item_price"
  },
  "location_ids": {
    "ftp_field_name": "mylocationids"
    "list_separator": "|"
  },
  "n": {
    "ftp_field_name": "n"
  }
}

This configuration overwrites the locations associated with each product imported with the values provided in the CSV file. No checking is performed on the validity of the values.

If you need help applying location data to your products, contact your Account Manager or client support to discuss your requirements.

Import JSON Data To Lists

To import a list of text values in JSON format:

Field mapping:

"ex.sizes":{"ftp_field_name":"sizes","field_type":"json"},

Data:

sizes
"[""small"",""medium"",""large""]"

To import a list of objects in JSON format:

Field mapping:

"ex.sizes":{"ftp_field_name":"sizes","field_type":"json"},

Data:

sizes
"[{""size"":""small",""length"":""short, {""size"":""small"",""length"":""regular""},{""size"":""small"",""length"":""long""}]"

Import transactions

Product variants (SKUs)

Single page application hooks

Product import API

Support multiple price lists