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
- UUIDproduct.key
- StringproductType.id
- UUIDproductType.key
- Stringvariant.id
- Numbervariant.key
- Stringsku
- Stringattributes.<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
- Moneyamount
- Number - The amount in the specifiedcurrency
.centAmount
- Number - The amount in cents (the subunit) of the specifiedcurrency
.currency
- String - Currency codecountry
- String - Country codecustomerGroup.id
- UUIDcustomerGroup.key
- Stringchannel.id
- UUIDchannel.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 productproduct.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 categorycategories.id = "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"//match a product that is in the given categorycategories.id contains "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"//match a product that is in all of the the given categoriescategories.id contains all ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7", "abcd9a23-14e3-40d0-aee2-3e612fcbefgh")//match a product that is in one of the the given categoriescategories.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 otherscategories.id = ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7", "abcd9a23-14e3-40d0-aee2-3e612fcbefgh")//match a product that is not in a given categorycategories.id != ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7")//match the prices above 12€ for any countries except France that do not have a customer group setcentAmount > 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 100sku = "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 categorycategoriesWithAncestors.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 Discounts can have two predicates: a
cartPredicate
and a CartDiscountTarget predicate. You can only use LineItem Field Identifiers and CustomLineItem Field Identifiers in CartDiscountTarget predicates.
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
- MoneytotalPrice.centAmount
- NumbertotalPrice.currencyCode
- String
A three-digit currency code as per ISO 4217.taxedPrice.net
- String - MoneytaxedPrice.net.centAmount
- NumbertaxedPrice.net.currencyCode
- String
A three-digit currency code as per ISO 4217.taxedPrice.gross
- String - MoneytaxedPrice.gross.centAmount
- NumbertaxedPrice.gross.currencyCode
- String
A three-digit currency code as per ISO 4217.createdAt
- String - DateTimelastModifiedAt
- String - DateTimeshippingAddress
- AddressbillingAddress
- Addresscustom.<name>
- CustomField
Matches a custom field by its name. For more information, see CustomField Predicate Field Identifiers.custom.type.id
-id
of a Typecustom.type.key
-key
of a Type
Customer field identifiers
The following identifiers reference fields on a Cart's Customer.
customer.id
- UUIDcustomer.key
- Stringcustomer.email
- Stringcustomer.customerNumber
- Stringcustomer.customerGroup.id
- UUIDcustomer.customerGroup.key
- Stringcustomer.firstName
- Stringcustomer.lastName
- Stringcustomer.middleName
- Stringcustomer.title
- Stringcustomer.isEmailVerified
- Booleancustomer.externalId
- Stringcustomer.createdAt
- String - DateTimecustomer.lastModifiedAt
- String - DateTime
ShippingInfo field identifiers
The following identifiers reference fields on a Cart's ShippingInfo.
shippingInfo.shippingMethod.id
- UUIDshippingInfo.shippingMethod.key
- StringshippingInfo.shippingMethodName
- StringshippingInfo.price
- String - MoneyshippingInfo.price.centAmount
- NumbershippingInfo.price.currencyCode
- String
A three-digit currency code as per ISO 4217.shippingInfo.shippingRate.price
- String - MoneyshippingInfo.shippingRate.price.centAmount
- NumbershippingInfo.shippingRate.price.currencyCode
- String
A three-digit currency code as per ISO 4217.shippingInfo.shippingRate.freeAbove
- String - MoneyshippingInfo.shippingRate.freeAbove.centAmount
- NumbershippingInfo.shippingRate.freeAbove.currencyCode
- String
A three-digit currency code as per ISO 4217.shippingInfo.taxCategory.id
- UUIDshippingInfo.taxCategory.key
- StringshippingInfo.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
- UUIDtaxRate.name
- StringtaxRate.amount
- NumbertaxRate.includedInPrice
- BooleantaxRate.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:
- Cart Discounts with a
lineItem
CartDiscountTarget - As a part of a Cart Predicate Function.
You cannot use CustomLineItem predicates by themselves in a CartDiscount.
product.id
- UUIDproduct.key
- StringproductType.id
- UUIDproductType.key
- Stringvariant.id
- Numbervariant.key
- Stringsku
- Stringcategories.id
- Array of UUIDcategories.key
- Array of StringscategoriesWithAncestors.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 Identifierscustom.type.id
-id
of a Typecustom.type.key
-key
of a TypetaxRate
- TaxRatesupplyChannel.id
- UUIDsupplyChannel.key
- Stringquantity
- Numberprice
- TypedMoney
The product price without any cart discounts applied.price.centAmount
- Numberprice.currencyCode
- String
A three-digit currency code as per ISO 4217.price.discount.id
- UUIDprice.country
- String
A two-digit country code as per ISO 3166-1 alpha-2.price.customerGroup.id
- UUIDprice.customerGroup.key
- Stringprice.channel.id
- UUIDprice.channel.key
- String
LineItem predicate examples
// matches all line itemstrue// matches line item with SKU "SKU-123" only if the price is a net pricesku = "SKU-123" and taxRate.includedInPrice = false// matches a line item by product type, a specific product and at least 3 'rating' attributesproductType.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 categorycategories.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:
- Cart Discounts with a
customLineItem
CartDiscountTarget - As a part of a Cart Predicate Function.
You cannot use CustomLineItem predicates by themselves in a CartDiscount.
money
- String - Moneymoney.centAmount
- Numbermoney.currencyCode
- String
A three-digit currency code as per ISO 4217.slug
- Stringquantity
- NumbertaxCategory.id
- UUIDtaxCategory.key
- StringtaxRate
- TaxRatecustom.<name>
- CustomField
Matches a custom field on the custom line item by its name given a certain predicate.custom.type.id
-id
of a Typecustom.type.key
-key
of a Type
CustomLineItem predicate examples
// matches all custom line itemstrue// matches custom line items with price of individual items bigger than 10.50 EUR only if the price is a net pricemoney > "10.50 EUR" and taxRate.includedInPrice = false// matches a custom line item by slugslug = "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 typecustom.<name> contains any ("<id1>", "<id2>")//checks if a custom field has a value equal to 18.00 EUR, if the field is a Money typecustom.<name> = "18.00 EUR"//checks ifcustom.<name>.centAmount = 18//checks ifcustom.<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 thequantity * 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 thetaxRate
).customLineItemNetTotal
(predicate
: CustomLineItemPredicate) – Money
Sums thequantity * money
of matching custom line items only if the price is the a net price (based on thetaxRate
).lineItemGrossTotal
(predicate
: LineItemPredicate) – Money
Sums the total of matching line items only if the price is the a gross price (based on thetaxRate
).customLineItemGrossTotal
(predicate
: CustomLineItemPredicate) – Money
Sums thequantity * money
of matching custom line items only if the price is a gross price (based on thetaxRate
).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 informationcustomer.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 producttotalPrice > "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-04custom.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