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 :

Attribute

Description

pid

The product ID.

title

The title or name of the product.

brand

The brand or designer name of the product.

url

The URL where the product is located.

price

The price of the product.

sale_price

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.

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

SKU attribute

Description

skuid

The SKU ID.

sku_thumb_images

The thumb image for the SKU.

sku_large_images

The larger image for the SKU.

sku_swatch_images

The swatch image for the SKU's color.

sku_color

The color of the SKU.

sku_color_group

The color group of the SKU.

sku_size

The size of the SKU.

sku_price

The regular price of the SKU.

sku_sale_price

The sale price of the SKU.