Cart Predicates

Predicates allow a sophisticated application of cart discounts, shipping methods etc.

The cart predicates offer a flexible way to define the conditions under which e.g. a discount or a shipping method can be applied to a cart. Cart predicates are structured as generic predicates by using specific fields and functions listed below. Some of these relate to the cart as a whole, like totalPrice or lineItemCount, while others relate to individual items of the cart, like product.id on a lineItem.

Please note that the syntax here differs from the one used in Query Predicates.

CartPredicate

These first fields and function apply to the cart as a whole.

The following field identifiers can be used in a CartPredicate. They reference fields in 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
  • 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
  • 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
  • custom.<field> - CustomField
    Matches a custom field on the cart by its name given a certain predicate.
  • custom.type.id - id of a Type
  • custom.type.key - key of a Type

The following identifiers referencing fields in an Address can be used in a CartPredicate.

  • <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

The following identifiers referencing fields in a TaxRate can be used in a CartPredicate.

  • <tax-rate-field>.id - UUID
  • <tax-rate-field>.name - String
  • <tax-rate-field>.amount - Number
  • <tax-rate-field>.includedInPrice - Boolean
  • <tax-rate-field>.country - String
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .
  • <tax-rate-field>.state - String

CartPredicate Functions

The following functions can be used in a cart predicate. All functions accept a LineItemPredicate or CustomLineItemPredicate as an argument, which allows you to limit function to the subset of matching (custom) 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 the 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.

Please note that you can provide a simple predicate like true if you want to sum or count all (custom) line items.

CartPredicate 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

LineItemPredicate

The LineItemPredicate offers a flexible way to specify the line items that should be used in the predicate.

LineItemPredicate Fields

The following field identifiers can be used in a predicate. They reference fields in a LineItem.

  • product.id - UUID
  • product.key - String
  • productType.id - UUID
  • variant.id - 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.<attr-name>
    Matches a product attribute by its name.
    The following attribute types are supported: boolean, text, number, datetime, date, time, enum, lenum and reference. The set of these types is also supported. Predicates on reference matches on the ID. Example: attribues.<field> = "<id>". Furthermore the attribute type money is supported but not inside a set. The predicate can then match on the complete value (attributes.<field> = "18.00 EUR"), only on the amount (attributes.<field>.centAmount = 18) or only on the currency (attributes.<field>.currencyCode = "EUR"). If an attribute name contains a dash (-) or starts with a digit, it needs to be escaped with backticks (`), e.g., attributes.`average-count`.
  • custom.<field> - CustomField
    Matches a custom field on the line item by its name given a certain predicate.
  • 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

LineItemPredicate 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")

CustomLineItemPredicate

The CustomLineItemPredicate offers a flexible way to define which CustomLineItem should be used in the predicate.

CustomLineItemPredicate Fields

The following field identifiers can be used in a predicate. They reference fields in a CustomLineItem.

  • 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.<field> - 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

CustomLineItemPredicate 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"

Predicate on custom fields

All predicates allow using custom fields and make use of a uniform syntax regarding those fields. They have the following form:

This predicate matches a custom field by its name.

The following field types are supported: Boolean, String, Number, DateTime, Date, Time, Enum, LocalizedEnum and Reference, all of which are also supported as sets.

Predicates on a reference match on the ID.
Examples:

  • custom.<field> = "<id>" where <field> is of type Reference.
  • custom.<field> contains any ("<id1>", "<id2>") where <field> is of type Reference.

Furthermore, the field type Money is supported, but not for sets of it.
Predicates on Money can match:

  • the complete value. Example: custom.<field> = "18.00 EUR"
  • only the amount. Example: custom.<field>.centAmount = 18
  • only the currency. Example: custom.<field>.currencyCode = "EUR"

If a field name contains a dash (-) or starts with a digit, it needs to be escaped with backticks (`), e.g., custom.`1stYear` or custom.`-myname`.

Predicate Operators

The operators combine field identifiers with concrete values to construct predicates.
The operators use the infix notation with the general notation field-identifier operator value.

Example: sku = "AB-123" where

  • the field identifier is sku,
  • the operator is = and
  • the value is "AB-123".

Collection values are separated with , and enclosed in parentheses.

Example: categories.id = ("f6a19a23-14e3-40d0-aee2-3e612fcb1bc7", "abcd9a23-14e3-40d0-aee2-3e612fcbefgh")

Following table lists all operators that can be used on fields or on other predicates to build higher order predicates.

purpose operator usable on
compare field values =, !=, >, >=, <, <= simple fields
check if field is present on resource is defined any field
check if field is missing on resource is not defined any field
check if field is present but has no value is empty collection fields
check if field is present and has a value is not empty collection fields
check if field contains specified value contains collection fields with simple value
check if field contains at least one of the specified values contains any collection fields with collection value
check if field contains all of the specified values contains all collection fields with collection value
logical disjunction or predicates
logical conjunction and predicates
logical negation not predicates

Parentheses are used to nest logical operators and combine predicate parts into more complex predicates.