Product data feed specifications

Sitecore Discover relies on standardized product attributes that enable platform-wide features and capabilities such as analytics, built-in recipes, site contexts, specialized facet experiences, and so on. Based on the experiences you want to implement on your site, you might also need to add custom attributes the product feed. Discuss any requirements for custom attributes with your Sitecore integration specialist.

This topic lists and describes the product attributes that Sitecore Discover predefines for the catalog data feed.

Note

A Sitecore integration specialist helps you determine the product attributes you need to provide, based on the experiences you want to create for your site visitors and business users.

Discover product attributes

This section describes default product attributes are available to all customers who subscribe to Sitecore Discover product discovery platform.

As per the data feed format requirements, each product attribute corresponds to a column name in the product data feed file.

The following table lists and describes both required and optional product attributes:

Note

When applicable, the examples provided in the following table use the pipe symbol (|) as a list separator.

Attribute

Type

Description

Example

product_group

string

Required.

Unique string used to identify a group of SKUs or an individual SKU.

For example, all size and color variations of a shirt can be grouped into a product_group.

When not specified, all products sharing a particular URL are grouped together.

234sbc

name

string

Required.

Name of the product.

Red winter rubber boots

product_url

string

Required.

URL of the product details page for this product (relative to the website's host).

/product/red-winter-rubber-boots

image_url

string (absolute URL)

Required.

Widgets use this absolute URL to display a product or SKU image. The optimal size for websites is around 300 pixels x 300 pixels.

URL must be absolute because it can be served from a host different from the website's host. Multiple SKUs can have the same URL.

https://images.domain.com/product/red-winter-rubber-boots-300x300.jpg

description

string

Optional.

Product description including all relevant information.

Do not include any tabs, carriage returns, and HTML tags. Escape all characters that might break the file.

This great long-sleeved shirt is made of 100% cotton with breathing capability for hot summers.

sku

string

Required.

The stock keeping unit (SKU) used to identify a particular product.

sku_name

string

Required.

Name associated with the SKU, if different from the product name.

sku_url

string

Required.

The URL of the SKU details page for this product, if different from the product_URL. It is a relative URL.

/product/red-winter-rubber-boots/sku1234

sku_image_url

string

Required.

Image URL connected to a particular product and used to show a SKU in widgets. You can use the same URL for several SKUs. It is an absolute URL as images might be served from a different host. Optimal image size is around 300 x 300 pixels.

https://images.domain.com/product/red-winter-rubber-boots-sku1234-300x300.jpg

sku_description

string

Required.

Description of the SKU.

ccids

string

Required.

List of customer category IDs (CCIDs) that this SKU or product belongs to. These IDs must be the same as those defined as CCIDs in the category feed. Provide only the leaf (lowest level) categories.

To list multiple CCIDs, use the separator (|) .

Discover can create category hierarchy in two ways. It can either create them from CCIDs, or it can create them from categories and their parent category (defined as parent_ccid, in the category feed).

Example leaf category IDs: cat123|cat456

Example hierarchical category IDs: cat1>cat12>cat123|cat4>cat45>cat456

category_breadcrumbs

string

Required only if CCIDs and the category feed are not available.

Path from the root category to the product.

If the product is under multiple levels of categories, delimit each category in the path using >.

If the product belongs to multiple categories, delimit the categories using a pipe | in the path.

Shoes>boots>Rubber Boots|Raingear>Accessories

price

float

Required.

Catalog price in any currency as a double precision floating point number. Do not include the currency symbol as part of the price attribute value.

22.22

final_price

float

Required.

The current final price of the product that the customer must pay. Do not include the currency symbol as part of the price attribute value.

If there is no discount, enter the value entered for price.

22.22

is_active

Boolean

Required.

Flag (0|1) to indicate whether to display the product in Discover.

Default: 1 (to display product)

1

product_type

string

Optional.

Type of product ( product, sku, set, or bundle). By default, Discover sorts products or SKUs based on their product_group values, and constructs an object to contain all SKUs that belong to a product.

Discover processes sets and bundles as products.

Possible values are:

product - might be an individual product, or a product that represents multiple variants.

sku - a single variant of the product. If there are no variants, product_type is the same as product.

set - also known as grouped products, this is a set of SKUs/products that forms a set, but users must buy each SKU individually.

bundle - a specific set of SKUs sold as a bundle. A bundle has its own price, sale-price, and so on.

set_skus

string

Optional.

Product groups or SKUs that are part of a set, if the product_type = set.

sku1|sku2|sku3| or prod_group1|prod_group2|prod_group3|

bundle_skus

string

Optional.

Product groups or SKUs that are part of a bundle, if the product_type = bundle.

sku1|sku2|sku3|

or

prod_group1|prod_group2|prod_group3|

stock_quantity

integer

Optional.

The number of items of the given SKU available in stock.

44

stock_unit

string

Optional.

The name of the measurement unit used for stock quantity.

each

sku_sequence

integer

Optional.

The order of SKUs within a product group. Used to organize the SKUs within a product in ascending order, based on availability. The lowest integer is selected as the default SKU, and its image is shown at the product level. SKUs that are not in stock are always listed last.

add_to_cart

string

Optional.

Any attribute used to create custom add-to-cart experiences. Requires JavaScript function (this can be sent outside of the data feed). Any values that need to be passed within the function can be included in the feed.

quick_view or quick_look

string

Optional.

Any attribute used to create custom experience with third-party quick view integration. Requires JavaScript function (this can be sent outside of feed). Any values that need to be passed within the function can be included in the feed.

search_keywords

string

Optional.

A number of keywords that are associated with the product during search.

List of keywords separated by spaces.

hat cap beanie visor

additional_image_urls

string

Optional.

A list of additional URLs (formatted as absolute URLs) if multiple images are required for a particular product.

https://images.domain.com/product/red-winter-rubber-boots-back-300x300.jpg|https://images.domain.com/product/red-winter-rubber-boots-side-300x300.jp

additional_sku_image_urls

string

Optional.

A list of additional URLs (formatted as absolute URLs) if multiple images are required for a particular SKU.

https://images.domain.com/product/red-winter-rubber-boots-back-300x300.jpg|https://images.domain.com/product/red-winter-rubber-boots-side-300x300.jpg

promotion_flag

string

Optional.

A flag that specifies the overlay image value (for example, Sale, New, Clearance).

save_off

integer / float

Optional.

The percentage value of the savings. For example, Save 40%. Only provide the numerical value. Can be a double precision floating point number if appropriate.

40

brand

string

Optional.

The brand of the product in question.

Sitecore

brand_code

string

Optional.

The number code assigned to a brand.

123abc

mobile_product_url

string

Optional.

Alternative product URL for mobile pages. Use if your e-commerce site does not automatically detect mobile browsing.

/mobile/product/red-winter-rubber-boots

mobile_image_url

string

Optional.

Alternative product image URL for mobile pages. Separate multiple image_urls using pipe (|). Use if your e-commerce site does not automatically detect mobile browsing.

mobile_sku_url

string

Optional.

Alternative SKU URL (relative URL) for mobile pages if different from the mobile_product_url. Use if your e-commerce systems cannot automatically detect mobile browsers.

/mobile/product/red-winter-rubber-boots/sku1234

mobile_sku_image_url

string

Optional.

Alternative SKU image URL (relative URL) for mobile pages. Can be the same UR: for several SKUs. This image is used to show the product in the widgets. Optimal image size for a website is around 300 x 300. Use if your e-commerce system cannot automatically detect mobile browsers.

https://images.domain.com/product/red-winter-rubber-boots-sku1234-300x300-mobile.jpg

color

string

Optional.

Color of the product. Separate multiple colors using a pipe (|) character.

red|orange

color_display_name

string

Optional.

A display name attached to the product. Separate multiple names using a pipe (|) character.

Autumn red|Auburn

color_rgb

string

Optional.

The hex code for a color.

#ff34bc

size

string

Optional.

The size of the particular item.

XL

review_rating

float

Optional.

Number representing the rating in product review rating. Float with single digit precision.

4.5

review_count

integer

Optional.

Number of reviews for this product.

review_link

string

Optional.

The path linking to a product's customer reviews. It can be an absolute or relative path.

margin

float

Optional.

Sales price minus the cost of goods. Double precision floating point number.

25.50

rankby1

float

Optional.

Any value that you might use to customize search ranking experiences. For example, you might use an algorithm to compute ranking order based on business goals.

rankby2

float

Optional.

Any value that you might use to customize search ranking experiences. For example, you might use an algorithm to compute ranking order based on business goals.

Timed product availability attributes

The following table lists and describes the product attributes that support timed product releases, to make a product available or unavailable on a specific date:

Attribute

Type

Description

Example

release_date

string

Required.

Date when the product is available. Can be a date in the future. Date format is ISO 8601 standard:

  • YYYY-MM-DD

  • YYYY-MM-DDThh:mm:ss

  • YYYY-MM-DDThh:mm:ssZ

Date is converted and stored in Discover as a timestamp (UTC). It is used to compute the is_active flag.

2023-04-01

2023-04-01T19:47:25

2019-04-01T19:47:25Z

expiration_date

string

Date when the product or SKU becomes unavailable. Date format is ISO 8601 standard:

  • YYYY-MM-DD

  • YYYY-MM-DDThh:mm:ss

  • YYYY-MM-DDThh:mm:ssZ

The expiration date must be later than the release_date.

23-05-01

2023-05-01T19:47:25

2023-05-01T19:47:25Z

Fitment and cross-category recommendations attributes

The following table lists and describes the product attributes that are required to support fitment and cross-category recommendations:

Attribute

Type

Description

Example

cfids

string

Required.

Customer fitment IDs that this SKU or product is compatible with. These IDs must be the same as the cfid included in the fitment feed.

12345|F1234|c456|9023

fitment_tags (compatible_tags)

string

Required.

List of tags that identify compatibility with other products. To determine compatible products to recommend, Discover looks for products across the catalog with at least one matching tag.

model1|model2|model3

cross_category_skus

string

Required.

List of SKUs to use for cross-category recommendations for this SKU.

sku1|sku2|sku3

Product availability and restriction attributes in multistore and B2B scenarios

If your Discover implementation is set up for B2B or multistore support, these attributes give you the ability to manage product or SKU availability and restriction for each store/customer. You manage product availability using an inclusion list (availability_whitelist). You manage availability restrictions using an exclusion list (availability_blacklist).

Note

Store and group IDs can't contain an underscore (_).

An inclusion list (availability_whitelist) contains B2B customers or stores where the product or SKU is available.

An exclusion list (availability_blacklist) contains B2B customers or stores where the product or SKU is not available.

As a general guideline, you use the option that produces the least amount of data to transfer. During your on-boarding, a Sitecore integration specialist helps you determine the optimal approach based on your specific implementation.

The following table describes the product attributes that are required to manage product availability and restriction for each store/customer:

Attribute

Type

Description

Example

availability_whitelist

string

Optional.

List of customer IDs for which the product or SKU is available.

A product can use either a whitelist or a blacklist, not both.

Product inventory is managed using stock quantity overrides or the stock_quantity attributes. Your Sitecore integration specialist can help determine the best method for your implementation.

s1|s2|s3

availability_blacklist

string

Optional.

List of customer/store IDs for which the product or SKU is not available.

A product can either use a whitelist or a blacklist, not both.

Product inventory is managed using stock quantity overrides or the stock_quantity attributes. Your Sitecore integration specialist can help determine the best method for your implementation.

s1|s2|s3

group_availability_whitelist

string

Optional.

List of customer group IDs for which the product or SKU is available.

A product can use either a whitelist group or a blacklist group, not both.

If a blacklist and a whitelist is specified at different levels, (that is, group_availability_whitelist and availability_blacklist, or vice versa) for a given product, then there must be a hierarchical relationship between the store/customer and store/customer groups. Otherwise, unpredictable behavior might occur.

g1|g2|g3

group_availability_blacklist

string

Optional.

List of customer group IDs for which the product or SKU is not available.

A product can either have a whitelist or a blacklist, not both.

If a blacklist and whitelist is specified at different levels (that is, group_availability_whitelist and availability_blacklist, or vice versa) for a given product, then there must be a hierarchical relationship between store/customer and store/customer groups. Otherwise, unpredictable behavior might occur.

g1|g2|g3

Override attributes for multistore and B2B scenarios

If your Discover implementation supports a B2B or multistore scenario, you can use these attributes to manage product price and stock quantities for each store or for each customer.

Attribute

Type

Description

Example

override_price

string

Optional.

Specifies price for each store or each B2B customer in a one-level organization of customers or stores.

Price overrides are only supported at the product level, and not at the SKU level.

g1/s1:23.45|g2/s2:45.89|

group_override_price

string

Optional.

Specifies price for each group of stores or group of customers, if you have a two-level grouping of your customers or stores, and you manage them as a group.

Price overrides are only supported at the product level, and not at the SKU level.

g1:23.45|g2:45.89

override_stock_quantity

string

Optional.

Specifies stock quantity (inventory) for each store or each customer in a one-level organization of customers or stores.

g1/s1:23|g2/s2:45|

group_override_stock_quantity

string

Optional.

Specifies stock quantity (inventory) for each group of stores or each group of customers, if you have a two-level grouping of customers or stores, and you manage them as a group.

g1:23|g2:45|

Locale attributes

There are two approaches you can choose from to specify localized attribute values in the feed file. You can either use locale (a combination of country and language) or you can specify languages.

Use a consistent approach in your feed file to manage locale, that is, either use a single column with a list of values, or use one column for each locale value. We recommend that you not mix the different formats. As a general rule, when Discover reads and processes locale information, the following precedence applies:

  • If a locale specific attribute column exists, then Discover uses it.

    Otherwise...

  • If a language specific attribute column exists, then Discover uses it.

The following table contains attributes you can use to manage locale in Discover:

Attribute

Type

Description

Example

<attribute>_locale

string

Optional.

Provides locale specific values for any attribute in a locale:value format, where multiple values are separated using a list separator.

In the feed file, the default value of an attribute is specified in its own column.

For example for the name attribute:

Column header: name_locale

Locale values: <locale1>:value|<locale2>:value|...

Column header: name_locale

Values: fr_ch:Bottes d'hiver en caoutchouc rouge|de_ch:Rote Wintergummistiefel

<attribute>_language

string

Optional.

Provides language specific values for any attribute, in a <language>:value format, using a list separator for multiple languages support. Useful when you have a small number of languages shared across multiple countries.

The default value of an attribute is specified in a separate column.

Column header: name_language

Values: fr:Bottes d'hiver en caoutchouc rouge|de:Rote Wintergummistiefel

<attribute>_locale_<locale>

string

Optional.

Used as an alternative to <attribute>_locale.

Specify one locale value for each column.

For example, for the attribute name, where country is Switzerland (ch), and languages are English en, French fr, and German de, corresponding attributes (column headers) are: name_locale_en_ch, name_locale_fr_ch, name_locale_de_ch.

Column header: name_locale_en_ch Value: Red Winter Rubber Boots

Column header: name_locale_fr_ch Value: Bottes d'hiver en caoutchouc rouge

Column header: name_locale_de_ch Value: Rote Wintergummistiefel

<attribute>_locale_<language>

string

Optional.

Used as an alternative to <attribute>_language.

Specify locale or language specific values as one locale or language for each column.

For example, for the attribute name, where supported languages are English (en), French (fr) and German (de), corresponding attributes (column headers) are: name_locale_en, name_locale_fr, name_locale_de.

Column header: name_locale_en Value: Red Winter Rubber Boots

Column: name_locale_fr Value: Bottes d'hiver en caoutchouc rouge

Column: name_locale_de Value: Rote Wintergummistiefel

Dynamic product attributes

Sitecore Discover supports the use of dynamic product attributes, mainly to support filtering and faceting. Typically, you use dynamic attributes to accommodate very large product catalogs with a significant number of product attributes, where only a small number of these attributes are distributed sparsely across products. In these cases, we recommend the use of dynamic product attributes for optimal page rendering performance. A Sitecore integration specialist can help you determine whether dynamic product attributes are suitable in your Discover implementation.

The following table lists and describes dynamic product attributes:

Attribute

Description

dyn_attrs

Optional.

A composite list of multiple attribute names, values (of various data types), and an optional sort order. Use the following convention to list dynamic attributes:

  • label - a string that displays the name of the attribute.

  • value - a string that represents the attribute value. You can mix string and numeric values in one list. All values are treated as string.  If a product attribute is assigned multiple values, use the number sign (#) to separate the values.

  • order - an optional order (float) by which to sort the original values when returned in facets. If not provided, or if same order value is specified more than once, the values are sorted by descending frequency within that facet. Use the number sign (#) to separate multiple order values.

  • name (optional) - an attribute name corresponding to the label following Discover convention. Generated automatically if not provided.

  • name_order - an optional order (float) to use to sort the facet names (label) for this dynamic attribute collection. Sort order is ascending. If no order is specified, or if the same order value is specified more than once, then the facets are ordered by descending frequency.

  • value_id - an optional string you can use to return additional data as part of the facets. There is no specific purpose within Discover.

dyn_attrs_numeric

Optional.

A composite list of multiple attribute names, values (of various data types), and an optional sort order. Use the following convention to list dynamic attributes:

  • label - a required string that displays the name of the attribute.

  • value - a required string or float that represents the attribute value. These attributes are treated as floating numbers, and facets/filters work for range of numbers instead of discrete values.

  • order - an optional order (float) by which to sort the original values when returned in facets. If not provided, or if the same order value is specified more than once, then the values are sorted alphabetically within that facet. Use the number sign (#) to separate multiple order values.

  • name - an optional attribute name corresponding to the label following Discover convention. Generated automatically if not provided.

  • name_order - an optional order (float) to use to sort the facet names (label) for this dynamic attribute collection. The sort order is ascending over the top ten facets with the highest frequency. If no order is specified, or if the same order value is specified more than once, then facets are ordered alphabetically.

Examples

The following shows examples of dynamic attributes (dyn_attrs) that take a mix of string and numeric values in a list:

dyn_attrs values format

Example

<label>;<value>|...

Unit;Pieces|Track Length;121 In.|Lug Height;5/16 in.|Track Color:Red#Blue

<label>;<value>;<order>|...

Unit;Pieces;1|Track Length;121 In.;121|Lug Height;5/16 in.;0.3125

<label>;<value>;<order>;<name>;<name_order>|...

Unit;Pieces;1;unit;35|Track Length;121 In.;121;;21|Lug Height;5/16 in.;0.3125;lug_height;10

JSON format: [{"label":<label>, "value":<value>, "order":<order>, "name":<name>,"name_order":<name_order>, "value_id": <value_id>},{...},...] 

[ {"label":"Unit", "value":"Pieces", "order":1, "name":"unit", "name_order":35}, {"label":"Track Length", "value":"121 In.", "order":121, "name_order":21}, {"label":"Lug Height", "value":"5/16 in.", "order":0.3125, "name": "lug_height", "name_order":10}, ... ]

The following shows a representation of dynamic attributes (dyn_attrs_numeric) that take numeric values in lists:

dyn_attrs_numeric format

Example

<label>;<value>|...

Track Length;121|Lug Height;0.3125

<label>;<value>;<order>|...

Track Length;121;121|Lug Height;0.3125;0.3125

<label>;<value>;<order>;<name>;<name_order>|...

Track Length;121;121;;21|Lug Height;0.3125;0.3125;lug_height;10

[{"label":<label>, "value":<value>, "order":<order>, "name":<name>,"name_order":<name_order>},{...},...]

[ {"label":"Track Length", "value":121, "order":121, "name_order":21}, {"label":"Lug Height", "value":0.3125, "order":0.3125, "name": "lug_height", "name_order":10}, ... ]

Do you have some feedback for us?

If you have suggestions for improving this article,