CitrusAd supports three format types for product data syncing via file:
- TSV
- CSV
- XML.
This section describes the structures of each file format for the product data we process in CitrusAd.
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
| 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. | https://www.retailer.com/product/1234.jpg |
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: 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 CitrusAd'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 | https://www.retailer.com/product/1234.jpg | 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 |
TSV files cannot be in quoted format.
XML files
CitrusAd 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 providedMax 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 CitrusAd'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:
<rss>
<item>
<id>80591011</id>
<title>Melissa & Doug Dinosaur Stamp Set, 4yrs+</title>
<description>Imagine a rugged landscape littered with volcanoes, and full of dinosaurs roaming around</description>
<image_link>https://www.retailer.com/productImages/image1.jpg</image_link>
<price>£9.99</price>
<brand>Melissa & Doug</price>
<product_type>Food Cupboard</product_type>
<availability>10</availability>
<hfss>true</hfss>
</item>
<item>
<id>87086011</id>
<title>Waitrose Splits Strawberry Ice Lollies</title>
<description>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.</description>
<image_link>https://www.retailer.com/productImages/image2.jpg</image_link>
<price>£1.25</price>
<brand>Waitrose</brand>
<product_type>Frozen Ice Cream Ice Cream Lollies</product_type>
<availability>20</availability>
<brand>Waitrose</brand>
<hfss>false</hfss>
<seller_id>432un3-sd32s-ssaar</seller_id>
</item>
</rss>
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:
{
"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
}
]
}
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:
{
"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": []
}
As custom payloads are additional workload for our ad generation service, please note that custom payloads integrations are not subject to CitrusAd SLA, unless specified otherwise.