🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
Integrations / Salesforce Commerce Cloud B2C

Attributes and properties

You can export a B2C business object attribute with the same name (1:1 mapping, the name of the attribute in your Algolia product records is the same) or under a different one.

Simple and complex values

You can export some values as the string value of the attribute (simple values like name) or nested values with direct access. For example, you can access the revenueWeek attribute of a product’s activeData object by declaring activeData.revenueWeek.

Other values are complex and are computed. For example, the in_stock property is exported as product.getAvailabilityModel().getInventoryRecord().getAST().getValue() >= ALGOLIA_IN_STOCK_THRESHOLD. You might also want to regroup several attributes under a single top-level attribute,—for example, the price attribute in different currencies.

You can extend the aggregatedValueHandlers object in algoliaLocalizedProduct.js to define how to export such complex attributes. For more detailed examples, see Use a custom function or the FAQ.

What data does the cartridge send?

The cartridge monitors the following data:

  • products, restricted to the attributes listed in your custom preferences (AlgoliaProductIndex_v2, AlgoliaProductDeltaIndex_v2);
  • categories (AlgoliaCategoryIndex_v2)
  • inventory data, which adds in_stock: true|false attribute to your products indices (AlgoliaProductInventoryIndex_v2 - also part of AlgoliaProductIndex_v2 and AlgoliaProductDeltaIndex_v2)
  • price books (including promotional prices), which adds price and promotionalPrice attributes for all your site’s currencies (AlgoliaProductPriceIndex_v2 only price by default - also part of AlgoliaProductIndex_v2, AlgoliaProductDeltaIndex_v2)


A typical installation on a site featuring:

  • hostname: example.com
  • site-id: clothing
  • 2 locales: en_US, fr_FR
  • 2 currencies: USD, EUR
  • 5 additional product attributes: short_description, long_description, brand, color, size

This setup will generate the following indices in Algolia:

  • example-com__clothing__products__en_US
  • example-com__clothing__products__fr_FR
  • example-com__clothing__categories__en_US
  • example-com__clothing__categories__fr_FR

Algolia generates a separate product and category index for each locale to give you the most flexibility in terms of configuration. This setup lets you to have synonyms, rules, and other locale-specific settings on your index without interfering with the settings for other locales.

The prefix ${hostname}__${site_id} prevents accidental name collisions between your environments. It makes using a single Algolia application with multiple sandboxes or sites completely safe. You can always change the prefix with the Algolia_IndexPrefix custom site preference.

A typical record in these indices has the following structure:

// index: example-com__clothing__products__en_US

// Base set (non-configurable attributes)
// theses fields are always added to your product record
  "objectID": "8987698M",
  "categories": [
        { "id": "womens-tops-tshirts", "name": "T-Shirts" },
        { "id": "womens-tops", "name": "Tops" },
        { "id": "womens", "name": "Women" }
  "__primary_category": {
     "0": "Womens",
     "1": "Womens > Tops",
     "2": "Womens > Tops > T-shirts"
  "in_stock": true,
  "price": {
    "USD": 12.99,
    "EUR": 11.99
  // configurable attributes
  "name": "Red T-shirt from PopularBrand",
  "short_description": "Short description of this red t-shirt",
  "long_description": "A much longer description of this red t-shirt",
  "brand": "PopularBrand",
  "color": "Red",
  "size": "L",
  "image_groups": [ /* */ ],
  "url": "/s/RefArch/womens/tops/tshirts/8987698M?lang=en_US"

Configure extra attributes for AlgoliaProductIndex_v2 and AlgoliaProductDeltaIndex_v2

You can configure the list of attributes that are exported to your Algolia index. The list has a set of base attributes which you can extend to match your business needs. Configure the product attributes to send to Algolia by adding them to the Additional Product Attributes preference. You should do this before performing a complete (re)index of your data.

  1. Go to Merchant Tools > Algolia > Algolia

    Configure Algolia custom site preferences

  2. Set up your Additional Product Attributes:

    Configure additional product attributes

Base attributes (non-configurable)

The base set of attributes is always included in product indexing, except when using the attributeListOverride job step parameter, which overrides both the base attributes and any additional product attributes configured for that job.

Attribute Description
name Name of the product
primary_category_id Primary category ID
categories Array of categories assigned to the product, with all their parent categories
url URL pointing to the product’s PDP (Product Detail Page).
image_groups Array of product image URLs
in_stock true if the number of products available is greater than the InStock Threshold you’ve set, false otherwise
price Product price

Configurable attributes

You can choose to send additional Product record attributes such as the following to Algolia by defining them in Additional Product Attributes.

You should start with the following attributes: short_description, long_description, then expand the list according to your use case (for example brand, color, size).

Attribute Description
EAN The European Article Number of the product.
UPC The Universal Product Code of the product.
brand The brand of the product.
bundle Identifies if this product instance is a product bundle.
bundled Identifies if this product instance is bundled within at least one product bundle.
bundledProducts A collection containing all products that participate in the product bundle.
color The product’s color.
long_description Full description of product.
manufacturerName The name of the product manufacturer.
manufacturerSKU The value of the manufacturer’s stock keeping unit.
master Identifies if this product instance is a product master.
online The online status of the product. This is determined based on the product’s online status flag, and the onlineFrom and onlineTo dates.
optionProduct Identifies if the product has options.
pageDescription Returns product’s page description in the default locale.
pageKeywords The product’s page keywords in the default locale.
pageTitle The product’s page title in the default locale.
productSetProduct true if this product is part of any product set, otherwise false.
productSet Returns true if the instance represents a product set, otherwise false.
promotionalPrice Product promotional price( calculated as product level.
promotions Available at the time of job run. Not taking into account user group, geolocation, and other storefront-related information.
refinementColor Search Refinement Bucket of the color
searchable Identifies if the product is searchable.
size The product’s size.
short_description Short description of product.
unit The products sales unit.
url Storefront product page link.
variant Identifies if this product instance belongs to a product master.

Add custom attributes

To add or create custom attributes, override the int_algolia/cartridge/scripts/algolia/lib/algoliaProductConfig.js file and update the attributeConfig_v2 object:

    /* ... */
    "algolia_attribute_name": {
        "attribute": custom.screenSize,
        "localized": false
Property Name Type Description
algolia_attribute_name string Product attribute name for export to Algolia index.
attribute string The full path to the SFCC Product attribute name separated by a dot.
localized boolean Should be true if the attribute is localized.

After adding the description of the custom attribute to the configuration file, you can add it to the Additional Product Attributes site preference in the Algolia BM module.

Some attributes are protected. Don’t create or modify attributes with the same name.

Use a custom function

For more complex attributes, use a custom function handler:

  1. Add a new attribute definition in the attributeConfig_v2 object, without the attribute property.

    var attributeConfig_v2 = {
      /* ... */
      "your_custom_attribute": {
        "localized": false, // if true, will be recomputed for each locale
  2. Declare a custom function in the aggregatedValueHandlers object of the int_algolia/cartridge/scripts/algolia/model/algoliaLocalizedProduct.js file. The value returned by the function will be added to your product records, in the your_custom_attribute attribute.

    var aggregatedValueHandlers = {
      /* ... */
      your_custom_attribute: function (product) {
        // Implement any custom computation here
        // The returned value will be added to a 'your_custom_attribute' attribute in the indexed records
       return /* ... */;

Any additional attribute added to the Product Model must be added to the Additional Product Attributes site preference in the Algolia BM module.

To add, remove, or customize attributes before sending them to Algolia, you can also override the customizeLocalizedProductModel function in the int_algolia/cartridge/scripts/algolia/customization/productModelCustomizer.js module. This permits to do post-processing operations on the final records, after all attributes have been fetched.

Some attributes are protected. Don’t create or modify attributes with the same name.

Protected attributes

The following attributes are used by Algolia to structure your indices. Don’t add, remove, or modify them:

  • id
  • primary_category_id
  • __primary_category
  • categories
  • in_stock
  • variants
  • _tags

Configure extra attributes for AlgoliaProductPriceIndex_v2 and AlgoliaProductInventoryIndex_v2

To extend the list of attributes sent by these jobs, select the job you want to configure in BM, go to the Jobs Steps tab, select the job step and edit the attributeListOverride parameter. Additional attributes can increase the job’s total runtime depending on the complexity of retrieving the attribute:

  • Nested attributes from B2C model classes take longer to retrieve than the product’s own properties
  • Calculated values take longer to retrieve than static values.

By default, these jobs send the following attributes:

  • AlgoliaProductPriceIndex_v2: price
  • AlgoliaProductInventoryIndex_v2: in_stock

If you extend the list of exported attributes, make sure to add the same attributes to the Additional Product Attributes site preference in the Algolia BM module as well so that the product delta export job also includes those attributes and updates them during its run.

Did you find this page helpful?