Syncing catalog & products via file
Epsilon Retail Media supports two format types for product data syncing via file:
TSV
CSV
This section describes the structures of each file format for the product data we process in Epsilon Retail Media.
Maximum file size
Epsilon Retail Media are able to support catalog files of 10M products or less per retailer, enabling most marketplace size catalogs.
TSV/CSV files
The table below illustrates the column names and the description of the columns for products in a TSV/CSV file. In this table, we also specify the compulsory columns required to be provided in a file. When a column is required, all values in the column need to be provided in its rows.
️ Unquoted TSV
TSV files cannot be in quoted format. When synchronising via TSV, ensure you synchronise unquoted files.
Column names and descriptions of product data in TSV/CSV files
product_code
Required
Text Max 50 characters
A code to identify the product in your system. This field is identical to the gtin and item fields in API and XML file syncing.
F153212AN1
name
Required
Text Max 150 characters
The name of the product.
SS Sticker Tee - Kids
image_url
Required
Url Max 2048 characters
A hyperlink to the image of a product. Must be a valid URL.
inventory
Required
Number 32 bit unsigned integer recommended
The inventory of the product. If the value is 0, product ads will not be served for the product.
1
description
Required
Text Max 5000 characters
The description of the product.
With embroidered Trefoils and outlined 3-Stripes in contrast white, the Sport Sweat Shorts are a fresh offering from Adidas Originals.
KEY (as a value)
Required for category and broad display placements
Text Max 1000 characters per column
If this type of column is used, retailers must provide a value for <KEY>. You may have several columns with this syntax in a TSV file.
The column name can be “brand” and the value of the cell in the column can be “green-fairy”. This will result in a filter of "brand:green-fairy" on the product.
subClassName
Deprecated. Required for product cross/upsell placements
Text Max 750 characters
The name of the subclass/category the relevant product is in. Subclasses enable better product targeting e.g. a butter product can target bread, but it won’t target band aids.
Cheese
xSellSubClassName
Deprecated. Required for product cross/upsell placements
Text Max 750 characters
The names of the subclasses/categories the relevant product is able to target products within.
Breads, Spreads, Crackers
price
Optional
Number 2 decimal points recommended
The price of a product.
30.00
brand
Required
Text Max 70 characters
The brand of the product.
Tommy Hilfiger
type
Required
Text Max 750 characters
The product type.
Clothing
retailer_taxonomy
Required for enhanced attribution. Must have no spaces between > characters
Text Max 750 characters
Your individual retailer taxonomy of the product.
Men>Men's Clothing>Sweaters
google_taxonomy
Required for enhanced attribution if retailer_taxonomy cannot be provided
Text Max 750 characters
The standard Google taxonomy of the product. More information can be found here: https://www.google.com/basepages/producttype/taxonomy.en-US.txt
Apparel & Accessories > Clothing > Tops
global_identifier
Required
Text Max 50 characters
The global identifier for the product.
08719108994761
global_identifier_type
Required
Text
The type of global identifier.
GTIN
custom_payload
Not required unless advised.
Base64-encoded byte array
This field contains a custom payload that should be threaded through to ad generation. The field should contain a valid JSON object serialised into a byte array and Base64 encoded. The JSON object should adhere to a schema.
See custom payloads section.
hfss
Optional
Boolean
Used to indicate if a product is HFSS or not. This is further leveraged in Epsilon Retail Media's UI. View our HFSS Documentation for more information.
true
seller_id
Optional
Text Max 50 characters
The unique Id of the seller. Only required if onboarding marketplace sellers. Can be left blank for non marketplace products. There are additional requirements to integrate seller_ids, please refer to Marketplace sellerId for more information.
aes-de4-ss
An example file represented as a table can be seen below:
product_code
name
image_url
inventory
description
filter:Category
filter:Size
filter:Country
groups
price
brand
type
retailer_taxonomy
google_taxonomy
global_identifier
seller_id
subClassName
xSellSubClassName
80591101
Green Fairy Absinth Gift Pack 500mL
20
This Green Fairy Absinth & Spoon Gift Pack is the perfect gift for any Absinth or cocktail lover. Place a cube of sugar on the spoon and pour the Absinthe over the top to drink this spirit in the authentic way!
Gifts, Alcoholic, Gift-packs
500ml
Czech Republic
Gifts, Alcoholic, Gift-packs
5.00
Green Fairy
Alcohol
Gifts>Alcoholic>Gift Packs
Food, Beverages & Tobacco>Beverages>Alcoholic Beverages>Liquor & Spirits>Absinthe
8594001443079
7328s-dmie3-9jdae
Gift Packs
Liquor
Updating product images
Epsilon caches image URLs to ensure consistent performance and reduce requests to your image server. If you update an image without changing its URL, you must explicitly trigger a refresh in Epsilon. To do this:
Remove the existing image_url from the product.
Re-send the same image_url once the update is complete.
Alternatively, if your image server supports it, you can force a refresh by appending a query string (for example, a version or timestamp) to the existing URL. This will cause Epsilon to reload the image..
XML files- planned to deprecate
️ Deprecated for new customers
The below is provided for legacy customers still utilising XML format. For new catalog onboarding, we support TSV and CSV formats documented above, which provides greater file flexibility as well as the opportunity to synchronise the file multiple times per day.
Epsilon Retail Media has defined a list of tags that are used to describe an XML document for products. The table below depicts the tags and their descriptions. The tag ‘item’ is used to describe a product in an XML document. All other tags for the other fields need to be written inside this tag.
item
Required
This tag is used to describe a product. All other XML tags for a product must be inside this tag. An XML document for products must contain a list of item tags. This field is identical to the gtin and product_code fields in API and TSV file syncing.
id
Required
A code to identify the product in your system. Equivalent of product_code in TSV files. This field is identical to the gtin and item fields in API and XML file syncing.
title
Required
The name of the product.
image_link
Required Max 50 characters
A hyperlink to the image of a product. Must be a valid URL.
brand
Required Max 70 characters
The brand of the product.
availability
Required 32 bit unsigned integer recommended
This tag is to describe the inventory of a product. The value must be a number.
description
Required Max 5000 characters
This tag is to describe a description of a product.
price
Optional 2 decimal points recommended
This tag is to describe the price of a product. If the value inside the tag is provided, it must be a number.
type
Optional Max 750 characters
The product type.
retailer_taxonomy
Required for enhanced attribution. Also required for category integrations. Max 750 characters
Your individual retailer taxonomy of the product. e.g. Men>Men's Clothing>Sweaters
google_taxonomy
Required for enhanced attribution if retailer_taxonomy cannot be provided
Max 750 characters
The standard Google taxonomy of the product. More information can be found here: https://www.google.com/basepages/producttype/taxonomy.en-US.txt
global_identifier
Required Max 50 characters
The global identifier for the product. e.g 08719108994761
global_identifier_type
Required
The type of global identifier. e.g. GTIN
custom_payload
Not required unless advised.
This field contains a custom payload that should be threaded through to ad generation. The field should contain a valid JSON object serialised into a byte array and Base64 encoded. The JSON object should adhere to a schema.
hfss
Optional
Used to indicate if a product is HFSS or not. This is further leveraged in Epsilon Retail Media's UI. View our HFSS Documentation for more information.
seller_id
Optional Max 50 characters
The unique Id of the seller. Only required if onboarding marketplace sellers. Can be left blank for non marketplace products. There are additional requirements to integrate seller_ids, please refer to Marketplace sellerId for more information.
An example of a valid XML document with the tags is outlined below:
Custom payloads
What are custom payloads?
Custom payloads are fields that are threaded through ‘as-is’ from catalog ingestion to ad serving. No transformations will be applied to the field. However, JSON Schema (https://json-schema.org/) based validation is performed on the field. The payload specification is provided via the link below (JSON Schema notation):
In the product ad response, the exact custom payload is returned to the integrator in a field named customPayload. An example of a valid payload is provided below:
File only
Please note that custom payloads are only supported when synchronising products via file.
Custom payloads in ad generation
When returning product ads, the custom payload is threaded through as part of the generated ad. The returned ad payloads will contain an additional field customPayload that will contain a JSON object adhering to the same specification as the information provided in the feed.
An example response may be:
As custom payloads are additional workload for our ad generation service, please note that custom payloads integrations are not subject to Epsilon Retail Media SLA, unless specified otherwise.