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.

The number of active cart discounts that do not require a discount code (isActive=true and requiresDiscountCode=false) is limited to 100.

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 relative to its price.

Please note that, with previous discounts already applied, the target may already have a discounted price. The discount is then calculated based on the already discounted price.

Absolute

Discounts the target by an absolute amount (not allowed for MultiBuyLineItems Target).

Gift Line Item

Adds a free line item as a gift to the cart. The line item will have the LineItemMode GiftLineItem and a quantity of 1. 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.

Note: Cannot be combined with MultiBuyLineItems Target.

CartDiscountTarget

Defines what part of the cart will be discounted.
Currently discounts can be applied on LineItems, CustomLineItems, and ShippingInfo.
Additionally, there is a MultiBuyLineItems Target which discounts certain quantities of line items.

LineItems Target

CustomLineItems Target

ShippingCost Target

MultiBuyLineItems Target beta

The multi-buy discount represents a “Buy 6 items, get 2 of them discounted” type of discount. A multi-buy discount is not applied on each line item as a whole (like with the LineItems Target) but on the individual items that are contained in all matching line items and subsumed under their quantity fields. A multi-buy discount can occur multiple times in a cart.

A single application of a multi-buy discount is described by the following two numbers:

In the above example the triggerQuantity is 6, and the discountedQuantity is 2.

The triggerQuantity must be greater than 1.
The discountedQuantity must be greater than 0 and less than or equal to the triggerQuantity.

A multi-buy discount can have more than one occurrence in a cart. Yet, any item will only be considered once per multi-buy discount. Sticking to the example discount above:

Given a cart with 6 items, the discount can be applied only once. As a result, 2 items will be discounted and 4 items will be marked as participating in this discount.

Given a cart with 8 items, the discount can still be applied only once. As a result, 2 items will be discounted and 4 items will be marked as participating while the Remaining 2 items will be disregarded by this discount.

Given a cart with 12 items, the discount can be applied twice. As a result, 2*2 items will be discounted and 2*4 items will be marked as participating in this discount.

A participation is represented by a DiscountedLineItemPortion with discountedAmount.centAmount = 0.

You can limit the number of occurrences (“applications”) of a multi-buy discount per cart by defining the maxOccurrence parameter. A LineItemPredicate is applied to select the items relevant for the discount. The discount value to be applied is defined in the discount’s CartDiscountValue. Currently only relative values are allowed.

To recap, the matching items of a discount application will be sliced into up to maxOccurence groups of size triggerQuantity. Remaining items (e.g., the 9th of a “buy 8, get 2 for free” discount) do not participate in the discount. Of any such group only discountedQuantity items will actually be discounted (e.g., the 2 of a “buy 8, get 2 for free” discount); the others are only participating, meaning they are part of this occurence and, consequently, cannot participate in another group and the price remains unchanged. To determine which items of a group will actually be discounted, a SelectionMode needs to be set.

SelectionMode

In order to decide which of the matching items will actually be discounted, SelectionMode offers two options:

If the discount occurs multiple times, it is guaranteed that, out of all matching items, the overall cheapest or most expensive ones will be discounted, depending on this setting.

Note that the discount always refers to the current price including already applied discounts.

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: