Requesting product and SKU attributes - Bloomreach Experience - Open Source CMS

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. 

Example keyword search API request

GET http://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 :

  • pid is the product ID.
  • title is the title or name of the product.
  • brand is the brand or designer name of the product.
  • url is the URL where the product is located.
  • price is the price of the product.
  • sale_price is the price of the product on sale.

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.

SKU variants

"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:

Example fl parameter with SKU attributes

&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 dress at example 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.

The dress at example that comes in three different shades of blue has three thumbnail images in its sku_thumb_images array.

Which SKU attributes does BloomReach return in API responses?

Here's a list of the standard SKU attributes that BloomReach can return in API responses:

  • skuid is the SKU ID.
  • sku_thumb_images is the thumb image for the SKU.
  • sku_large_images is the larger image for the SKU.
  • sku_swatch_images is the swatch image for the SKU's color.
  • sku_color is the color of the SKU, such as verdant or lavender.
  • sku_color_group is the color group of the SKU, such as green or purple.
  • sku_size is size of the SKU.
  • sku_price is the regular price of the SKU.
  • sku_sale_price is the discounted price of the SKU.
  • sku_size is the size of the SKU.
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?