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>
      <price>9.99</price>
      <product_type>Food Cupboard</product_type>
       <category_path>Stationary>Stamps</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>
      <price>1.25</price>
      <product_type>Frozen Ice Cream Ice Cream Lollies</product_type>
      <category_path>Dairy>Ice creams</category_path>
      <availability>20</availability>
      <brand>Waitrose</brand>
    </item>
<rss>

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.
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.
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. When it is 0 it declares that the product is out of stock.

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.