Integrations / commercetools

Product schema

Algolia’s commercetools integration stores your product data in an extensible format that’s optimal for search.

It uses two different schemas. The appropriate one for you depends on what you chose during installation: variant level or product level.

Variant level schema

Algolia stores commercetools product variants in the following format:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

{
  // Unique ID in the format product ID.variantID
  objectID: "ffdcbccd-fd9d-49fc-8f12-b43a97721300.7",
  productID,
  sku,
  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: {
    color: "blue"
  },
  attributes: {
    color: "blue"
    season: "winter"
  },
  images: [],          // List of image URLs
  prices: {            // Prices by currency
    USD: {
      min: 1000,
      max: 2000,
      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"
        }
      ]
    }
  },
  pricesCustomFields: { // Price defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
    USD: { 
      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
  },
  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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

{
  // Unique ID in the format product ID
  objectID: "ffdcbccd-fd9d-49fc-8f12-b43a97721300",
  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"
  },
  masterVariantID,    // The ID of the primary variant
  variantIDs: [        // List of variant IDs
    "variant-id-1",
    "variant-id-2"
  ]
  variants: [
    {
      id,                  // variant ID
      sku,                 // variant SKU
      searchableAttributes: {
        color: "blue"
      },
      attributes: {
        color: "blue"
      },
      images: [],          // List of image URLs
      prices: {            // Prices by currency
        USD: {
          min: 1000,
          max: 2000,
          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"
            }
          ]
        }
      },
      pricesCustomFields: { // Price defined custom fields, only indexed when the source defines it https://docs.commercetools.com/tutorials/custom-types
        USD: { 
          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.

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

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

Display results grouped by product ID

You can group product variants in the results. For example, when displaying the results in your storefront, you could group multiple colors (variants) of the same t-shirt (product) together.

To group variants, apply Algolia’s distinct feature to the product ID.

If you don’t group variants (default behavior), the results show each variant separately.

Categories

Categories are stored as hierarchical facets.

Category pages are automatically generated and referenced by the categoryPageId attribute.

The categoryKeys attribute is a flattened version of the categories attribute hierarchy.

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 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.
Previous
Monitor indexing
Did you find this page helpful?