Integrations / commercetools

Product schema

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:

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

{
  // 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
  },
  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
99
100
101
102
103
104

{
  // 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"
  },
  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.

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

Configure results grouping

Results are grouped by default when you use the product-level schema.

For the variant-level schema, if your catalog is large, it’s common practice to group related variants in the results by displaying one result per base product. To do that, Enable the distinct feature one the productID attribute.

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