Product feed

The product feed necessary for the system to function is compliant with the standard feed for Google Shopping. Provide the URL where the feed is located to start data synchronization. We accept both regular XML files and compressed gzip files - in that case, provide a URL ending with .gz.

Below we list optional and required attributes for the product feed. Additionally, we include an example feed containing a single product - a good starting point for creating the final feed.

Required and Optional Attributes for Products

We assume that the XML namespace for Google is named g (added xmlns:g="http://base.google.com/ns/1.0" at the top of the file) and for AdsHero, it is named ah (added xmlns:ah="http://adshero.io/ns/1.0" at the top of the file).

Attribute list:

Field	Product description	Format	Required	Notes
`g:id`	Unique product or offer code	Maximum 50 characters	Yes	The SKU code should be unique for each product. If the same product is sold by multiple sellers (`g:external_seller_id`), then `g:id` is the unique offer identifier, and use `ah:product_id` for product identification. Keep the same code when updating data.
`ah:product_id`	Unique product code	Maximum 128 characters	No	Product identifier, if `g:id` is used as offer identifier (in case the same product can be sold by multiple sellers). Keep the same code when updating data.
`g:title`	Product name	Maximum 300 characters	Yes	Accurately describes your product and matches the title in your store. Do not include promotional or shipping information in the title.
`g:description`	Product description	Maximum 5000 characters	No	List product features, technical specifications, and visual attributes. A detailed description will help us show your product to the right customers.
`g:link`	Link to the product in your store	URL	Yes	Use a link from your domain. Start with `http://` or `https://`.
`g:image_link`	URL to the main product image	URL	Yes	For the image link: Link to the main product image. Start with `http://` or `https://`. For the image: Precisely show the product you are selling. Use one of the formats: JPEG (.jpg/.jpeg), WebP (.webp), PNG (.png), non-animated GIF (.gif), BMP (.bmp), and TIFF (.tif/.tiff)
`g:availability`	Product availability	Enum: `in stock` `out of stock`	Yes	Provide product availability consistent with the product’s availability in your store.
`g:price`	Product price.	Monetary value: Numeric, with a dot as a decimal separator. Currency compliant with ISO-4217	Yes	Accurately state the price and currency of the product consistent with the price in your store. Ensure that the product price is in a currency consistent with the target country.
`g:sale_price`	Promotional product price.	Monetary value: Numeric, with a dot as a decimal separator. Currency compliant with ISO-4217	No	Precisely state the promotional price and currency of the product consistent with the price in the store.
`g:google_product_category`	Google-defined category of your product.	Value from the Google product taxonomy: Numeric category ID or Full category path	No	Include only one category. Include the most appropriate category. Include either the full category path or the category ID - do not use both values simultaneously.
`g:product_type`	Product category you define for your product.	Maximum 750 alphanumeric characters.	No	Include the full product category, down to the lowest level. Categories should be separated by symbol: >, e.g. `Health > Vitamins > Vitamin C`
`g:brand`	Brand name of your product.	Maximum 70 characters.	No	Provide the product brand commonly known to consumers. Providing the correct brand positively affects the shopping experience and ensures better results. If you sell private label products, fill in this field by entering your brand name. If the product has no brand, leave this field empty.
`g:gtin`	Global Trade Item Number (GTIN) of your product.	In Europe, this will be EAN (GTIN-13): 13-digit number	No	Exclude dashes and spaces. Submit only valid and correct GTIN numbers. If the product has no GTIN, do not guess or create one yourself.
`g:MPN`	Unique product identifier.	Maximum 70 alphanumeric characters.	No	Include only MPN numbers specified by the manufacturer. Use the most specific MPN number for the product (different color, different MPN). Providing the correct MPN number makes the ad better matched to the consumer. If you do not know the MPN number, do not provide it and leave this field empty.
`g:shipping`	Product shipping cost and time, and countries to which you ship products.	Additionally, you may set sub-attributes: `country` `region` `price` `min_handling_time` `max_handling_time` `min_transit_time` `max_transit_time`	No
`g:unit_pricing_measure`	Unit price measure	Example `2.5 kg` Supported units: Weight: `oz`, `lb`, `mg`, `g`, `kg` Volume (US/Imperial units): `floz`, `pt`, `qt`, `gal` Volume (metric units): `ml`, `cl`, `l`, `cbm` Length: `in`, `ft`, `yd`, `cm`, `m` Area: `sqft`, `sqm` Per unit: `quantity`	No	Attribute defines the measure and size of the product without the shipping packaging.
`g:adult`	Attribute designates if the product is intended for adults.	Example: `yes` Supported values: `yes` `no`	No	Use the `yes` attribute for products intended only for adults, e.g., nudity, erotic content.
`g:energy_efficiency_class`	Energy efficiency class	Example `A+++` Maximum 10 characters.	No	Include legally required energy label.
`g:age_group`	Age group defining the demographic group the product is intended for.	Example `kids` Maximum 100 characters.	No	Include only one value per product.
`g:color`	Color of your product.	Example `White` Maximum 100 alphanumeric characters (40 characters per color).	No
`g:gender`	Gender the product is intended for.	Example `Unisex` Maximum 10 characters.	No
`g:material`	Material the product is made from.	Example `Leather` Maximum 200 characters describing the material.	No	Add information about the material(s) your product is made from. If specifying more than one material, format it this way: `”cotton/polyester/elastane”`
`g:pattern`	Pattern or graphic design of the product.	Example `striped` `paisley` Maximum 100 characters.	No
`g:size`	Product size.	Example `XS` Maximum 100 characters.	No
`g:product_detail`	Technical or additional product details.	This field has subattributes: `attribute_name`: Specific characteristic you’re describing, required, up to 140 characters, ex. `Resolution` `attribute_value`: Actual value for that characteristic, required, up to 1000 characters, ex. `432 x 240` `section_name`: Acts as a category for related specifications, optional, up to 140 characters, ex. `Display` This field can be repeated with different values, up to 50 times.	No	Do not include information here that is contained in other attributes.
`g:item_group_id`	Attribute for grouping unique products.	Text field.	No	For a single ad request, no more than one ad will be returned from the same group.
`g:external_seller_id`	External seller ID.	Text field.	No	If this field is filled, it is required to fill in the `external_seller_name` field.
`ah:external_seller_name`	External seller name.	Text field.	No	If this field is filled, it is required to fill in the `external_seller_id` field.
`g:deep_link`	Link to the product in the mobile application.	URI	No	Start with `http://`, `https://` or `myapp://`.
`g:certification`	Product certifications, regulatory compliance, or industry standards.	This field has subattributes: `certification_authority`: Name of the authority that issued the certification `certification_name`: Name of the certification `certification_code`: Unique code or identifier for the certification `certification_value`: Value or level of the certification	No	Use this attribute to indicate any certifications or compliance information relevant to the product.
`ah:adshero_label`	Custom labels that can be used for custom grouping of products or campaign management.	Example: `onsite` This field can be repeated with different values.	No	These labels can be used for custom filtering.

“Product” vs “Offer”

By default, the feed contains products. In the case of multi-merchant stores (where multiple sellers sell on the platform and different sellers can sell the same product as different offers), each item in the feed is treated as a single offer. Effectively, the feed contains “offers” when the g:external_seller_id field is populated, indicating which seller the offer belongs to.

In the case of a feed with offers, g:id must be unique for each offer. If multiple sellers are selling the same “product” (the same item, but e.g., at a different price), then the optional ah:product_id field should be filled, which is the product identifier (multiple offers can have the same ah:product_id - this gives the system information that several offers represent the same product).

Example Feeds

Below is an example feeds.

Minimum Feed XML

Contains 6 required fields for two products. This is used for the fastest connection verification and implementation.

<?xml version="1.0" encoding="utf-8" ?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:ah="http://adshero.io/ns/1.0">
  <channel>
    <g:title>AdsHero Minimum Product Feed (Sample Store)</g:title>
    <g:link>https://www.exampleshop.pl/</g:link>
    <g:description>Feed with minimal data required for synchronization.</g:description>

    <item>
      <g:id><![CDATA[KWA-ZIAR-EKO-1KG]]></g:id>
      <g:title><![CDATA[Arabica Organic Coffee Beans, 1 kg]]></g:title>
      <g:link><![CDATA[https://www.exampleshop.pl/coffee-arabica-bio-1kg]]></g:link>
      <g:image_link><![CDATA[https://www.exampleshop.pl/img/coffee-bio-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>79.99 PLN</g:price>
    </item>

    <item>
      <g:id><![CDATA[EXP-AUTO-SILVER]]></g:id>
      <g:title><![CDATA[Barista Pro Automatic Coffee Machine X10]]></g:title>
      <g:link><![CDATA[https://www.exampleshop.pl/ekspres-barista-x10]]></g:link>
      <g:image_link><![CDATA[https://www.exampleshop.pl/img/ekspres-x10-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>2499.00 PLN</g:price>
    </item>

  </channel>
</rss>

Maximum Feed XML

Contains all possible fields for two products.

<?xml version="1.0" encoding="utf-8" ?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:ah="http://adshero.io/ns/1.0">
  <channel>
    <metadata>
      <ref_application_id>101010101010101</ref_application_id>
      <ref_asset_id>ExampleShop.pl-FULL-MAX</ref_asset_id>
    </metadata>
    <g:title>Perfectly Maximum Product Feed ExampleShop</g:title>
    <g:link>https://www.exampleshop.pl/</g:link>
    <g:description>Feed filled with every attribute, no empty values, for maximum monetization.</g:description>

    <item>
      <g:id><![CDATA[KWA-ZIAR-EKO-1KG-SPRZ1]]></g:id>
      <g:title><![CDATA[Arabica Organic Coffee Beans, 1 kg, medium roast]]></g:title>
      <g:link><![CDATA[https://www.exampleshop.pl/coffee-arabica-bio-1kg]]></g:link>
      <g:image_link><![CDATA[https://www.exampleshop.pl/img/coffee-bio-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>79.99 PLN</g:price>

      <ah:product_id><![CDATA[KWA-ZIAR-EKO-1KG]]></ah:product_id>
      <g:external_seller_id><![CDATA[SELLER-001]]></g:external_seller_id>
      <ah:external_seller_name><![CDATA[Coffee of the World Roastery]]></ah:external_seller_name>

      <g:description><![CDATA[100% Arabica from organic Ethiopian farming. Medium roast, with notes of chocolate and nuts. Perfect for espresso.]]></g:description>
      <g:sale_price>69.99 PLN</g:sale_price>
      <g:google_product_category>129</g:google_product_category>
      <g:product_type><![CDATA[Food > Coffee and tea > Coffee beans]]></g:product_type>
      <g:brand>EcoCoffee</g:brand>
      <g:gtin><![CDATA[7777777777777]]></g:gtin>
      <g:mpn><![CDATA[EC-KZ-AB-1K]]></g:mpn>
      <g:item_group_id><![CDATA[COFFEE-BEANS-SERIES]]></g:item_group_id>
      <g:condition>new</g:condition>
      <g:adult>no</g:adult>

      <g:age_group>adult</g:age_group>
      <g:gender>Unisex</g:gender>
      <g:material>Arabica beans</g:material>
      <g:color>Dark brown</g:color>
      <g:pattern>Smooth</g:pattern>
      <g:size>1 kg (package)</g:size>

      <g:unit_pricing_measure>1 kg</g:unit_pricing_measure>
      <g:energy_efficiency_class>A</g:energy_efficiency_class>
      <g:product_detail>
        <g:section_name>Flavor Profile</g:section_name>
        <g:attribute_name>Acidity</g:attribute_name>
        <g:attribute_value>Low</g:attribute_value>
      </g:product_detail>
      <g:certification>
        <g:certification_authority>UE</g:certification_authority>
        <g:certification_name>Eco Certificate</g:certification_name>
        <g:certification_code>PL-EKO-05-001</g:certification_code>
        <g:certification_value>PL-EKO-05</g:certification_value>
      </g:certification>

      <g:shipping>
        <g:country>PL</g:country>
        <g:region>Mazowieckie</g:region>
        <g:price>11.00 PLN</g:price>
        <g:min_handling_time>1 day</g:min_handling_time>
        <g:max_handling_time>2 days</g:max_handling_time>
        <g:min_transit_time>2 days</g:min_transit_time>
        <g:max_transit_time>4 days</g:max_transit_time>
      </g:shipping>
      <g:deep_link><![CDATA[app://exampleshop/product/KWA-ZIAR-EKO-1KG-SPRZ1]]></g:deep_link>
      <ah:adshero_label><![CDATA[premium-eko]]></ah:adshero_label>
      <ah:adshero_label><![CDATA[in-promotion]]></ah:adshero_label>
    </item>

    <item>
      <g:id><![CDATA[EXP-AUTO-SILVER-SPRZ3]]></g:id>
      <g:title><![CDATA[Barista Pro Automatic Coffee Machine X10]]></g:title>
      <g:link><![CDATA[https://www.exampleshop.pl/ekspres-barista-x10]]></g:link>
      <g:image_link><![CDATA[https://www.exampleshop.pl/img/ekspres-x10-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>2499.00 PLN</g:price>

      <ah:product_id><![CDATA[EXP-AUTO-BPX10]]></ah:product_id>
      <g:external_seller_id><![CDATA[SELLER-003]]></g:external_seller_id>
      <ah:external_seller_name><![CDATA[AGD Expert]]></ah:external_seller_name>

      <g:description><![CDATA[Espresso machine with built-in grinder, 15 bar, milk frothing system. Automatic cleaning.]]></g:description>
      <g:sale_price>2299.00 PLN</g:sale_price>
      <g:google_product_category>502</g:google_product_category>
      <g:product_type><![CDATA[Electronics > Household appliances > Automatic coffee machines]]></g:product_type>
      <g:brand>BaristaPro</g:brand>
      <g:gtin><![CDATA[1234567890123]]></g:gtin>
      <g:mpn><![CDATA[BPX10-SILVER-EU]]></mpn>
      <g:item_group_id><![CDATA[BARISTAPRO-X10-SERIES]]></g:item_group_id>
      <g:condition>new</g:condition>
      <g:adult>no</g:adult>

      <g:age_group>adult</g:age_group>
      <g:gender>Unisex</g:gender>
      <g:material>Stainless steel / Plastic</g:material>
      <g:color>Silver</g:color>
      <g:pattern>Smooth</g:pattern>
      <g:size>Compact</g:size>

      <g:unit_pricing_measure>1 szt.</g:unit_pricing_measure>
      <g:energy_efficiency_class>A+++</g:energy_efficiency_class>
      <g:product_detail>
        <g:section_name>Technical Parameters</g:section_name>
        <g:attribute_name>Pressure</g:attribute_name>
        <g:attribute_value>15 bars</g:attribute_value>
      </g:product_detail>
      <g:certification>
        <g:certification_authority>TÜV</g:certification_authority>
        <g:certification_name>Electrical Safety</g:certification_name>
        <g:certification_code>TUV-EXP-2024</g:certification_code>
        <g:certification_value>Compliant with IEC standard</g:certification_value>
      </g:certification>

      <g:shipping>
        <g:country>PL</g:country>
        <g:region>Łódzkie</g:region>
        <g:price>0.00 PLN</g:price>
        <g:min_handling_time>1 day</g:min_handling_time>
        <g:max_handling_time>1 day</g:max_handling_time>
        <g:min_transit_time>1 day</g:min_transit_time>
        <g:max_transit_time>2 days</g:max_transit_time>
      </g:shipping>
      <g:deep_link><![CDATA[app://exampleshop/product/EXP-AUTO-SILVER-SPRZ3]]></g:deep_link>
      <ah:adshero_label><![CDATA[premium-agd]]></ah:adshero_label>
      <ah:adshero_label><![CDATA[free-delivery]]></ah:adshero_label>
    </item>

  </channel>
</rss>

Additional Feed

When configuring a product feed, you can provide a URL to an additional feed. The additional feed contains exactly the same data as the main feed, but doesn’t have g:id - instead, it only has ah:product_id. It can be used when the main feed is very large and data between offers (e.g., g:description) often repeats.

When an additional feed is configured, Adshero will download it together with the main feed and supplement the offer/product data from the main feed based on data from the additional feed (matching is done by ah:product_id).

Besides reducing feed size, this also allows generating these files at different rates (e.g., price and stock data every hour, but product description and title once a day).

Creating Product Feeds via API

🛡

This API is secured — you need to pass access token in the Authorization header.

The default path for uploading feeds to AdsHero is creating them in the panel. Unless there are special cases, you don’t need to use this API.

POST https://api.adshero.io/v1/feed/ HTTP/2
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "string",
  "url": "string",
  "shopId": "string",
  "currency": "string",
  "lang": "string"
}

curl --location --request POST 'https://api.adshero.io/v1/feed/' \
    --header 'Authorization: Bearer {access_token}' \
    --header 'Content-Type: application/json' \
    --data '{ 
      "name": "string", 
      "url": "string", 
      "shopId": "string", 
      "currency": "string", 
      "lang": "string"
    }'

Parameter meanings:

name: The feed name visible in the panel.
url: The URL to the feed — this is where we expect the XML file with the feed to be located.
shopId: Shop identifier. It is available in the publisher panel (shop) under account settings.
currency: The currency of the feed, compliant with ISO-4217.
lang: The language of the feed, compliant with ISO-639-1 (two-letter language codes).