Documentation

Discount Predicate Field Identifiers

Some resources in the commercetools API have a predicate or cartPredicate field. In particular, Product Discounts, Cart Discounts, and Shipping Method have predicate fields. This field expects a conditional statement known as a predicate. When a predicate evaluates as true, the API applies the discount or selects a shipping method. Predicates consist of field identifiers and operators. For more information on creating predicates, see Discount Predicate Operators.

You cannot use field identifiers listed here to construct API queries using the where field. General purpose queries use a different syntax. For more information, see Query Predicates.

ProductDiscount predicates

ProductDiscount predicates reference a field on a Product or a field on a ProductVariant's Price.

You can only use ProductDiscount field identifiers for creating Product Discounts.

Product field identifiers

The following identifiers reference fields on a Product.

  • product.id - UUID
  • product.key - String
  • productType.id - UUID
  • productType.key - String
  • variant.id - Number
  • variant.key - String
  • sku - String
  • attributes.<name>
    Matches a Product Attribute by its name. For more information, see Product Attribute Field Identifiers.

Price field identifiers

The following identifiers reference fields on a ProductVariant's Price.

  • price - Money
  • amount - Number - The amount in the specified currency.
  • centAmount - Number - The amount in cents (the subunit) of the specified currency.
  • currency- String - Currency code
  • country - String - Country code
  • customerGroup.id - UUID
  • customerGroup.key - String
  • channel.id - UUID
  • channel.key - String

Category field identifiers

The following identifiers identify products that have a specific Category or group of categories.

  • categories.id - Array of UUID Identifies all Products that have a category.
  • categories.key - Array of Strings Identifies all Products that have a category with a given key.
  • categoriesWithAncestors.id - Array of UUID
    Identifies all Products that have a category as well as products in child categories.
  • categoriesWithAncestors.key - Array of Strings Identifies all Products that have a category as well as products in child categories that have a given key.

Product Attribute field identifiers

The following identifiers reference user-defined product attribute fields on a Product.

  • attribute.name - Attribute
    Matches a product attribute by its name.
    If a field name contains a dash (-) or starts with a digit, escape it using backticks (`): attributes.\`2019Season\`

Supported Attribute Types

The following attribute types are supported as individual values or as Sets:

  • boolean
  • text
  • number
  • datetime
  • date
  • time
  • enum
  • lenum
  • money

For enum and lenum attributes, you can only reference a value in the collection using the value's key field.

Product Predicate examples



// match a specific variant in the specific product
product.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7" and variant.id = 1


// match a specific variant based on variant key in the specific product
(product.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7" and variant.id = 1) or variant.key = "blue_shirt"


// match a product that is only in the given category
categories.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"


//match a product that is in the given category
categories.id contains "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"


//match a product that is in all of the the given categories
categories.id contains all ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7", "abcd9a23-14e3-40d0-aee2-3e612fcbefgh")


//match a product that is in one of the the given categories
categories.id contains any ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7", "abcd9a23-14e3-40d0-aee2-3e612fcbefgh")


//match a product that is in the two given categories and in no others
categories.id = ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7", "abcd9a23-14e3-40d0-aee2-3e612fcbefgh")


//match a product that is not in a given category
categories.id != ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7")


//match the prices above 12€ for any countries except France that do not have a customer group set
centAmount > 1200 and currency = "EUR" and country != "FR" and customerGroup.id is not defined


//match all product variants that have size "L" and have the color white and black
//size is an EnumType attribute for which the key is specified in the predicate,
//color is a SetType of Enums for which the keys are listed in the predicate.
attributes.size = "L" and attributes.colors contains all ("black", "white")


//match all product variants with the given sku, the boolean attribute available set to true and the number attribute weight less than 100
sku = "AB-12" and attributes.available = true and attributes.weight < 100


//match all products that are in the given category or in a category that is a descendant of the given category
categoriesWithAncestors.id contains "abcd9a23-14e3-40d0-aee2-3e612fcbefgh"

Cart Predicates

Cart Predicate field identifiers reference fields on a Cart. You can also use Cart Predicate Functions to construct conditional statements based on the state of the cart and its line items.

You can use Cart Predicates for the following:

Cart field identifiers

The following identifiers reference fields on a Cart.

  • currency
    A three-digit currency code as per ISO 4217.
  • country
    A two-digit country code as per ISO 3166-1 alpha-2.
  • totalPrice - Money
  • totalPrice.centAmount - Number
  • totalPrice.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • taxedPrice.net - String - Money
  • taxedPrice.net.centAmount - Number
  • taxedPrice.net.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • taxedPrice.gross - String - Money
  • taxedPrice.gross.centAmount - Number
  • taxedPrice.gross.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • createdAt - String - DateTime
  • lastModifiedAt - String - DateTime
  • shippingAddress - Address
  • billingAddress - Address
  • custom.<name> - CustomField
    Matches a custom field by its name. For more information, see CustomField Predicate Field Identifiers.
  • custom.type.id - id of a Type
  • custom.type.key - key of a Type

Customer field identifiers

The following identifiers reference fields on a Cart's Customer.

  • customer.id - UUID
  • customer.key - String
  • customer.email - String
  • customer.customerNumber - String
  • customer.customerGroup.id - UUID
  • customer.customerGroup.key - String
  • customer.firstName - String
  • customer.lastName - String
  • customer.middleName - String
  • customer.title - String
  • customer.isEmailVerified - Boolean
  • customer.externalId - String
  • customer.createdAt - String - DateTime
  • customer.lastModifiedAt - String - DateTime

ShippingInfo field identifiers

The following identifiers reference fields on a Cart's ShippingInfo.

  • shippingInfo.shippingMethod.id - UUID
  • shippingInfo.shippingMethod.key - String
  • shippingInfo.shippingMethodName - String
  • shippingInfo.price - String - Money
  • shippingInfo.price.centAmount - Number
  • shippingInfo.price.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • shippingInfo.shippingRate.price - String - Money
  • shippingInfo.shippingRate.price.centAmount - Number
  • shippingInfo.shippingRate.price.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • shippingInfo.shippingRate.freeAbove - String - Money
  • shippingInfo.shippingRate.freeAbove.centAmount - Number
  • shippingInfo.shippingRate.freeAbove.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • shippingInfo.taxCategory.id - UUID
  • shippingInfo.taxCategory.key - String
  • shippingInfo.taxRate - TaxRate

Address field identifiers

The following identifiers reference fields on a Cart's shippingAddress or billingAddress Address fields.

Depending on the address you want to construct a predicate with, replace <address-field> with shippingAddress or billingAddress.

  • <address-field>.id - UUID
  • <address-field>.key - String
  • <address-field>.title - String
  • <address-field>.salutation - String
  • <address-field>.firstName - String
  • <address-field>.lastName - String
  • <address-field>.streetName - String
  • <address-field>.streetNumber - String
  • <address-field>.additionalStreetInfo - String
  • <address-field>.postalCode - String
  • <address-field>.city - String
  • <address-field>.region - String
  • <address-field>.state - String
  • <address-field>.country - String
    A two-digit country code as per ISO 3166-1 alpha-2.
  • <address-field>.company - String
  • <address-field>.department - String
  • <address-field>.building - String
  • <address-field>.apartment - String
  • <address-field>.pOBox - String
  • <address-field>.phone - String
  • <address-field>.mobile - String
  • <address-field>.email - String
  • <address-field>.additionalAddressInfo - String

TaxRate field identifiers

The following identifiers reference fields on a Cart's TaxRate field.

  • taxRate.id - UUID
  • taxRate.name - String
  • taxRate.amount - Number
  • taxRate.includedInPrice - Boolean
  • taxRate.country - String
    A two-digit country code as per ISO 3166-1 alpha-2.
  • taxRate.state - String

LineItem field identifiers

The following identifiers reference fields on a Cart's LineItems.

You can only use LineItem predicate field identifiers for the following:

You cannot use CustomLineItem predicates by themselves in a CartDiscount.

  • product.id - UUID
  • product.key - String
  • productType.id - UUID
  • productType.key - String
  • variant.id - Number
  • variant.key - String
  • sku - String
  • categories.id - Array of UUID
  • categories.key - Array of Strings
  • categoriesWithAncestors.id - Array of UUID
    Identifies categories of a product and all the ancestors of those categories. It is used to match all categories that are in a subtree of a specific category.
  • categoriesWithAncestors.key - Array of Strings
    Identifies categories of a product and all the ancestors of those categories. It is used to match all categories that are in a subtree of a specific category by key.
  • attributes.<name>
    Matches a product attribute by its name. For more information, see Product Attribute Field Identifiers.
  • custom.<name> - CustomField
    Matches a custom field on the line item by its name. For more information, see CustomField Field Identifiers
  • custom.type.id - id of a Type
  • custom.type.key - key of a Type
  • taxRate - TaxRate
  • supplyChannel.id - UUID
  • supplyChannel.key - String
  • quantity - Number
  • price - TypedMoney
    The product price without any cart discounts applied.
  • price.centAmount - Number
  • price.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • price.discount.id - UUID
  • price.country - String
    A two-digit country code as per ISO 3166-1 alpha-2.
  • price.customerGroup.id - UUID
  • price.customerGroup.key - String
  • price.channel.id - UUID
  • price.channel.key - String

LineItem predicate examples



// matches all line items
true


// matches line item with SKU "SKU-123" only if the price is a net price
sku = "SKU-123" and taxRate.includedInPrice = false


// matches a line item by product type, a specific product and at least 3 'rating' attributes
productType.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7" and attributes.rating > 3 and (product.id = "abcd9a23-14e3-40d0-aee2-3e612fcbefgh" or product.id = "ba3e4ee7-30fa-400b-8155-46ebf423d793")


// matches a line item that has the custom field "gender" to be "alien"
custom.gender = "alien"


//matches a line item that is not in a given category
categories.id != ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7")

CustomLineItem field identifiers

The following identifiers reference fields on a Cart's CustomLineItems.

You can only use CustomLineItem predicate field identifiers for the following:

You cannot use CustomLineItem predicates by themselves in a CartDiscount.

  • money - String - Money
  • money.centAmount - Number
  • money.currencyCode - String
    A three-digit currency code as per ISO 4217.
  • slug - String
  • quantity - Number
  • taxCategory.id - UUID
  • taxCategory.key - String
  • taxRate - TaxRate
  • custom.<name> - CustomField
    Matches a custom field on the custom line item by its name given a certain predicate.
  • custom.type.id - id of a Type
  • custom.type.key - key of a Type

CustomLineItem predicate examples



// matches all custom line items
true


// matches custom line items with price of individual items bigger than 10.50 EUR only if the price is a net price
money > "10.50 EUR" and taxRate.includedInPrice = false


// matches a custom line item by slug
slug = "adidas-superstar-2"


// matches a custom line item that has the custom field "gender" to be "alien"
custom.gender = "alien"

CustomField field identifiers

The following identifiers reference custom fields on a Cart, or a line item in a cart.

You can use CustomField field identifiers for the following:

  • A Cart's cartPredicate field, to identify custom fields on a Cart.
  • A CartDiscount with a lineItem CartDiscountTarget, to identify custom fields on a LineItem.
  • A CartDiscount with a customLineItem CartDiscountTarget, to identify custom fields on a CustomLineItem.
  • custom.<name> - CustomField
    Matches a custom field by its name.
    If a field name contains a dash (-) or starts with a digit, escape it using backticks (`): custom.\`1stYear\`

Supported custom field types

The following field types are supported as individual values or as Sets:

  • Boolean
  • String
  • Number
  • DateTime
  • Date
  • Time
  • Enum
  • LocalizedEnum
  • Reference

Custom Fields using the Money type are also supported, but Sets with the Money type are not supported.

CustomField predicate examples

Predicates on a reference match on the ID.
Examples:

//identifies a custom field by ID (where the field is a Reference type)
custom.<name> = "<id>"


//checks if a custom field is contained in a collection, where the field is a reference type
custom.<name> contains any ("<id1>", "<id2>")


//checks if a custom field has a value equal to 18.00 EUR, if the field is a Money type
custom.<name> = "18.00 EUR"


//checks if
custom.<name>.centAmount = 18


//checks if
custom.<name>.currencyCode = "EUR"

Cart Predicate functions

In addition to accessing specific field information, you can use the following predicate functions when constructing Cart Predicates.

All functions accept a LineItemPredicate or CustomLineItemPredicate as an argument, which allows you to limit function to a subset of matching (custom) line items. You can also provide a simple predicate, like true, as an argument if you want to sum or count all line items.

  • lineItemCount(predicate: LineItemPredicate) – Number
    Counts matching line items.
  • customLineItemCount(predicate: CustomLineItemPredicate) – Number
    Counts matching custom line items.
  • lineItemTotal(predicate: LineItemPredicate) – Money
    Sums the total of matching line items.
  • customLineItemTotal(predicate: CustomLineItemPredicate) – Money
    Sums the quantity * money of matching custom line items.
  • lineItemNetTotal(predicate: LineItemPredicate) – Money
    Sums the total of matching line items only if the price is the a net price (based on the taxRate).
  • customLineItemNetTotal(predicate: CustomLineItemPredicate) – Money
    Sums the quantity * money of matching custom line items only if the price is the a net price (based on the taxRate).
  • lineItemGrossTotal(predicate: LineItemPredicate) – Money
    Sums the total of matching line items only if the price is the a gross price (based on the taxRate).
  • customLineItemGrossTotal(predicate: CustomLineItemPredicate) – Money
    Sums the quantity * money of matching custom line items only if the price is a gross price (based on the taxRate).
  • lineItemExists(predicate: LineItemPredicate) – Boolean
    Returns true if at least one line item matches the predicate, otherwise false.
  • forAllLineItems(predicate: LineItemPredicate) – Boolean
    Returns true if all line items matching the predicate, otherwise false.

The total of a line item depends on the line item price mode and the discounts that may apply.

Cart Predicate examples



// matches a cart with total line item cost bigger or equal to 10 USD (which excludes other costs, like shipping)
lineItemTotal(true) >  "10.00 USD"


// matches a cart only when it has exactly 2 like items that have product with size "xxl" or "xl"
lineItemCount(attributes.size in ("xxl", "xl")) = 2


// matches a cart by customer information
customer.email = "john@example.com" and customer.customerGroup.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"


// matches a cart with a minimum total price and at least one lineItem that satisfies a price, a productType, a size attribute or a specific product
totalPrice > "800.00 EUR" and lineItemCount(price > "10.50 EUR" and productType.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7" and attributes.size in ("xl", "xxl") or product.id = "abcd9a23-14e3-40d0-aee2-3e612fcbefgh") > 0


// matches a cart with custom.bookingStart = 2016-11-24 and custom.bookingEnd = 2016-12-04
custom.bookingStart = "2016-11-24" and custom.bookingEnd = "2016-12-04"


// matches a cart for a family (at least 2 adults and at least one youth)
lineItemCount(custom.age = "adult") >=2 and lineItemCount(custom.age = "youth") >=1