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 CartDiscounts that do not require a discount code (isActive=true and requiresDiscountCode=false) is limited to 100.

Representations

CartDiscount

  • id - String
    The unique ID of the product discount
  • version - Number
    The current version of the product discount.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • name - LocalizedString
  • description - LocalizedString - Optional
  • value - CartDiscountValue
  • cartPredicate - String
    A valid Cart predicate.
  • target - CartDiscountTarget - Optional
    Empty when the value has type giftLineItem, otherwise a CartDiscountTarget is set.
  • sortOrder - String
    The string must contain a number between 0 and 1. All matching cart discounts are applied to a cart in the order defined by this field. A discount with greater sort order is prioritized higher than a discount with lower sort order. The sort order is unambiguous among all cart discounts.
  • isActive - Boolean
    Only active discount can be applied to the cart.
  • validFrom - DateTime - Optional
  • validUntil - DateTime - Optional
  • requiresDiscountCode - Boolean
    States whether the discount can only be used in a connection with a DiscountCode.
  • references - Array of Reference
    The platform will generate this array from the predicate. It contains the references of all the resources that are addressed in the predicate.
  • stackingMode - StackingMode
    Specifies whether the application of this discount causes the following discounts to be ignored. Defaults to Stacking.
  • custom - CustomFields - Optional

CartDiscountDraft

  • name - LocalizedString
  • description - LocalizedString - Optional
  • value - CartDiscountValue
  • cartPredicate - String
    A valid Cart predicate.
  • target - CartDiscountTarget - Optional
    Must not be set when the value has type giftLineItem, otherwise a CartDiscountTarget must be set.
  • sortOrder - String
    The string must contain a number between 0 and 1. A discount with greater sort order is prioritized higher than a discount with lower sort order. The sort order must be unambiguous among all cart discounts.
  • isActive - Boolean - Optional
    Only active discount can be applied to the cart. Defaults to true.
  • validFrom - DateTime - Optional
  • validUntil - DateTime - Optional
  • requiresDiscountCode - Boolean
    States whether the discount can only be used in a connection with a DiscountCode.
  • stackingMode - StackingMode - Optional
    Specifies whether the application of this discount causes the following discounts to be ignored. Defaults to Stacking.
  • custom - CustomFields - Optional

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.

  • type - relative
  • permyriad - Number
    Per ten thousand. The fraction the price is reduced. 1000 will result in a 10% price reduction.

Absolute

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

  • type - absolute
  • money - Array of Money
    The array contains money values in different currencies. An absolute product discount will only match a price if this array contains a value with the same currency. If it contains 10€ and 15$, the matching € price will be decreased by 10€ and the matching $ price will be decreased by 15$.

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

  • type - lineItems
  • predicate - String
    A valid line item target predicate. The discount will be applied to line items that are matched by the predicate.

CustomLineItems Target

  • type - customLineItems
  • predicate - String
    A valid custom line item target predicate. The discount will be applied to custom line items that are matched by the predicate.

ShippingCost Target

  • type - shipping

MultiBuyLineItems Target beta

The multi-buy discount represents a “Buy 4 items, get 2 of them at a discounted rate” 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:

  • triggerQuantity - How many items need to match per occurrence?
  • discountedQuantity - How many of these items will be discounted per occurrence?

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.

  • type - multiBuyLineItems
  • predicate - String
    A valid line item target predicate. The discount will be applied to line items that are matched by the predicate.
  • triggerQuantity - Number
    Quantity of line items that need to be present in order to trigger an application of this discount.
  • discountedQuantity - Number
    Quantity of line items that are discounted per application of this discount.
  • maxOccurrence - Number - Optional
    Maximum number of applications of this discount.
  • selectionMode - SelectionMode

MultiBuyCustomLineItems Target beta

The multi-buy discount represents a “Buy 4 items, get 2 of them at a discounted rate” type of discount. This discount target is very similar to MultiBuyLineItems but applied on custom line items instead of line items.

  • type - multiBuyCustomLineItems
  • predicate - String
    A valid custom line item target predicate. The discount will be applied to custom line items that are matched by the predicate.
  • triggerQuantity - Number
    Quantity of custom line items that need to be present in order to trigger an application of this discount.
  • discountedQuantity - Number
    Quantity of custom line items that are discounted per application of this discount.
  • maxOccurrence - Number - Optional
    Maximum number of applications of this discount.
  • selectionMode - SelectionMode
SelectionMode

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

  • Cheapest - select the cheapest item(s)
  • MostExpensive - select the most expensive item(s)

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.

StackingMode

Describes how this discount interacts with other discounts.

Values of the StackingMode enumeration:

  • Stacking
    Default. Continue applying other matching discounts after applying this one.
  • StopAfterThisDiscount
    Don’t apply any more matching discounts after this one.

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:

  • version - Number - Required
    The expected version of the product discount on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the CartDiscount.

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


Change Value

Change Cart Predicate

  • action - String - "changeCartPredicate"
  • cartPredicate - String
    A valid Cart predicate.

Change Target

Change IsActive

  • action - String - "changeIsActive"
  • isActive - Boolean

Change Name

Set Description

  • action - String - "setDescription"
  • description - LocalizedString - Optional
    If the description parameter is not included, the field will be emptied.

Change Sort Order

  • action - String - "changeSortOrder"
  • sortOrder - String
    The string must contain a number between 0 and 1. A discount with greater sortOrder is prioritized higher than a discount with lower sortOrder.

Change Requires DiscountCode

  • action - String - "changeRequiresDiscountCode"
  • requiresDiscountCode - Boolean

Set Valid From

  • action - String - "setValidFrom"
  • validFrom - DateTime - Optional

Set Valid Until

  • action - String - "setValidUntil"
  • validUntil - DateTime - Optional

Change Stacking Mode

  • action - String - "changeStackingMode"
  • stackingMode - StackingMode - Required

Set Custom Type

This action sets or removes the custom type for an existing cart discount.

This action overwrites any existing custom type and fields.

Set Custom Field

Delete CartDiscount

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

  • version - Number - Required