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 name

Required/optional

Data type

Description

Example

product_code

Required

Text

A unique 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

The name of the product.

SS Sticker Tee - Kids

image_url

Required

Url

A hyperlink to the image of a product. Must be a valid URL.

https://www.retailer.com/product/1234.jpg

inventory

Required

Number

The inventory of the product. If the value is 0, product ads will not be served for the product.

1

description

Required

Text

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.

filter:KEY

Required for category and broad display placements

Text

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 “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.

filters

Required for category and broad display placements

Json array

A 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"]

groups

Deprecated.

Json array

If 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”]

subClassName

Required for cross/upsell placements

Text

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

Required for cross/upsell placements

Text

The names of the subclasses/categories the relevant product is able to target products within.

Breads, Spreads, Crackers

price

Optional

Number

The price of a product.

30.00

brand

Required for enhanced attribution in lower case format

Text

The brand of the product.

Tommy Hilfiger

type

Required

Text

The product type.

Clothing

retailer_taxonomy

Required for enhanced attribution

Text

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

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

The global identifier for the product.

08719108994761

global_identifier_type

Required

Text

The type of global identifier.

GTIN

custom_payload

Optional*

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

An example file represented as a table can be seen below:

product_codenameimage_urlinventorydescriptionfilter:Categoryfilter:Sizefilter:Countrygroupspricebrandtyperetailer_taxonomygoogle_taxonomyglobal_identifier
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 > Absinthe8594001443079

📘

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 unique code to identify the product in your system. This field is identical to the gtin and item fields in API and XML file syncing.

title

Optional

The name of the product.

image_link

Required

A hyperlink to the image of a product. Must be a valid URL.

availability

Required

This tag is to describe the inventory of a product. The value must be a number.

description

Optional

This tag is to describe a description of a product.

price

Optional

This tag is to describe the price of a product. If the value inside the tag is provided, it must be a number.

product_type

Optional

This tag is to describe the category hierarchy of a product.

product_type_code

Optional

This tag is to describe filters on the product. If the value is provided, it must be a json array, e.g.
<product_type_code>[“brand_name:green-fairy", "category:absinthe", "department:spirits", "productName:Green Fairy Absinth Gift Pack 500mL", "varietal:absinthe", "webcountryoforigin:czech-republic"]</product_type_code>

custom_payload

Optional*

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.

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>
    </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.