Use JSONata expressions in data mappings inside the Product sync module to transform your commercetools product data into the format required by the AI provider.
Each expression is evaluated against a single entry in the product feed. Expressions can access product fields directly, apply conditional logic, and call built-in helper functions called bindings.
Product data object
productData: the full ProductProjection for the current product.variant: the Product Variant that this feed entry represents, extracted from the product's variants.store: the Store context for the Agentic Channel.shippingMethods: available ShippingMethod resources.
price field (singular). For mapping expressions, prefer variant.price as the primary price source.The following simplified example shows the structure of a single feed entry. Fields not relevant to data mapping are omitted.
{
"productData": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": { "en-US": "Classic Running Shoe", "de-DE": "Klassischer Laufschuh" },
"description": { "en-US": "A versatile everyday running shoe." },
"slug": { "en-US": "classic-running-shoe" },
"masterVariant": {
"id": 1,
"key": "classic-running-shoe-master",
"sku": "CRS-001-BLK-42"
},
"variants": [
{
"id": 2,
"key": "classic-running-shoe-v2",
"sku": "CRS-001-BLK-43"
}
]
},
"variant": {
"id": 1,
"key": "classic-running-shoe-master",
"sku": "CRS-001-BLK-42",
"price": {
"id": "a1b2c3d4-5678-4abc-b3fc-2c963f66afa6",
"value": { "centAmount": 12999, "currencyCode": "USD", "fractionDigits": 2 },
"channel": { "id": "956d220a-fde7-44be-8496-c852fed723ca" }
},
"attributes": [
{ "name": "color", "value": "black" },
{ "name": "size", "value": 42 }
],
"availability": {
"isOnStock": true,
"availableQuantity": 100
}
},
"store": {
"id": "store-ABC"
},
"shippingMethods": [
{
"id": "sm-standard"
},
{
"id": "sm-express"
}
]
}
This example shows how multiple resources are combined in a single feed entry. For full field-level details, refer to the API type definitions:
productDatafollows the ProductProjection shape.variantfollows the ProductVariant shape.storefollows the Store shape.shippingMethodscontains ShippingMethod resources.
Default bindings
Bindings are values and helper functions available to expressions at runtime. Variable bindings are always injected from your Agentic Channel configuration as read-only values. Function bindings can be available in provider templates as reusable helpers.
Variable bindings
The following variable bindings are available in every expression. Their values are derived from the Store and Channel configuration of your Agentic Channel, and cannot be reassigned. They are always injected and read-only.
| Binding | Type | Example value | Description |
|---|---|---|---|
$country | string | "US" | Country code from the Store configuration. |
$locale | string | "en-US" | Default locale from the Store configuration. |
Function bindings
The following function bindings are common helper examples. Depending on the selected provider template, additional helper functions can be available, and some functions can differ.
| Binding | Description |
|---|---|
$getAttribute(attributes, name) | Returns the value of a named attribute from a variant's attributes array. |
$priceToAmount(price) | Extracts the numeric price amount from the variant price object, accounting for fractionDigits. |
$formatPrice(price) | Returns a formatted price string from the variant price object (for example, "129.99"). |
Expression examples
The following examples show expressions of increasing complexity, from direct field access to derived transformations.
Access fields directly
The simplest expressions access a field directly from the product entry.
variant.sku
Localized fields are plain objects keyed by locale. Use a string key with backticks when the locale contains a hyphen.
productData.name.`en-US`
productData.id
Use bindings and conditionals
Intermediate expressions use bindings, conditionals, or string operations.
$locale variable binding and $lookup to access the localized value dynamically, without hardcoding a language.$lookup(productData.name, $locale)
Use a conditional expression to return the string value expected by the provider.
variant.availability.isOnStock ? "in_stock" : "out_of_stock"
$getAttribute, use it to retrieve a named attribute from the variant's attributes array.$getAttribute(variant.attributes, "color")
Build derived values
Complex expressions combine multiple fields, optional helper functions, and logic to produce derived values.
$priceToAmount to correctly account for the currency's fractionDigits value.$priceToAmount(variant.price)
centAmount by the appropriate power of 10 based on fractionDigits:variant.price.value.centAmount / $power(10, variant.price.value.fractionDigits)
$formatPrice, you can format the same scoped price value.$formatPrice(variant.price)
Combine the localized product name with custom attribute values to produce a richer title string.
$lookup(productData.name, $locale) & " - " & $getAttribute(variant.attributes, "color") & " / " & $string($getAttribute(variant.attributes, "size"))
null or undefined, no value is included in the feed for that field. The effect depends on the field and the provider:- For required fields, the provider fails to process the product.
- For optional fields, the provider removes any existing value, depending on its implementation.
$default operator or conditional logic.