Add SKU variants to your product feed

❗️

New integrations

As of May 2021, all new integrations are required to use API based catalog feed management to send data and perform index updates.

Some products have variants, such as different colors and sizes. These variants have their own SKU and appear in the variants array of API responses.

Each variant of a product has a different SKU from the encompassing product's SKU. The product has its own ID, and each of its SKUs has its own ID.

For example, a particular scarf is sold in three different colors. The scarf itself has its own product ID. Each version of the scarf shares the product ID plus has its own SKU ID. The specific product IDs and SKU IDs are derived according to your own organization's best practices.

ProductProduct IDVariantSKU ID
Striped scarf33757blackblk-3-3757
Striped scarf33757redred-3-3757
Striped scarf33757blueblu-3-3757

Add SKU variants to your product feed

Let's walk through how to set up SKUs in your product feed, then examine how this information is represented in API responses.

Scenario

Example.com is a retail site that sells products for outdoor recreation, including hiking equipment. Lydia is modifying Example.com's product feed. She needs to add three SKUs to an existing product. The product is a tent called The Only Tent. She's adding three different sizes and prices.

1920

Product ID: H-993051-00

SKU IDSizePrice
H-993051-V1single$162.99
H-993051-V2couple$197.99
H-993051-V3family$251.99

Enter the SKUs in the feed

Example.com's product feed is a TSV-formatted file.

She enters a row for each SKU ID in Example.com's product feed. All of the information for each SKU is associated with the product ID — notice how the pid field remains constant, but the skuid field value is unique for each SKU.

Here's a snippet of Lydia's entry for The Only Tent:

pidskuidsku-sizesku-price
H-993051-00H-993051-V1single$162.99
H-993051-00H-993051-V2couple$197.99
H-993051-00H-993051-V3family$251.99

How does SKU data appear in API responses?

SKU data appears in your API responses in the variants array, which is nested inside each product. Here's The Only Tent in one of Lydia's search API responses:

"response": {
    "numFound": 29,
    "start": 0,
    "docs": [
      {
        "description": "This all-season tent is the only tent you'll ever need!",
        "title": "The Only Tent",
        "url": "http://www.example.com/Product/Product.aspx?br=BLMQ&category=tent&productid=H-993051-00",
        "brand": "The Only",
        "pid": "H-993051-00",
        "thumb_image": "http://www.example.com/images/sm/the-only-tent.jpg",
        "variants": [
          {
            "skuid": "H-993051-V1",
            "sku_size": "single",
            "sku_price": "162.99",
          },
          {
            "skuid": "H-993051-V2",
            "sku_size": "couple",
            "sku_price": "197.99",
          },
          {
            "skuid": "H-993051-V3",
            "sku_size": "family",
            "sku_price": "251.99",
          },
        ]
      },
...
    ]
  },
}

Adding variants to a XML feed

If your product feed is in XML, then you need to create a array within the field. The array contains a field with SKU data for each variant.

You can declare values for all variants by declaring values at the product level. Each product should have a unique .

Values declared at the variant level will be only apply to that specific variant. You should declare and at the variant level.

If a value is declared at the product level, it should always be done so for all records. If a value is declared at the variant level, it should always be done so for all records.

Here's a snippet from a XML feed. You can view more details in the variant feed template files.

<Products>
     <Product>
          <pid>585864</pid>
          <title>Skinny Check Tuxedo Trousers</title>
          ...
          <variants>
               <variant>
                    <skuid>58564-blue-8-r</skuid>
                    <size>8</size>
                    ...
               </variant>
               <variant>
                    <skuid>58564-blue-10-r</skuid>
                    <size>10</size>
                    ...
               </variant>  
          </variants>
     </Product>
</Products>