Discount Predicate Field Identifiers

Some resources in the commercetools API have a predicate or cartPredicate field. In particular, Product Discounts, Cart Discounts, and Shippping 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.

Note: 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
  • variantId - Number
  • 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

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.
  • categoriesWithAncestors.id - Array of UUID
    Identifies all Products that have a category as well as products in child categories.

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

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 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.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.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.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 - 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
  • variantId - Number
  • 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
  • quantity - Number
  • price - BaseMoney
    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

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 .
  • money.fractionDigits - Number
  • slug - String
  • quantity - Number
  • taxCategory.id - UUID
  • 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 indivudual 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 quantity * price of matching line items.
  • customLineItemTotal(predicate: CustomLineItemPredicate) – Money
    Sums the quantity * money of matching custom line items.
  • lineItemNetTotal(predicate: LineItemPredicate) – Money
    Sums the quantity * price 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 quantity * price 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.

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 = 24.11.2016 and custom.bookingEnd = 04.12.2016
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