Syncing Catalog and Products Via File

CitrusAd support two types of format for product data syncing via file. The first is TSV while the other is XML. In this section, we will describe the structures of each file format for product data that we process in CitrusAd.

TSV Files

TSV is a tab-delimited format used in spreadsheet software packages such as Microsoft Excel, LibreOffice Spreadsheet, or Google Sheets. TSV stands for Tab Separated Values. Each TSV file is a raw text file and can be imported into or exported from spreadsheet software. TSV data files can be opened and viewed in a representation of a table with columns and rows.

The first 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 that are required to provide in a TSV file. When a column is required, all values in the column need to be provided in its rows. As can be seen in the table, the two columns that are required are product_code and inventory.

Column names and descriptions of product data in TSV files:

Column name

Required?

Datatype

Description

product_code

Required

Text

This is a unique code to identify the product in the system of retailer. This field is identical to the gtin and item fields in API and XML file syncing.

groups

Optional

Json array

If the value is provided, it must be a json array. It is a list of traits of the product. Must be human readable. Can be things such as: brand, category, style, demographic, ect.

For example:

[ “Electronics”, “Video”, “Televisions”, “Flat Panel Televisions” ]

inventory

Required

Number

This is the inventory of the product.

price

Optional

Number

This is the price of a product.

description

Required

Text

This is the description of the product.

tags

Optional

Json array

If the value is provided, it must be a json array.

For example:

[“description:Autodesk Architecture, Engineering and Construction Collection”, “name:Autodesk Architecture, Engineering and Construction Collection”]

filters

Required

Json array

If the value is provided, it must be a json array.

For example:

[“brand_name:green-fairy", "category:absinthe", "department:spirits", "productName:Green Fairy Absinth Gift Pack 500mL", "varietal:absinthe", "webcountryoforigin:czech-republic"]

filter:KEY

Optional

Text

If this type of column is used, retailers must provide a value for KEY.

For example: The column name can be “filter:brand_name” and the value of the cell in the column can be “green-fairy”.

There could be several columns with this syntax in a TSV file.

name

Optional

Text

This is the name of the product.

size

Optional

Text

This is the size of the product.

image_url

Required

Url

This is a hyperlink to the image of a product.

If the value is provided, it must be a valid URL. The syntax of a URL can be found at http://www.ietf.org/rfc/rfc2396.txt

An example of a TSV file of products can be seen in the table below. In the table, the first row is the heading row. It contains the column names that we have described in the table above. The next rows in the table are data rows. The columns in TSV files can be in any orders, provided that there are valid values in the rows of required columns.

Retailers can provide filters (website taxonomy) for products in a TSV file via the columns “filters” or “filter:KEY”. The text “KEY” can be replaced by a label to have a complete column name for a filter on product. Retailers can provide several columns with the names that match the format “filter:KEY”. In the data of the table below, we have provided an example in which there are two columns with the format “filter:KEY”. They are “filter:category” and “filter:brand_name”.

An example with a heading row and a data row in a TSV file:

product_code

inventory

category_hierachy

filter:category

filter:brand_name

80591101

20

["department:spirits", "productName:Green Fairy Absinth Gift Pack 500mL", "varietal:absinthe", "webcountryoforigin:czech-republic"]

absinthe

green-fairy

XML Files

CitrusAd have 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. An example of a valid XML document with the tags can be seen in the below example.

<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>
</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>
</item>
<rss>

XML tags in XML documents for products

XML Tags

Required?

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

This tag is to describe a unique code to identify a product in the system of retailer.

title

Optional

This tag is to describe the name of a product.

description

Optional

This tag is to describe a description of a product.

image_link

Optional

This tag is to describe the hyperlink to an image of a product.

If the value is provided, it must be a valid URL. The syntax of a URL can be found at http://www.ietf.org/rfc/rfc2396.txt

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.

For example:

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

availability

Required

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