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:
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
{
// 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,
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
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
{
// 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,
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.
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 theisSearchable
property istrue
. It’s a subset of theattributes
object in the product schema.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
incentAmount
: the smallest unit of the currency such as cents, pence, or centime. - The maximum price
max
incentAmount
- A list of values for each price as
priceValues
with the following properties:id
- The ID of the price.value
- The price incentAmount
.discountedValue
- The discounted price incentAmount
.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.