Cart Discounts

Cart discounts are used to change the prices of different elements within a cart.

Cart discounts are recalculated every time LineItems or CustomLineItems are added or removed from the Cart or an order is created from the cart.

Representations

CartDiscount

CartDiscountDraft

CartDiscountValue

Defines the effect the discount will have. For a target, relative or absolute discount values can be specified. If no target is specified, a gift line item can be added to the cart.

Relative

Discounts the target relatively to it’s base price.

Absolute

Discounts the target by an absolute amount.

Gift Line Item

Adds a free line item as a gift to the cart. The line item will have the LineItemMode GiftLineItem. Like all other line items, it has the price field set (it is therefore necessary that the variant has a price defined that can be selected for each cart the discount should be applied to). The totalPrice has a centAmount of 0. The discountedPricePerQuantity discounts the full price and links back to this cart discount.

If at creation time the discount can not be applied to any cart (e.g. because the product, the variant, or a channel does not exist), the creation fails.

The discount will not be applied to a cart if it either has become invalid since the creation (e.g. because the product, the variant, or a channel have been deleted) or because no price can be selected for the particular cart.

CartDiscountTarget

Defines what part of the cart will be discounted.
Currently discounts can be applied on LineItems, CustomLineItems and ShippingInfo.

LineItems Target

CustomLineItems Target

ShippingCost Target

CartDiscountPredicate

The CartDiscountPredicate offers a flexible way to define the conditions under which the discount can be applied to a cart. CartDiscountPredicates are structured as generic predicates by using specific fields listed below.

The following field identifiers can be used in a CartDiscountPredicate. They reference fields in a Cart.

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

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

CartDiscountPredicate 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.

Please note, that you can provide an empty predicate like 1 = 1 or true = true if you want to sum or count all (custom) line items.

CartDiscountPredicate Examples

// matches a cart with total line item cost bigger or equal to 10 USD (which excludes other costs, like shipping)
lineItemTotal(1 = 1) >  "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 discounted. LineItemPredicates are structured as generic Predicates by using specific fields listed below.

LineItemPredicate Fields

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

LineItemPredicate Examples

// matches all line items
1 = 1

// 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 discounted or filtered. Custom line item predicates are structured as generic Predicates by using the specific fields listed below.

CustomLineItemPredicate Fields

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

CustomLineItemPredicate Examples

// matches all custom line items
1 = 1

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

A predicate on a custom field has 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. Those types are also supported for SetType of them.

Predicates on reference matches on the ID.
Examples:

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

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

Predicate Operators

See ProductDiscount operators.

Get CartDiscount by ID

Endpoint: /{projectKey}/cart-discounts/{id}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: CartDiscount

Query CartDiscounts

Endpoint: /{projectKey}/cart-discounts
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of CartDiscount
Query Parameters:

Create a CartDiscount

Endpoint: /{projectKey}/cart-discounts
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Request Representation: CartDiscountDraft
Response Representation: CartDiscount

Update CartDiscount

Endpoint: /{projectKey}/cart-discounts/{id}
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: CartDiscount
Fields:

Update Actions
Please find below the individual update actions provided on this endpoint.


Change Value

Change Cart Predicate

Change Target

Change IsActive

Change Name

Set Description

Change Sort Order

Change Requires DiscountCode

Set Valid From

Set Valid Until

Delete CartDiscount

Endpoint: /{projectKey}/cart-discounts/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey}
Query Parameters: