Google Merchant Center XML item feed

An item feed is necessary to show items in search results, recommendations, to make propensity predictions, and so on.

One of the options of uploading an item feed is to use a Google Merchant Center XML file (RSS or Atom specification). Such a file can be:

uploaded to Catalogs with Automation.
In this case, Data Transformation can be used to modify the content to meet the requirements. The catalog can then be used as an item feed (for example, for event enrichment or when Configuring the AI engine).
See example Use Case: Transform and import product data to a catalog.
pulled from an URL as the item feed when Configuring the AI engine.
In this case:
- the file must already meet the requirements when Synerise pulls it from the URL you provide.

This article describes the requirements that the XML must meet, some good practices, and how to add custom attributes.

Note:

For a complete documentation of the Google Merchant Center XML format, see:

Requirements

The file must be written according to RSS or Atom specification.
The file must meet the requirements listed in Google’s documentation.
The maximum file size is 5 GB (5 000 000 000 bytes).
The encoding must be UTF-8.

These two namespaces must be included in the XML prolog:

xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0"

Item attributes from the Google Merchant Center XML standard must have a g: prefix.
Exceptions: title, link, description, name
The following attributes (tags) are required in every item:
- <g:id>
- <title>
- <g:availability>
- <g:product_type>
  The value of the attribute is saved in Synerise as the item category and can be used, for example, in recommendations.
- <g:price>
- <link>
- <g:image_link>
product:type must be the same as the category on your website (in OG tags).
The item ID (g:id in the XML) must be consistent in every integration and piece of data you store in Synerise (transactions, page view events, item feed, and so on)

If your XML is not built exactly according to Google’s documentation (for example, c:cost is used instead of g:price and g:price is not included at all), you need to use an Automation with data transformation while importing the data.

Attribute name transfer into Synerise

Synerise automatically maps attributes (including custom attributes) from the XML to attributes in the Synerise database. The prefix is removed and snake_case is converted into camelCase. For example, g:image_link is saved as imageLink.
Some attributes are transferred differently:

g:product_type attribute is transformed into category
g:price; g:cost_of_goods_sold; g:sale_price and custom attributes of price type are split into value and currency, and their names are converted into camelCase.
For example:
- g:price = 12 USD is saved as price.value = 12 and price.currency = USD
- g:sale_price is saved as salePrice.value and salePrice.currency
g:availability is converted into boolean (true/false) values.
Custom attributes are saved in the attributes object.
For example, c:myAttribute is saved as attributes.myAttribute. When using Inserts in a recommendation frame, if the item info is stored in the item object, you need to access the custom attribute in the following way:
{{item.attributes.myAttribute}}

Multiple instances of the same parameter will be saved as an array, for example:

<c:purpose>Regeneration</c:purpose> 
<c:purpose>Dry hair</c:purpose> 
<c:purpose>Colored hair</c:purpose>

are saved as:

"attributes": {
    "purpose": ["Regeneration","Dry hair","Colored hair"]
}

Attributes created automatically

If g:price is defined, the following attributes may be created automatically while the XML is imported:

effectivePrice
If g:salePrice is defined, it’s saved as effectivePrice. If not, the value of g:price is used as effectivePrice
discountAmount
This is price.value minus salePrice.value
discount
This is discountAmount divided by price.value

Attribute format

The attributes can be saved in two formats:

By using the CDATA tag, for example:
```
<g:product_type><![CDATA[ Man > all > clothes > shirts ]]></g:product_type>
```
This format lets you include special characters (<, >, &) in the attribute’s value. This is the recommended format.
As a string, for example:
```
<g:product_type>Man &gt; all &gt; clothes &gt; shirts</g:product_type>
```
In this format, special characters (<, >, &) can’t be used.

Category separators

In both formats, there must be a space before and after the category separator (> or >). Otherwise, the character is treated as part of the category name instead of a separator.

Correct: clothes > shirts

Wrong: clothes>shirts

Custom item attributes

Custom parameters are prefixed with a c::

...
<c:custom_tagName1>...</c:custom_tagName1>
<c:custom_tagName2>...</c:custom_tagName2>
...

Additional categories

If you want to add additional categories that are recognized by Synerise, use the <g:additional_product_type> attribute, for example:

<g:additional_product_type><![CDATA[X > Y > Z]]></g:additional_product_type>
<g:additional_product_type><![CDATA[A > B > C]]></g:additional_product_type>
<g:additional_product_type><![CDATA[1 > 2 > 3]]></g:additional_product_type>

Good practices

Tips to help you make your work easier and your files more efficient:

Avoid including too large images. They may slow down loading dynamic content in campaigns where data from the feed is used.
Use the <[!CDATA]> tag in case you add items with special characters (<, >, &) in the attribute in the future, even if the attributes don’t include those characters now.
Include only the attributes that you plan to use.
Include the Last-Modified header to enable detection of whether the product feed import is necessary, this will help you reduce data transmission costs.

Troubleshooting

Ensure that all the requirements are met.
For the most common problems, see the “Item feed” section of the Integration checklist.

RSS example

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0">
    <channel>
        <title>Your Website</title>
        <link>http://www.example.com</link>
        <description>About your website</description>
        <item>

            <!-- The following attributes are always required -->
            <g:id>CLO-29473856-2</g:id>
            <title><![CDATA[Roma Cotton Rich Bootcut Jeans - Size 8 Tall]]></title>
            <g:availability><![CDATA[in stock]]></g:availability>
            <g:product_type><![CDATA[Women's Clothing ? Jeans > Bootcut Jeans]]></g:product_type>
            <g:price>59.50 USD</g:price>
            <link><![CDATA[http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856]]></link>
            <g:image_link><![CDATA[http://images.example.com/CLO-29473856-front.jpg]]></g:image_link>

            <!-- The following demonstrates the use of the 'sale price' attribute -->
            <g:sale_price>29.20 USD</g:sale_price>

            <!-- The following attributes are not required for this item -->
            <g:item_group_id>CLO-29473856</g:item_group_id>
            <name><![CDATA[Roma Cotton Rich Bootcut Jeans]]></name>
            <g:online_only>yes</g:online_only>
            <description><![CDATA[A smart pair of bootcut jeans in stretch cotton.]]></description>
            <g:condition>new</g:condition>
            <g:size>30</g:size>
            <g:quantity>10</g:quantity>
            <g:color><![CDATA[Navy]]></g:color>
            <g:shipping_weight>1 kg</g:shipping_weight>
            <g:manufacturer><![CDATA[Wonderful Jean]]></g:manufacturer>
            <g:brand><![CDATA[MS]]></g:brand>
            <g:mpn>B003J5F5EY</g:mpn>
            <g:gtin>5060155240282</g:gtin>
            <g:google_product_category>Women's Clothing > Jeans > Bootcut Jeans</g:google_product_category>
            <g:gender>Female</g:gender>
            <g:material><![CDATA[Jeans]]></g:material>

            <!-- The following demonstrates the use of the custom attributes -->
            <c:age_group><![CDATA[Adult]]></c:age_group>
        </item>
        <item>...</item>
        <item>...</item>
</channel>
</rss>

Atom example

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0">
    <title>Your Website</title>
    <link rel="self" href="http://www.example.com" />
    <updated>2018-01-01CET10:10:30</updated>
    <entry>

        <!-- The following attributes are always required -->
        <g:id>CLO-29473856-2</g:id>
        <title><![CDATA[Roma Cotton Rich Bootcut Jeans - Size 8 Tall]]></title>
        <g:availability><![CDATA[out of stock]]></g:availability>
        <g:product_type><![CDATA[Women's Clothing ? Jeans > Bootcut Jeans]]></g:product_type>
        <g:price>59.50 USD</g:price>
        <link><![CDATA[http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856]]></link>
        <g:image_link><![CDATA[http://images.example.com/CLO-29473856-front.jpg]]></g:image_link>

        <!-- The following demonstrates the use of the 'sale price' attribute -->
        <g:sale_price>29.20 USD</g:sale_price>

        <!-- The following attributes are not required for this item -->
        <g:item_group_id>CLO-29473856</g:item_group_id>
        <name><![CDATA[Roma Cotton Rich Bootcut Jeans]]></name>
        <g:online_only>yes</g:online_only>
        <description><![CDATA[A smart pair of bootcut jeans in stretch cotton.]]></description>
        <g:condition>new</g:condition>
        <g:size>30</g:size>
        <g:quantity>10</g:quantity>
        <g:color><![CDATA[Navy]]></g:color>
        <g:shipping_weight>1 kg</g:shipping_weight>
        <g:manufacturer><![CDATA[Wonderful Jean]]></g:manufacturer>
        <g:brand><![CDATA[MS]]></g:brand>
        <g:mpn>B003J5F5EY</g:mpn>
        <g:gtin>5060155240282</g:gtin>
        <g:google_product_category>Women's Clothing &gt; Jeans &gt; Bootcut Jeans</g:google_product_category>
        <g:gender>Female</g:gender>
        <g:material><![CDATA[Jeans]]></g:material>
        <g:additional_image_link>http://images.example.com/CLO-29473856-side.jpg</g:additional_image_link>
        <g:additional_image_link>http://images.example.com/CLO-29473856-back.jpg</g:additional_image_link>
        <g:shipping>
            <g:country>US</g:country>
            <g:service>Standard Free Shipping</g:service>
            <g:price>0 USD</g:price>
        </g:shipping>

        <!-- The following demonstrates the use of the custom attributes -->
        <c:age_group><![CDATA[Adult]]></c:age_group>
    </entry>
    <entry>...</entry>
    <entry>...</entry>
</feed>