Documentation
API
Product feed
Products update

Products update

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

Products update via API

Example products update request:

POST https://api.adshero.io/v1/feed/product HTTP/2
Content-Type: application/json

{
  "entries": [
    {
      "batchId": "1",
      "method": "UPSERT",
      "product": {
        "id": "549795f4abe49940801b381b",
        "title": "Pillow",
        "link": "http://shop-url/link-to-pillow",
        "price": 12.23,
        "isAvailable": true,
        "brand": "Brand Name",
        "feedId": "17f4ca82-f4a4-4f3a-8372-64fb250e564v",
        "imageLink": "https://image-source/pillow.jpg",
        "salePrice": 9.99,
        "gtin": "3332221112332",
        "googleProductCategory": "6565",
        "mpn": "7656",
        "productType": "Home > Bedroom > Pillows",
        "shipping": [
          {
            "country": "PL",
            "region": "Interan region",
            "price": "10.99 PLN",
            "minHandlingTime": "5 days",
            "maxHandlingTime": "12 days",
            "minTransitTime": "5 days",
            "maxTransitTime": "15 days"
          }
        ],
        "unitPricingMeasure": "2.5 kg",
        "adult": true,
        "energyEfficiencyClass": "A+++",
        "ageGroup": "adult",
        "color": "black",
        "gender": "male",
        "material": "Leather",
        "pattern": "striped",
        "size": "XS",
        "productDetails": [
          {
            "sectionName": "Pillow additional attributes",
            "attributeName": "size",
            "attributeValue": "12x43"
          }
        ],
        "externalSellerId": "341",
        "externalSellerName": "Seller name",
        "deepLink": "https://app.shop-url/pillow",
        "shopVersion": 1
      }
    }
  ]
}
curl -X 'POST' \
  'https://api.adshero.io/v1/feed/product' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "entries": [
    {
      "batchId": "1",
      "method": "UPSERT",
      "product": {
        "id": "549795f4abe49940801b381b",
        "title": "Pillow",
        "link": "http://shop-url/link-to-pillow",
        "price": 12.23,
        "isAvailable": true,
        "brand": "Brand Name",
        "feedId": "17f4ca82-f4a4-4f3a-8372-64fb250e564v",
        "imageLink": "https://image-source/pillow.jpg",
        "salePrice": 9.99,
        "gtin": "3332221112332",
        "googleProductCategory": "6565",
        "mpn": "7656",
        "productType": "Home > Bedroom > Pillows",
        "shipping": [
          {
            "country": "PL",
            "region": "Interan region",
            "price": "10.99 PLN",
            "minHandlingTime": "5 days",
            "maxHandlingTime": "12 days",
            "minTransitTime": "5 days",
            "maxTransitTime": "15 days"
          }
        ],
        "unitPricingMeasure": "2.5 kg",
        "adult": true,
        "energyEfficiencyClass": "A+++",
        "ageGroup": "adult",
        "color": "black",
        "gender": "male",
        "material": "Leather",
        "pattern": "striped",
        "size": "XS",
        "productDetails": [
          {
            "sectionName": "Pillow additional attributes",
            "attributeName": "size",
            "attributeValue": "12x43"
          }
        ],
        "externalSellerId": "341",
        "externalSellerName": "Seller name",
        "deepLink": "https://app.shop-url/pillow",
        "shopVersion": 1
      }
    }
  ]
}'

In response we will get:

HTTP/2 202 ACCEPTED

Meaning of fields:

  • entries: Products list to update ((the maximum allowable number of products is 10000 in single request)
  • batchId: Unique id within the request (technical product group identifier)
  • method : How to update products. Allowed values are: UPSERT (creates or updates the product if it exists) and DELETE
  • product: Product to update

Product fields (Required and optional attributes for products):

  • id: Unique product id (g:id)
  • productId: Product id in a shop database when multiple feed products (offers)) correspond to a single shop product (ah:product_id)
  • title: Product name (g:title)
  • description: Product description (g:description)
  • link: Link to the product in your store (g:link)
  • price: Product price (g:price)
  • isAvailable: Product availability (g:availability)
  • brand: Brand name of your product (g:brand)
  • feedId: Unique feed id (internal feed id in Adshero db)
  • imageLink: URL to the main product image (g:image_link)
  • salePrice: Promotional product price (g:sale_price)
  • gtin: Global Trade Item Number (GTIN) of your product (g:gtin)
  • googleProductCategory: Google-defined category of your product (g:google_product_category)
  • mpn: Unique product identifier (g:MPN)
  • productType: Product category you define for your product (g:product_type)
  • shipping: Product shipping cost and time, and countries to which you ship products (g:shipping)
    • country: Shipping country
    • region: Shipping region
    • price: Shipping price
    • minHandlingTime: Minimum order processing time
    • maxHandlingTime: Maximum order processing time
    • minTransitTime: Minimum transit time
    • maxTransitTime: Maximum transit time
  • unitPricingMeasure: Unit price measure. Attribute defines the measure and size of the product without the shipping packaging (g:unit_pricing_measure)
  • adult: Attribute designates if the product is intended for adults (g:adult)
  • energyEfficiencyClass: Energy efficiency class (g:energy_efficiency_class)
  • ageGroup: Age group defining the demographic group the product is intended for (g:age_group)
  • color: Color of your product (g:color)
  • gender: Gender the product is intended for (g:gender)
  • material: Material the product is made from (g:material)
  • pattern: Pattern or graphic design of the product (g:pattern)
  • size: Product size (g:size)
  • productDetails: Technical or additional product details (g:product_detail)
    • sectionName: Name of the additional product attributes section
    • attributeName: Product additional attribute name
    • attributeValue: Product additional attribute value
  • externalSellerId: External seller ID (g:external_seller_id)
  • externalSellerName: External seller name (ah:external_seller_name)
  • deepLink: Link to the product in the mobile application (ah:deep_link)
  • certification: Product certifications, regulatory compliance, or industry standards (g:certification)
    • certificationAuthority: Name of the authority that issued the certification
    • certificationName: Name of the certification
    • certificationCode: Unique code or identifier for the certification
    • certificationValue: Value or level of the certification
  • itemGroupId: Group identifier used to link variants of the same product (g:item_group_id)
  • labels: Custom labels that can be used for custom grouping of products or campaign management (ah:adshero_label)
  • condition: An attribute used to inform potential customers about the status of the product being sold (g:condition)
  • shopVersion: Product version number on the shop side - an update is applied only when the submitted version is greater than or equal to the stored one (ah:shop_version)

price and salePrice are plain numbers without a currency - the currency set in the feed configuration applies. isAvailable and adult are booleans (true/false).

Custom parameters

You can add custom parameters to products using the custom namespace c: (namespace URI: http://base.google.com/cns/1.0). Custom parameters allow you to pass additional product data that will be returned in the decorated emission response.

Example XML feed with custom parameters:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:g="http://base.google.com/ns/1.0"
      xmlns:c="http://base.google.com/cns/1.0">
  <entry>
    <g:id>PROD-001</g:id>
    <g:title>Example Product</g:title>
    <g:price>99.99 PLN</g:price>
    <!-- Custom parameters -->
    <c:warehouse_location>A1-B2</c:warehouse_location>
    <c:supplier_code>SUP123</c:supplier_code>
    <c:color_variant>red</c:color_variant>
  </entry>
</feed>

Limitations:

  • Maximum 500 characters per parameter value (parameters with longer values are skipped)
  • Maximum 50 custom parameters per product - the first 50 parameters after sorting names alphabetically are kept, the rest are ignored
  • Parameter names must be valid XML element names; when a name repeats, the last value is kept

Exceeding the limits produces a warning visible in the panel - the product is accepted.

Custom parameters are available in the emission API response when using the decorateResponse=true query parameter.

Product validation

The maximum number of products that can be updated in one request is 10,000.

When the UPSERT method is specified, the required fields are:

  • feedId
  • id
  • title
  • price
  • isAvailable
  • link
  • imageLink

For the (DELETE) method, the required fields are:

  • feedId
  • id

A missing required field or exceeding the product limit results in a 400 response and the whole request is rejected.

A 202 response means the request was accepted for processing - products are stored asynchronously. During processing the same rules apply as for the XML feed (Required and optional attributes for products).

Deduplication of products during emission

The deduplication mechanism ensures the uniqueness of products during ad emission (within a single ad request). Feed products have 4 fields that are or can be used for deduplication

  • itemGroupId
  • productId
  • gtin
  • id

Fields are checked in the order as above, i.e. if itemGroupId is not empty - this field will be the deduplication key. If it is empty - the next field is checked, i.e. productId, etc.