Requesting product and SKU attributes

fl parameter and the docs response array

The response array, docs, contains a list of all of the products that fit the search query. The fields within docs vary according to the request’s fl parameter. Each attribute that you specify in the fl parameter becomes a docs field in the response. For example, if you pass the fl parameter with the value, brand, then the docs array in the response includes the name of the designer or brand for every product.

In the following example request, the fl parameter value has these attributes: pid, title, and brand.:

GET https://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&domain_key=example_com
&request_id=8438674518839
&url=http://www.example.com/index.html?q=dresses
&request_type=search
&search_type=keyword
&q=dresses
&rows=10
&start=0
&fl=pid,title,brand

In the corresponding response, the attributes contained in each entry of the response's docs array are pid, title, and brand. You can run a similar request and see its full response.

When you pass the fl parameter, you need to include all of the attributes about a product that you want returned in the response. Here are common attributes that you can request using the fl parameter :

This list isn't exhaustive. You might have some other attributes or some custom attributes that aren't in this list. If you need information about using them, then your BloomReach representative can help you.

🚧

Product feed

Attributes must be in your product feed before you can use them in API requests.

SKU variants array

If your product feed includes products that have individual SKU variants, then your search API response can include information about SKUs that fit the search query. Just as you do for products, your request's fl parameter needs to include all of the attributes about a SKU that you want returned in the response.

The docs array includes a variants array that holds information about SKUs. In the following example, the product is a skirt with SKU variants for the skirt's color, size, SKU ID, and some images.

"docs": [
      {
        "pid": "wd87347286",
        "title": "Spring Meadows Skirt",
        "brand": "Flirt",
        "price": 72.99
        "sale_price": 62.88,
        "thumb_image": ...
        "variants": [
          {
             "skuid": "wd8734728608grn",
             "sku_color": "verdant",
             "sku_size": "8",
             "sku_swatch_images": [...],
             "sku_thumb_images": [...],
          },
          ...
        ],

What are the contents of the variants array?

The variants array contains information about the individual SKUs of a product. SKUs are variations or variants of a product. For example, the Tropical Blossoms product comes in three different colors, each of which is represented by different SKUs. If you don't include SKU data in your product feed, then your API responses don't include a variants array nested inside your docs array.

🚧

Your product feed must be current and complete

Just like the rest of the docs array, the variants array can only include attributes that are defined in product feed fields. Even if you include a value like sku_color_group in your API request's &fl parameter, that attribute can only be in your response if your product feed defines it.

Example use case

Jake is a web developer at the online retail site, example. He keeps SKU data in example's product feed. Therefore, any product that has SKUs can have a variants array in his API responses, depending on how he forms the fl parameter value in his API requests. Here's an example of the fl value for one of his product search requests:

&fl=pid,title,brand,price,sale_price,thumb_image,sku_thumb_image,sku_swatch_images,sku_color_group,url,description

For search results pages, Jake includes a limited number of SKU attributes per product. You might notice that he doesn't include the skuid attribute. That's because he wants his search results pages to focus on the larger products. When site visitors click a product in their search results, the product's page contains more detailed SKU data.

The attributes in Jake's variants array describe the alternate colors of the Tropical Blossoms dress and show a thumbnail image of the alternate colors.

"variants": [
          {
            "sku_color_group": "RED",
            "sku_swatch_images": [
              "http://www.example.com/images/color/flutter/ladybug.jpg"
            ],
            "sku_thumb_images": [
              "http://www.example.com/images/sm/tropical-blossoms-flutter.jpg"
            ]
          },
          {
            "sku_color_group": "PURPLE",
            "sku_swatch_images": [
              "http://www.example.com/images/color/flutter/tropical-violet.jpg"
            ],
            "sku_thumb_images": [
              "http://www.example.com/images/sm/tropical-blossoms-alt1-flutter.jpg"
            ]
          },
          {
            "sku_color_group": "GREEN",
            "sku_swatch_images": [
              "http://www.example.com/images/color/flutter/tropical-verdant.jpg"
            ],
            "sku_thumb_images": [
              "http://www.example.com/images/sm/tropical-blossoms-alt2-flutter.jpg"
            ]
          },
        ]
      },
...
    ]
  },

sku_color_group attribute

The sku_color_group attribute indicates the general color, such as red. The designer of the Tropical Blossoms dress calls the color ladybug, which is a shade of red. Lucia might look at the ladybug Tropical Blossoms dress and call the color bright red. Another customer might call the color vermilion. By grouping all shades of red into sku_color_group: "RED", Jake makes it easy for all customers looking for a red dress to find the ladybug Tropical Blossoms dress.

sku_swatch_images array

The sku_swatch_images array contains swatches of the color group. A swatch image is just an image of the color, not an image of the dress in that color. Tropical Blossoms comes in one shade of red: ladybug. Therefore, the sku_swatch_images array for the red sku_color_group contains only one swatch image.

Another example: a dress comes in three different shades of blue: midnight, true, and sky. The sku_swatch_images array for that dress' blue sku_color_group has three swatches, one for each shade of blue.

sku_thumb_images array

The sku_thumb_images array contains the thumbnail images for the product's SKU. There is only one thumbnail image for the red Tropical Blossoms dress because ladybug is the only shade of red that the designer makes for the Tropical Blossoms dress.

Another example: a dress comes in three different shades of blue, so it has three thumbnail images in its sku_thumb_images array.

Which SKU attributes does BloomReach return in API responses?