Product schema - Algolia

Algolia’s commercetools integration stores your product data in an extensible format that’s optimal for search. The integration can generate two types of records, depending on your record model preference:

Product Variant records: create one record per product variant.
Product records: create one record per base product, containing all the variants in a variants attribute.

You can choose the record model when you configure the destination. For more information about which model best suits your needs, see Ecommerce records.

Variant level schema

Algolia stores commercetools product variants in the following format:

JavaScript

{
  // Unique ID in the format product ID.variantID
  objectID: "ffdcbccd-fd9d-49fc-8f12-b43a97721300.7",
  productID,
  productKey,
  productType,
  key,                 // Variant key
  sku,
  name,                // Name of the product
  description,
  slug: {              // Localized slugs (keys are locales and values are slugs)
    en: "en-slug"
  },
  categories: {        // Localized hierarchical categories for faceting
    en: {
      lvl0: ["Men"],
      lvl1: ["Men > Clothing"],
      lvl2: ["Men > Clothing > T-shirts"]
    }
  },
  categoriesCustomFields: { // Categories defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
    en: {
      Men: {
        "custom-field-name": {
          en: "custom-field-value"
        }
      }
    }
  },
  categoryKeys: {      // Localized unique non-hierarchical categories with ancestors
    en: ["Men", "Clothing", "T-shirts"]
  },
  categoryPageID: [    // Category pages
    "Men",
    "Men > Clothing",
    "Men > Clothing > T-shirts"
  ],
  searchableAttributes: {
    color: "blue"
  },
  attributes: {
    color: "blue"
    season: "winter"
  },
  images: [],          // List of image URLs
  prices: {            // Prices by currency
    USD: {
      min: 1000,
      max: 2000,
      customerGroups: [
        {
          id: "customer-group-id-1",
          price: 1000
        }
      ],
      priceValues: [ // List of all prices with optional values
        {
          id: "price-id-1",
          value: 1000,
          discountedValue: 995,
          validFrom: "2023-01-01T00:00:00.000Z",
          validUntil: "2023-02-01T00:00:00.000Z",
          customerGroupID: "customer-group-id-1",
          customFields: { // Price defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
            "custom-field-name": {
              en: "price-custom-field-value"
            }
          }
        }
      ]
    }
  },
  isMasterVariant,     // `true` if this record is the primary variant
  isInStock,           // `true` if this SKU is in stock
  inventory: {         // inventory information by supply channel
    "channel-key-1": 100,
    "channel-key-2": 120
  },
  reviewStatistics: { // Product review information as stored in commercetools
    "avg": 4.07037,
    "max": 5,
    "min": 3,
    "count": 1009,
    "distribution": {
        "5": 254,
        "4": 572,
        "3": 183
    }
  },
  inventoryCustomFields: { // Inventory defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
    "channel-key-1": {
      "custom-field-name-in-channel-1": {
        en: "inventory-custom-field-value"
      }
    },
    "channel-key-2": {
      "custom-field-name-in-channel-2": {
        en: "inventory-custom-field-value"
      }
    }
  }
}

Product level schema

JavaScript

{
  // Unique ID in the format product ID
  objectID: "ffdcbccd-fd9d-49fc-8f12-b43a97721300",
  key,                 // Product key
  productType,
  name,                // Name of the product
  description,
  slug: {              // Localized slugs (keys are locales and values are slugs)
    en: "en-slug"
  },
  categories: {        // Localized hierarchical categories for faceting
    en: {
      lvl0: ["Men"],
      lvl1: ["Men > Clothing"],
      lvl2: ["Men > Clothing > T-shirts"]
    }
  },
  categoriesCustomFields: { // Categories defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
    en: {
      Men: {
        "custom-field-name": {
          en: "custom-field-value"
        }
      }
    }
  },
  categoryKeys: {      // Localized unique non-hierarchical categories with ancestors
    en: ["Men", "Clothing", "T-shirts"]
  },
  categoryPageID: [   // Category pages
    "Men",
    "Men > Clothing",
    "Men > Clothing > T-shirts"
  ],
  searchableAttributes: {
    season: "winter"
  },
  attributes: {
    season: "winter"
  },
  reviewStatistics: { // Product review information as stored in commercetools
    "avg": 4.07037,
    "max": 5,
    "min": 3,
    "count": 1009,
    "distribution": {
        "5": 254,
        "4": 572,
        "3": 183
    }
  },
  masterVariantID,    // The ID of the primary variant
  variantIDs: [        // List of variant IDs
    "variant-id-1",
    "variant-id-2"
  ],
  variants: [
    {
      id,                  // variant ID
      key,                 // variant key
      sku,                 // variant SKU
      searchableAttributes: {
        color: "blue"
      },
      attributes: {
        color: "blue"
      },
      images: [],          // List of image URLs
      prices: {            // Prices by currency
        USD: {
          min: 1000,
          max: 2000,
          customerGroups: [
            {
              id: "customer-group-id-1",
              price: 1000
            }
          ],
          priceValues: [   // List of all prices with optional values
            {
              id: "price-id-1",
              value: 1000,
              discountedValue: 995,
              validFrom: "2023-01-01T00:00:00.000Z",
              validUntil: "2023-02-01T00:00:00.000Z",
              customerGroupID: "customer-group-id-1",
              customFields: { // Price defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
                "custom-field-name": {
                  en: "price-custom-field-value"
                }
              }
            }
          ]
        }
      },
      isInStock,          // `true` if this SKU is in stock
      inventory: {        // inventory information by supply channel
        "channel-key-1": 100,
        "channel-key-2": 120
      },
      inventoryCustomFields: { // Inventory defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
        "channel-key-1": {
          "custom-field-name-in-channel-1": {
            en: "inventory-custom-field-value"
          }
        },
        "channel-key-2": {
          "custom-field-name-in-channel-2": {
            en: "inventory-custom-field-value"
          }
        }
      }
    }
  ]
}

The attributes field lists all the commercetools product attributes.

Attributes used for search

By default, users can search in the following attributes, ranked in order of importance:

name
description
searchableAttributes. All commercetools product attributes where the isSearchable property is true. It’s a subset of the attributes object in the product schema.
categories

Configure results grouping

Results are grouped by default when you use the product-level schema. In a variant-level schema, large catalogs often group related variants to show one result per base product. To enable this, set the distinct feature and use productID as the attributeForDistinct.

Changes to your commercetools inventory

Algolia’s commercetools integration monitors inventory changes and sets the isInStock value for each affected SKU. isInStock is true if the inventory for any supply channel is greater than zero for that SKU.

Prices

The prices attribute consists of key-value pairs with currency codes as keys, such as “USD”. Values contain:

The minimum price min in centAmount: the smallest unit of the currency such as cents, pence, or centime.
The maximum price max in centAmount
A list of all the Customer Groups set in the prices as customerGroups with the following properties:
- id. The ID of the Customer Group.
- price. The price of the Customer Group in centAmount.
A list of values for each price as priceValues with the following properties:
- id. The ID of the price.
- value. The price in centAmount.
- discountedValue. The discounted price in centAmount.
- validFrom. The date from which the price is valid.
- validUntil. The date until which the price is valid.
- customerGroupID. The ID of the customer group to which the price applies.

commercetools

​Variant level schema

​Product level schema

​Attributes used for search

​Configure results grouping

​Categories

​Changes to your commercetools inventory

​Prices