Cart Discounts

Representations

CartDiscount

• id - String
  The unique ID of the cart discount.
• version - Number
  The current version of the cart discount.
• key - String - Optional
  User-specific unique identifier for a cart discount. Must be unique across a project.
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• 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
• key - String - Optional
  User-defined unique identifier for the CartDiscount. Keys can only contain alphanumeric characters (a-Z, 0-9), underscores and hyphens (_, -) and be between 2 and 256 characters.
• description - LocalizedString - Optional
• value - CartDiscountValueDraft
• 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 - Optional
  States whether the discount can only be used in a connection with a DiscountCode. Defaults to false.
• stackingMode - StackingMode - Optional
  Specifies whether the application of this discount causes the following discounts to be ignored. Defaults to Stacking.
• custom - CustomFieldsDraft - Optional

CartDiscountValue

Defines the effect the discount will have. For a target, relative or absolute discount values, or a fixed item price value 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 CentPrecisionMoney
  The array contains money values in different currencies. An absolute cart 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$.

Fixed

Sets the DiscountedLineItemPrice of the LineItems Target or CustomLineItems Target to the value specified in the money field, if it is lower than the current line item price for the same currency. If the line item price is already discounted to a price equal or lower the respective price in the money field the fixed price cart discount is not applied.

• type - fixed
• money - Array of CentPrecisionMoney
  The array contains money values in different currencies. A fixed price cart 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 discounted to 10€ and the matching $ price will be discounted to 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 (for example 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 (for example because the product, the variant, or a channel have been deleted) or because no price can be selected for the particular cart.

• type - giftLineItem

• product - Reference to a Product

• variantId - Number

• supplyChannel - Reference to a Channel - Optional
  The channel must have the role InventorySupply.

• distributionChannel - Reference to a Channel - Optional
  The channel must have the role ProductDistribution.

  Note: Cannot be combined with MultiBuyLineItems Target.

CartDiscountValueDraft

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

Same as CartDiscountValueRelative.

Absolute

Same as CartDiscountValueAbsolute.

Fixed

Same as CartDiscountValueFixed.

Gift Line Item

The difference from CartDiscountValueGiftLineItem is that, being a draft object, the fields product, supplyChannel, and distributionChannel take ResourceIdentifiers instead of References for their values. (cf. the explanation under ResourceIdentifier by Key.)

• type - giftLineItem
• product - ResourceIdentifier of a Product
• variantId - Number
• supplyChannel - ResourceIdentifier of a Channel - Optional
  The channel must have the role InventorySupply.
• distributionChannel - ResourceIdentifier of a Channel - Optional
  The channel must have the role ProductDistribution.

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 (for example, the nineth 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 (for example, the second of a "buy 8, get 2 for free" discount); the others are only participating, meaning they are part of this occurence and thus, 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 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 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

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

• Cheapest - select the cheapest items
• MostExpensive - select the most expensive items

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 if it got successfully applied.

Note: The stacking mode does not control free shipping as defined via freeAbove on a ShippingRate. To avoid unwanted scenarios, we highly recommend not using cart discounts on shipping target and freeAbove together.

Get CartDiscount

Get CartDiscount by ID

Endpoint: /{projectKey}/cart-discounts/{id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey} or view_cart_discounts:{projectKey}
Response Representation: CartDiscount

Get CartDiscount by Key

Endpoint: /{projectKey}/cart-discounts/key={key}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey} or view_cart_discounts:{projectKey}
Response Representation: CartDiscount

Query CartDiscounts

Endpoint: /{projectKey}/cart-discounts
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey} or view_cart_discounts:{projectKey}
Response Representation: PagedQueryResult with results containing an array of CartDiscount
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Create a CartDiscount

Endpoint: /{projectKey}/cart-discounts
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_cart_discounts:{projectKey}
Request Representation: CartDiscountDraft
Response Representation: CartDiscount

Update CartDiscount

Update CartDiscount by ID

Endpoint: /{projectKey}/cart-discounts/{id}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_cart_discounts:{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 CartDiscount by Key

Endpoint: /{projectKey}/cart-discounts/key={key}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_cart_discounts:{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

Set Key

Sets a CartDiscount's key field. The key must be unique across the project.

• action - String - "setKey"
• key - String - Optional If key is absent or null, the existing key, if any, will be removed.

Change Value

• action - String - "changeValue"
• value - CartDiscountValueDraft

Change Cart Predicate

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

Change Target

• action - String - "changeTarget"
• target - CartDiscountTarget

Change IsActive

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

Change Name

• action - String - "changeName"
• name - LocalizedString

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
  If absent, the field with the value is removed in case a value was set before.

Set Valid Until

• action - String - "setValidUntil"
• validUntil - DateTime - Optional
  If absent, the field with the value is removed in case a value was set before.

Set Valid From and Until

• action - String - "setValidFromAndUntil"
• validFrom - DateTime - Optional
  If absent, the field with the value is removed in case a value was set before.
• validUntil - DateTime - Optional
  If absent, the field with the value is removed in case a value was set before.

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. If present, this action overwrites any existing custom type and fields.

• action - String - "setCustomType"
• type - ResourceIdentifier of a Type - Optional
  If absent, the custom type and any existing CustomFields are removed.
• fields - * - Optional
  A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

Set Custom Field

This action sets, overwrites, or removes any existing custom field for an existing cart discount.

Delete CartDiscount

Delete CartDiscount by ID

Endpoint: /{projectKey}/cart-discounts/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_cart_discounts:{projectKey}
Query Parameters:

• version - Number - Required

Delete CartDiscount by Key

Endpoint: /{projectKey}/cart-discounts/key={key} Method: DELETE OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_cart_discounts:{projectKey} Query Parameters:

• version - Number - Required