Syncing catalog & products via file

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 and CSV files

TSV stands for Tab Separated Values. Each TSV file is a raw text file that can be imported into, or exported from, spreadsheet software. TSV data files can be opened and viewed in a table representation with columns and rows.

The table below illustrates the column names and the description of the columns for products in a TSV file. In this table, we also specify the compulsory columns required to be provided in a TSV file. When a column is required, all values in the column need to be provided in its rows.

️ Unquoted TSV

CitrusAd advises when synchronising via TSV to synchronise unquouted TSV files.

Column names and descriptions of product data in TSV files

Column nameRequired/optionalData typeDescriptionExample
product_codeRequiredTextA 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
nameRequiredTextThe name of the product.SS Sticker Tee - Kids
image_urlRequiredUrlA hyperlink to the image of a product. Must be a valid URL.https://www.retailer.com/product/1234.jpg
inventoryRequiredNumberThe inventory of the product. If the value is 0, product ads will not be served for the product.1
descriptionRequiredTextThe 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.
filter:KEYRequired for category and broad display placementsTextIf 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 “filter:brand_name” and the value of the cell in the column can be “green-fairy”. This will result in a filter of "brand_name:green-fairy" on the product.
filtersDeprecated.Json arrayA json array of product filters.[“brand_name:green-fairy", "category:absinthe", "department:spirits", "productName:Green Fairy Absinth Gift Pack 500mL", "varietal:absinthe", "webcountryoforigin:czech-republic"]
groupsDeprecated.Json arrayIf the value is provided, it must be a json array. It is a list of traits of the product and must be user friendly - it can be things such as: brand, category, style, demographic, etc.[“Electronics”, “Video”, “Televisions”, “Flat Panel Televisions”]
subClassNameRequired for cross/upsell placementsTextThe 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
xSellSubClassNameRequired for cross/upsell placementsTextThe names of the subclasses/categories the relevant product is able to target products within.Breads, Spreads, Crackers
priceOptionalNumberThe price of a product.30.00
brandRequired for enhanced attribution in lower case formatTextThe brand of the product.Tommy Hilfiger
typeRequiredTextThe product type.Clothing
retailer_taxonomyRequired for enhanced attribution. Must have no spaces between > charactersTextYour individual retailer taxonomy of the product.Men>Men's Clothing>Sweaters
google_taxonomyRequired for enhanced attribution if retailer_taxonomy cannot be providedTextThe standard Google taxonomy of the product. More information can be found here: https://www.google.com/basepages/producttype/taxonomy.en-US.txtApparel & Accessories > Clothing > Tops
global_identifierRequiredTextThe global identifier for the product.08719108994761
global_identifier_typeRequiredTextThe type of global identifier.GTIN
custom_payloadOptional*Base64-encoded byte arrayThis 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.
hfssOptionalBooleanUsed 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_idOptionalTextThe 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_codenameimage_urlinventorydescriptionfilter:Categoryfilter:Sizefilter:Countrygroupspricebrandtyperetailer_taxonomygoogle_taxonomyglobal_identifierseller_idsubClassNamexSellSubClassName
80591101Green Fairy Absinth Gift Pack 500mLhttps://www.retailer.com/product/1234.jpg20This 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-packs500mlCzech RepublicGifts, Alcoholic, Gift-packs5.00Green FairyAlcoholGifts>Alcoholic>Gift PacksFood, Beverages & Tobacco>Beverages>Alcoholic Beverages>Liquor & Spirits>Absinthe85940014430797328s-dmie3-9jdaeGift PacksLiquor

📘

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 tagsRequired/optionalDescription
itemRequiredThis 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.
idRequiredA 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.
titleRequiredThe name of the product.
image_linkRequiredA hyperlink to the image of a product. Must be a valid URL.
availabilityRequiredThis tag is to describe the inventory of a product. The value must be a number.
descriptionRequiredThis tag is to describe a description of a product.
priceOptionalThis tag is to describe the price of a product. If the value inside the tag is provided, it must be a number.
typeOptionalThe product type.
retailer_taxonomyRequired for enhanced attribution. Also required for category integrations.Your individual retailer taxonomy of the product. e.g. Men>Men's Clothing>Sweaters
google_taxonomyRequired for enhanced attribution if retailer_taxonomy cannot be providedThe standard Google taxonomy of the product. More information can be found here: https://www.google.com/basepages/producttype/taxonomy.en-US.txt
global_identifierRequiredThe global identifier for the product. e.g 08719108994761
global_identifier_typeRequiredThe type of global identifier. e.g. GTIN
custom_payloadOptional*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.
hfssOptionalUsed 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_idOptionalThe 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 &amp; 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>&pound;9.99</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>&pound;1.25</price>
      <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&lt;BR&gt;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&lt;BR&gt;SAVE up to: $1",
      "promoType": "P",
      "offerFlag": true
    }
  ]
}

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&lt;BR&gt;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&lt;BR&gt;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.