> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/data-api/catalog-products-2/syncing-catalog-products-via-file.md). # 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. {% hint style="info" %} Are you over 10M products? If your catalog is over this volume, Epsilon Retail Media can assess if your catalog size is supportable. Please note this may also require commercial adjustments {% endhint %} ## 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. {% hint style="warning" %} ️ Unquoted TSV TSV files cannot be in quoted format. When synchronising via TSV, ensure you synchronise unquoted files. {% endhint %} ### Column names and descriptions of product data in TSV/CSV files | Column name | Required/optional | Data type | Description | Example | | ------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 \.

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: | 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](/retail-media-interface/integration/feature-integrations/placement-level-product-type-blocking-hfss-support.md) 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 | {% hint style="info" %} TSV files cannot be in quoted format. {% endhint %} ## 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.. {% hint style="info" %} Images are only used in the UI Product images are not served in ad responses. Any image updates only affect how the product appears in the Epsilon UI while the cache refresh occurs. {% endhint %} ## XML files- planned to deprecate {% hint style="danger" %} ️ 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. {% endhint %} 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. | XML tags | Required/optional | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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: | | `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](/retail-media-interface/integration/feature-integrations/placement-level-product-type-blocking-hfss-support.md) 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: ```xml 80591011 Melissa & Doug Dinosaur Stamp Set, 4yrs+ Imagine a rugged landscape littered with volcanoes, and full of dinosaurs roaming around https://www.retailer.com/productImages/image1.jpg £9.99 Melissa & Doug Food Cupboard 10 true 87086011 Waitrose Splits Strawberry Ice Lollies Strawberry splits; Suitable for vegetarians. Strawberry splits vanilla flavoured ice cream with a fruity strawberry ice coating. Our fundamental belief is that few things in life are more important than the food you buy. Good quality is essential. https://www.retailer.com/productImages/image2.jpg £1.25 Waitrose Frozen Ice Cream Ice Cream Lollies 20 Waitrose false 432un3-sd32s-ssaar ``` ## 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 () 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: ```json { "id": "102013703", "upc": "4400000463", "name": "Bee Farms Honey - 14.4 Oz", "nutrientName": [ "Kosher" ], "description": "Honey", "brand": "Bee Farms", "imageUrl": "https://www.retailer.com/products/1/image.png", "productUrl": "https://www.retailer.com/products/1/page.html", "aisleId": "1_22_2_3", "departmentName": "Breakfast ", "aisleName": "Breakfast spreads", "shelfName": "Honeu", "salesRank": 481, "details": "Made with real honey. No high fructose corn syrup. 8 g of while grain per 31 g serving. Per 8 Crackers: 130 calories; 0 g sat fat (% DV); 160 mg sodium (7% DV); 8 g total sugars. Start with: Bee farms honey grahams. Fill grahams with toasted marshmallows. Add milk chocolate squares. For full nutritional information, go to honeymaid.com. Try our other delicious flavors: Grahams made with real cinnamon. Grahams made with real chocolate. 8 g of whole grain per 31 g serving. Nutritionist recommend eating 18 g or more of whole grains throughout the day. 100% Whole Grain: 8 per serving. Eat 48 g or more of whole grains daily. WholeGrainsCouncil.org. Smartlabel. Visit us at: beefarms.com 1-809-622-4726 please have package available. Keep it Going: 100 recycled paperboard. Please recycle this carton. Minimum 35% post-consumer content. Made in Mexico.", "averageWeight": 0, "displayType": 0, "stores": [ { "storeId": "2543", "price": 3.99, "salePrice": 0.28, "pricePer": 4.99, "unitOfMeasure": "OUNCE", "restrictedFlag": false, "sellByWeight": false, "promoDescription": "I", "promoText": "Club Price: $3.99<BR>SAVE up to: $1", "promoType": "P", "offerFlag": true }, { "storeId": "2544", "price": 3.99, "salePrice": 0.28, "pricePer": 4.99, "unitOfMeasure": "OUNCE", "restrictedFlag": false, "sellByWeight": false, "promoDescription": "I", "promoText": "Club Price: $3.99<BR>SAVE up to: $1", "promoType": "P", "offerFlag": true } ] } ``` {% hint style="warning" %} File only Please note that custom payloads are only supported when synchronising products via file. {% endhint %} ### 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: ```json { "ads": [ { "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==", "gtin": "4400000463", "customPayload": { "id": "102013703", "upc": "4400000463", "name": "Bee Farms Honey - 14.4 Oz", "nutrientName": [ "Kosher" ], "description": "Honey", "brand": "Bee Farms", "imageUrl": "https://www.retailer.com/products/1/image.png", "productUrl": "https://www.retailer.com/products/1/page.html", "aisleId": "1_22_2_3", "departmentName": "Breakfast ", "aisleName": "Breakfast spreads", "shelfName": "Honeu", "salesRank": 481, "details": "Made with real honey. No high fructose corn syrup. 8 g of while grain per 31 g serving. Per 8 Crackers: 130 calories; 0 g sat fat (% DV); 160 mg sodium (7% DV); 8 g total sugars. Start with: Bee farms honey grahams. Fill grahams with toasted marshmallows. Add milk chocolate squares. For full nutritional information, go to honeymaid.com. Try our other delicious flavors: Grahams made with real cinnamon. Grahams made with real chocolate. 8 g of whole grain per 31 g serving. Nutritionist recommend eating 18 g or more of whole grains throughout the day. 100% Whole Grain: 8 per serving. Eat 48 g or more of whole grains daily. WholeGrainsCouncil.org. Smartlabel. Visit us at: beefarms.com 1-809-622-4726 please have package available. Keep it Going: 100 recycled paperboard. Please recycle this carton. Minimum 35% post-consumer content. Made in Mexico.", "averageWeight": 0, "displayType": 0, "stores": [ { "storeId": "2543", "price": 3.99, "salePrice": 0.28, "pricePer": 4.99, "unitOfMeasure": "OUNCE", "restrictedFlag": false, "sellByWeight": false, "promoDescription": "I", "promoText": "Club Price: $3.99<BR>SAVE up to: $1", "promoType": "P", "offerFlag": true }, { "storeId": "2544", "price": 3.99, "salePrice": 0.28, "pricePer": 4.99, "unitOfMeasure": "OUNCE", "restrictedFlag": false, "sellByWeight": false, "promoDescription": "I", "promoText": "Club Price: $3.99<BR>SAVE up to: $1", "promoType": "P", "offerFlag": true } ] } , "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516943179Z" } ], "banners": [], "products": [] } ``` {% hint style="warning" %} 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. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/integration/data-api/catalog-products-2/syncing-catalog-products-via-file.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.