Syncing Catalog and Products Via File

XML Files

Project Agora Commerce 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>
      <pa_id>catprefix--80591011</pa_id>
      <title>Melissa &amp; Doug Dinosaur Stamp Set, 4yrs+</title>
      <barcode>012345678923</barcode>
      <pa_title>Melissa &amp; Doug Dinosaur Stamp Set, 4yrs+--012345678923</pa_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>
      <link>htttps://www.retailer.com/icecreams/melissa-dougdinosaurstam-set.html</link>
      <msrp>11.99</msrp>
      <price>9.99</price>
      <taxonomy>Dairy>Ice creams|Dairy</taxonomy>
      <product_type>Dairy>Ice creams</product_type>
      <category_path>Dairy>Ice creams</category_path>
      <availability>10</availability>
      <brand>Melissa</brand>
    </item>
    <item>
      <id>87086011</id>
      <pa_id>catprefix--87086011</pa_id>
      <title>Waitrose Splits Strawberry Ice Lollies</title>
      <barcode>789123456789</barcode>
      <pa_title>Waitrose Splits Strawberry Ice Lollies--78912345678</pa_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>
       <link>htttps://www.retailer.com/icecreams/melissa-dougdinosaurstam-set.html</link>
       <msrp>11.99</msrp>
      <price>1.25</price>
      <taxonomy>Dairy>Ice creams|Dairy</taxonomy>
      <product_type>Dairy>Ice creams</product_type>
      <category_path>Dairy>Ice creams</category_path>
      <availability>20</availability>
      <brand>Waitrose</brand>
    </item>
<rss>

The taxonomy attribute contains all the category paths in which a product belongs divided with the | sign. It is important that the different paths are divided with the | symbol without any spaces around it.

For example if a product belongs to the following categories A > B> C and D > E then all the available category paths are "A>B>C", "A>B","A" ,"D>E" and "D". The taxonomy attribute will be integrated like below:

<taxonomy>A>B>C|A>B|A|D>E|D</taxonomy>

The product_type attribute contains all the available categories (parent and current) in which a product belongs divided with the > sign

The category_path attribute contains only one indicative category path of the product. For example if the product belongs in category C which has as a parent category B and B has a parent category A, then the category_path will contain the value A > B > C

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.
pa_id	Required	The pa_id is a concatenation of id with a catalog specific prefix(the catalog prefix is provided from project agora) <pa_id>=catprefix+"--"+<id> This is the universal unique id to identify each product in the pa-commerce platform. This id is used for ad requests/responses and impression/click and order reporting.
title	Required	This tag is to describe the name of a product.
barcode	Required	The barcode/GTIN of the product
pa_title	Required	The pa_title is a concatenation of the title of the product and the barcode. <pa_title>=<title>+"--"+<barcode>.
description	Required	This tag is to describe a description of a product.
image_link	Required	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
link	Required	The landing page url of this item (product details page). If this product has multiple product details pages (because it exists in multiple different categories), please select a random one.
msrp	Required	Manufacturer's Suggested Retail Price: Price before discount including VAT
price	Required	This tag is to describe the price of a product. If the value inside the tag is provided, it must be a number.
taxonomy	Required	This tag is to describe all the available category paths for this product
product_type	Required	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>
category_path	Required	This tag contains one indicative hierarchy of the product's category tree
brand	Required	This tag is to describe the brand of the product
availability	Required	This tag is to describe the inventory of a product. The value must be a number. If the product is out of stock it should have the value 0

The retailer has to ensure that every product is included in the xml file even if the product is out of stock.

The <pa_id> and <pa_title> were introduced on April 2020 as part of the new pa commerce integration process.