Cart Discounts are used to change the Prices of different elements within a Cart.
isActive=true
and requiresDiscountCode=false
) is limited to 100
. Cart Discounts can be defined globally for the Project or specific to one or more (up to 500
) Stores. Learn more about this limit.Representations
CartDiscount
id ​String​ | Unique identifier of the CartDiscount. |
version ​Int​ | Current version of the CartDiscount. |
key ​String​ | User-defined unique identifier of the CartDiscount. MinLength:Â2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
name ​ | Name of the CartDiscount. |
description ​ | Description of the CartDiscount. |
value ​ | Effect of the CartDiscount on the target . |
cartPredicate ​String​ | Valid Cart Predicate. |
target ​ | Segment of the Cart that is discounted. Empty, if the value is giftLineItem . |
sortOrder ​String​ | Value between 0 and 1 .
All matching CartDiscounts are applied to a Cart in the order defined by this field.
A Discount with a higher sortOrder is prioritized.
The sort order is unambiguous among all CartDiscounts. |
stores ​Array of StoreKeyReference​ | |
isActive ​Boolean​ | Indicates if the CartDiscount is active and can be applied to the Cart. |
validFrom ​DateTime​ | Date and time (UTC) from which the Discount is effective. |
validUntil ​DateTime​ | Date and time (UTC) until which the Discount is effective. |
requiresDiscountCode ​Boolean​ | Indicates if the Discount is used in connection with a DiscountCode. |
references ​Array of Reference​ | References of all resources that are addressed in the predicate. The API generates this array from the predicate. |
stackingMode ​StackingMode​ | Indicates whether the application of the CartDiscount causes other discounts to be ignored. Default:ÂStacking ​ |
custom ​CustomFields​ | Custom Fields of the CartDiscount. |
createdAt ​DateTime​ | Date and time (UTC) the CartDiscount was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the CartDiscount. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the CartDiscount was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the CartDiscount. |
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
CartDiscountDraft
key ​String​ | User-defined unique identifier for the CartDiscount. MinLength:Â2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
name ​ | Name of the CartDiscount. |
description ​ | Description of the CartDiscount. |
value ​ | Effect of the CartDiscount on the target . |
cartPredicate ​String​ | Valid Cart Predicate. |
target ​ | Segment of the Cart that will be discounted. Must not be set if the value is giftLineItem . |
sortOrder ​String​ | Value between 0 and 1 .
A Discount with a higher sortOrder is prioritized.
The sort order must be unambiguous among all CartDiscounts. |
stores ​Array of StoreResourceIdentifier​ |
If the referenced Stores exceed the limit, a MaxStoreReferencesReached error is returned.
If the referenced Stores exceed the limit for Cart Discounts that do not require a Discount Code, a StoreCartDiscountsLimitReached error is returned. MaxItems: 500 ​ |
isActive ​Boolean​ | Only active Discounts can be applied to the Cart.
If the limit for active Cart Discounts is reached, a MaxCartDiscountsReached error is returned. Default: true ​ |
validFrom ​DateTime​ | Date and time (UTC) from which the Discount is effective. |
validUntil ​DateTime​ | Date and time (UTC) until which the Discount is effective. |
requiresDiscountCode ​Boolean​ | States whether the Discount can only be used in a connection with a DiscountCode. |
stackingMode ​StackingMode​ | Specifies whether the application of this discount causes the following discounts to be ignored. Default:ÂStacking ​ |
custom ​ | Custom Fields of the CartDiscount. |
{
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"key": "europe",
"typeId": "store"
}
],
"isActive": true,
"requiresDiscountCode": true,
"stackingMode": "Stacking"
}
CartDiscountPagedQueryResponse
limit ​Int​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset ​Int​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
count ​Int​ | Actual number of results returned. |
total ​Int​ | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false .
When the results are filtered with a Query Predicate, total is subject to a limit. |
results ​Array of CartDiscount​ | CartDiscounts matching the query. |
CartDiscountReference
id ​String​ | Unique identifier of the referenced CartDiscount. |
typeId ​ | cart-discount Type of referenced resource. |
obj ​CartDiscount​ | Contains the representation of the expanded CartDiscount. Only present in responses to requests with Reference Expansion for CartDiscounts. |
CartDiscountResourceIdentifier
id
or key
is required. If both are set, an InvalidJsonInput error is returned.id ​String​ | Unique identifier of the referenced CartDiscount. Required if key is absent. |
key ​String​ | User-defined unique identifier of the referenced CartDiscount. Required if id is absent. |
typeId ​ | cart-discount Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
CartDiscountValue
CartDiscountValueRelative
type ​String​ | "relative" |
permyriad ​Int​ | Fraction (per ten thousand) the price is reduced by. For example, 1000 will result in a 10% price reduction. |
{
"type": "relative",
"permyriad": 1000
}
With previous Discounts already applied, the target may already have a discounted Price. The Discount is then calculated based on the already discounted Price.
CartDiscountValueAbsolute
type ​String​ | "absolute" |
money ​Array of CentPrecisionMoney​ | Cent precision money values in different currencies. |
applicationMode ​ | Determines how the discount is applied on CartDiscountLineItemTarget and CartDiscountCustomLineItemTarget. |
{
"type": "absolute",
"money": {
"centAmount": 2000,
"currencyCode": "EUR",
"type": "centPrecision",
"fractionDigits": 2
},
"applicationMode": "IndividualApplication"
}
CartDiscountValueFixed
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 to or lower than the respective price in the money
field, this Discount is not applied. If the quantity
of the Line Item eligible for the Discount is greater than 1
, the fixed price discount is only applied to the Line Item portion for which the money
value is lesser than their current price.type ​String​ | "fixed" |
money ​Array of TypedMoney​ | Money values in cent precision or high precision of different currencies. |
applicationMode ​ | Indicates how the discount is applied on CartDiscountLineItemTarget or CartDiscountCustomLineItemTarget.
Default: IndividualApplication ​ |
{
"type": "fixed",
"money": {
"centAmount": 2000,
"currencyCode": "EUR",
"type": "centPrecision",
"fractionDigits": 2
}
}
CartDiscountValueGiftLineItem
The Gift Line Item has the following characteristics:
- LineItemMode
GiftLineItem
and aquantity
of1
. - Like all other Line Items, it has the
price
field set (it is, therefore, necessary that the Product Variant has a Price defined that can be selected for each Cart the Discount should be applied to). - The
totalPrice
has acentAmount
of0
. - The
discountedPricePerQuantity
shows adiscountedPrice
with acentAmount
of0
andincludedDiscounts
references the Cart Discount that was evaluated to add the Gift Line Item.
type ​String​ | "giftLineItem" |
product ​ | Reference to a Product. A Gift Line Item can be present on a Cart even if the referenced Product is unpublished. |
variantId ​Int​ | ProductVariant of the Product. |
supplyChannel ​ | Channel must have the ChannelRoleEnum InventorySupply . |
distributionChannel ​ | Channel must have the ChannelRoleEnum ProductDistribution . |
{
"type": "giftLineItem",
"product": {
"id": "{{product-id}}",
"typeId": "product"
},
"variantId": 1,
"distributionChannel": {
"id": "{{channel-id}}",
"typeId": "channel"
}
}
CartDiscountValueDraft
CartDiscountValueRelativeDraft
type ​String​ | "relative" |
permyriad ​Int​ | Fraction (per ten thousand) the price is reduced by. For example, 1000 will result in a 10% price reduction. |
{
"type": "relative",
"permyriad": 1000
}
CartDiscountValueAbsoluteDraft
type ​String​ | "absolute" |
money ​Array of Money​ | Money values in different currencies. An absolute Cart Discount will match a price only if the array contains a value with the same currency. For example, if it contains 10€ and 15$, the matching € price will be decreased by 10€ and the matching $ price will be decreased by 15$. If the array is empty or has multiple values of the same currency, the API returns an InvalidOperation error. |
applicationMode ​ | Determines how the discount applies on CartDiscountLineItemTarget and CartDiscountCustomLineItemTarget.
If not set, the default behavior is ProportionateDistribution . |
{
"type": "absolute",
"money": {
"centAmount": 2000,
"currencyCode": "EUR"
},
"applicationMode": "IndividualApplication"
}
For example, when an absolute Discount of €16 applies to all Line Items in a Cart:
- If discounted proportionately, the discount is calculated (for a Line Item) by dividing the price of the Line Item by the total price of the Cart and multiplying (the rounded) value by the discount amount; in this case, for Line Item A, (14/54)*16 = 4.16.
- If discounted evenly, the discount amount is divided by the number of Line Items—in this case, 16/3—and that value is deducted from each Line Item with rounding.
- If applied individually, the discount amount is deducted on every eligible Line item; negative values are rounded to zero, as seen for Line Item A.
Cart | Quantity | Price | Total price (tax-inclusive) | Proportionate distribution | Even distribution | Individual application |
---|---|---|---|---|---|---|
Line Item A | 1 | €14,00 | €14,00 | €9,84 | €8,67 | €0,00 |
Line Item B | 2 | €20,00 | €40,00 | €28.16 | €29,33 | €8,00 |
----------- | --------- | ------- | ----------- | --------------- | -------- | ------------ |
Total | 3 | €54,00 | €38,00 | €38,00 | €8,00 | |
Discounted total | €0,00 | €16,00 | €16,00 | €46,00 |
CartDiscountValueFixedDraft
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 to or lower than the respective price in the money
field, this Discount is not applied.type ​String​ | "fixed" |
money ​Array of TypedMoneyDraft​ | Money values provided either in cent precision or high precision for different currencies.
A fixed Cart Discount will match a price only if the array contains a value with the same currency. For example, if it contains 10€ and 15$, the matching € price will be discounted by 10€ and the matching $ price will be discounted to 15$.
If the array is empty or has multiple values of the same currency, the API returns an InvalidOperation error. |
applicationMode ​ | Determines how the discount applies on CartDiscountLineItemTarget or CartDiscountCustomLineItemTarget.
For CartDiscountPatternTarget, you can also set the mode to Default: ProportionateDistribution or EvenDistribution .IndividualApplication ​ |
{
"type": "fixed",
"money": {
"centAmount": 2000,
"currencyCode": "EUR"
}
}
CartDiscountValueGiftLineItemDraft
Adds one free Line Item to the Cart as a gift.
When the best deal (between Cart and Product Discounts) applies to a Cart, the gift item is added only after the best deal is calculated. The sort order and stacking mode are effective only among other Cart Discounts with the same discount target.
target
specified.
Hence, this type can not be used in the Change Value update action.type ​String​ | "giftLineItem" |
product ​ | ResourceIdentifier of a Product. A Gift Line Item is added to a Cart even if the referenced Product is unpublished. |
variantId ​Int​ | ProductVariant of the Product. |
supplyChannel ​ | Channel must have the role InventorySupply . |
distributionChannel ​ | Channel must have the role ProductDistribution . |
{
"type": "giftLineItem",
"product": {
"id": "{{product-id}}",
"typeId": "product"
},
"variantId": 1,
"distributionChannel": {
"id": "{{channel-id}}",
"typeId": "channel"
}
}
CartDiscountTarget
Discounts can be applied on LineItems, CustomLineItems, ShippingInfo, or Cart
totalPrice
.CartDiscountLineItemsTarget
predicate
.type ​String​ | "lineItems" |
predicate ​String​ | Valid LineItem target predicate. |
{
"type": "lineItems",
"predicate": "shippingInfo.price = \"50.00 EUR\""
}
CartDiscountCustomLineItemsTarget
predicate
.type ​String​ | "customLineItems" |
predicate ​String​ |
{
"type": "customLineItems",
"predicate": "customLineItemTotal(1 = 1) = \"20.00 EUR\""
}
CartDiscountShippingCostTarget
type ​String​ | "shipping" |
{
"type": "shipping"
}
When the best deal (between Cart and Product Discounts) applies to a Cart, the discount (to the shipping cost) applies only after the best deal is calculated. The sort order and stacking mode are effective only among other Cart Discounts with the same discount target.
CartDiscountTotalPriceTarget
StopAfterThisDiscount
StackingMode of the other Cart Discounts, if any. The sort order for a Cart Total Price discount only determines its ranking among other Cart Discounts targeting the Total Price. As a result, the stackingMode = StopAfterThisDiscount
takes effect for a Cart Total Price discount only when there are other Cart Discounts targeting the Total Price with a lower sort order.MultiBuyLineItemsTarget BETA
quantity
fields.type ​String​ | "multiBuyLineItems" |
predicate ​String​ | Valid LineItem target predicate. The Discount will be applied to Line Items that are matched by the predicate. |
triggerQuantity ​Int​ | Number of Line Items to be present in order to trigger an application of this Discount. Minimum:Â2 ​ |
discountedQuantity ​Int​ | Number of Line Items that are discounted per application of this Discount.
It must be less than or equal to the Minimum: triggerQuantity .1 ​ |
maxOccurrence ​Int​ | Maximum number of times this Discount can be applied. Do not set if the Discount should be applied an unlimited number of times. |
selectionMode ​ | Discounts particular Line Items only according to the SelectionMode. |
{
"type": "multiBuyLineItems",
"predicate": "taxedPrice.gross = \"200.00 EUR\"",
"triggerQuantity": 5,
"discountedQuantity": 2,
"maxOccurrence": 10,
"selectionMode": "Cheapest"
}
triggerQuantity
and discountedQuantity
. For example, if the triggerQuantity
is 6
, and the discountedQuantity
is 2
, then the following cases apply:-
On a Cart with
6
items,2
items are discounted and4
items are undiscounted while participating in the Discount. As a result, the Discount is applied only once. -
On a Cart with
8
items,2
items are discounted,4
items are undiscounted while participating in the Discount, and the2
remaining items are disregarded by the Discount. As a result, the Discount is still applied only once. -
On a Cart with
12
items,2*2
items are discounted and2*4
are undiscounted while participating in the Discount. As a result, the Discount is applied twice.
maxOccurrence
groups of size triggerQuantity
. The remaining items (for example, the ninth item in a "buy 8, get 2 free" discount) do not participate in the Discount. In any such group, only discountedQuantity
items are actually discounted (for example, the second item of a "buy 8, get 2 free" discount); the other items are part of this occurrence and thus, cannot participate in another group and the Price remains unchanged.MultiBuyCustomLineItemsTarget BETA
quantity
fields.MultiBuyLineItems
, but is applied on Custom Line Items instead of Line Items.type ​String​ | "multiBuyCustomLineItems" |
predicate ​String​ | Valid CustomLineItems target predicate. The Discount will be applied to Custom Line Items that are matched by the predicate. |
triggerQuantity ​Int​ | Number of Custom Line Items to be present in order to trigger an application of this Discount. Minimum:Â2 ​ |
discountedQuantity ​Int​ | Number of Custom Line Items that are discounted per application of this Discount.
It must be less than or equal to the Minimum: triggerQuantity .1 ​ |
maxOccurrence ​Int​ | Maximum number of times this Discount can be applied. Do not set if the Discount should be applied an unlimited number of times. |
selectionMode ​ | Discounts particular Line Items only according to the SelectionMode. |
{
"type": "multiBuyCustomLineItems",
"predicate": "taxedPrice.gross = \"200.00 EUR\"",
"triggerQuantity": 2,
"discountedQuantity": 1,
"maxOccurrence": 5,
"selectionMode": "MostExpensive"
}
CartDiscountPatternTarget
Pattern targets can be used to model Buy and Get discounts.
type ​String​ | "pattern" |
triggerPattern ​Array of PatternComponent​ | Defines the set of units of (Custom) Line Items in a Cart that trigger a discount application. Based on the availability of matching units, the
triggerPattern can match multiple times, limiting the number of maximum times the discount will be applied.
The units matched in the triggerPattern are excluded and not considered for the targetPattern .To further limit the discount application, set the maxOccurrence . |
targetPattern ​Array of PatternComponent​ | Defines the set of units of (Custom) Line Items in a Cart on which the Discount is applied. Based on the availability of matching units and the limits from the
triggerPattern or maxOccurrence , the targetPattern can match multiple times.This array cannot be empty. |
maxOccurrence ​Int​ | Maximum number of times the Discount can apply on a Cart. If empty or not set, the Discount will apply indefinitely. |
selectionMode ​ | Determines which of the matching units of (Custom) Line Items are discounted. |
triggerPattern
and targetPattern
) match. Each (pattern) component defines a set of units participating in the Discount; the set can include units coming from different (Custom) Line Items.Components are matched in the order listed in the array. A unit matched in a component will not be available for further matching. The resulting set of units is a combination of the resulting sets of all components.
Let's see a few examples:
-
Example 1: Buy a bundle of 2 pairs of jeans and 1 shirt; get a US$100 discount (distributed evenly) on the bundle. The discount can be applied up to 3 times and the cheapest items are selected for the discount.To obtain this behavior, only fill the
targetPattern
to select the units that will be discounted. The pattern component (targetPattern
) is matched by the union of the units matching each single component.{ "triggerPattern": [], "targetPattern": [ { "type":"CountOnLineItemUnits", "predicate": "categories.key=\"Jeans\"", "minCount": 2, "maxCount": 2 }, { "type":"CountOnLineItemUnits", "predicate": "categories.key=\"Shirt\"", "minCount": 1, "maxCount": 1 } ], "maxOccurrence": 3, "selectionMode": "Cheapest", ... "value": { "type": "absolute", "applicationMode": "EvenDistribution", "money": [ { "type": "centPrecision", "currencyCode": "USD", "centAmount": 10000, "fractionDigits": 2 } ] } }
If a cart contains:
- 1 pair of jeans and 4 shirts, no unit will be selected for the discount as the first target component is not satisfied.
- 4 pairs of jeans, no unit will be selected for the discount as the second target component is not satisfied.
- 3 pairs of jeans and 2 shirts, 1 bundle (of 2 jeans and 1 shirt) will be selected and discounted by US$100.
- 6 pairs of jeans and 5 shirts, 3 bundles will be selected and each bundle will be discounted by US$100. Each time the target pattern is matched, the cheapest bundle will be selected.
- 12 pairs of jeans and 5 shirts, only 3 bundles will be selected and discounted as the maximum allowed limit for the discount application is 3.
-
Example 2: Buy 2 pairs of jeans and get up to 3 shirts at 20% off. The discount can be applied up to 4 times and the most expensive items are selected for the discount.In this scenario, a set of units is required to apply the discount on another set of units. To obtain this behavior, you must define the
triggerPattern
andtargetPattern
.{ "triggerPattern": [ { "type":"CountOnLineItemUnits", "predicate": "categories.key=\"Jeans\"", "minCount": 2, "maxCount": 2 } ], "targetPattern": [ { "type":"CountOnLineItemUnits", "predicate": "categories.key=\"Shirt\"", "minCount": 1, "maxCount": 3 } ], "maxOccurrence": 4, "selectionMode": "MostExpensive", ... "value": { "type": "relative", "permyriad": "200", } }
If a cart contains:
- 2 pairs of jeans and 8 shirts, 3 shirts are discounted as the trigger is matched only once.
- 4 pairs of jeans and 3 shirts, 3 shirts are discounted as the target is matched only once although the trigger is matched twice.
- 4 pairs of jeans and 5 shirts, 5 shirts are discounted as the trigger and target is matched twice.
- 6 pairs of jeans and 6 shirts, 6 shirts are discounted.
- 20 pairs of jeans and 20 shirts, 12 shirts are discounted shirts as the discount is applied a maximum of 4 times.
-
Example 3: Buy 3 tees and get up to 2 other tees at US$20 each. The discount can be applied up any number of times and the cheapest items are selected for the discount.In this scenario, the units that trigger the discount and the units that are targeted by the discount are the same. To obtain this behavior, you must define the
triggerPattern
andtargetPattern
. The units considered in thetriggerPattern
are excluded from thetargetPattern
.
{
"triggerPattern": [
{
"type":"CountOnLineItemUnits",
"predicate": "categories.key=\"Tee\"",
"minCount": 3,
"maxCount": 3
}
],
"targetPattern": [
{
"type":"CountOnLineItemUnits",
"predicate": "categories.key=\"Tee\"",
"minCount": 1,
"maxCount": 2
}
],
"selectionMode": "Cheapest",
...
"value": {
"type": "fixed",
"applicationMode": "IndividualApplication"
"money": [
{
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 2000,
"fractionDigits": 2
}
]
}
}
If a cart contains:
- 3 tees, no tees are discounted as 3 tees are excluded from the discount.
- 4 tees, 1 tee will be discounted from 1 application.
- 5 tees, 2 tees will be discounted from 1 applications.
- 8 tees, 2 tees will be discounted from 2 applications (3 excluded and 2 selected for the first application and 3 excluded for the second application).
- 9 tees, 3 tees will be discounted from 2 applications (3 excluded and 2 selected for the first application and 3 excluded and 1 selected for the second application).
PatternComponent
A component that defines the set of units to participate in the Discount.
CountOnLineItemUnits
type ​String​ | "CountOnLineItemUnits" |
predicate ​String​ | Valid LineItem predicate that determines the units participating in the Discount. |
minCount ​Int​ | Minimum number of units of a Line Item that match the predicate. Default:Â1 ​Minimum: 0 ​ |
maxCount ​Int​ | Maximum number of units of a Line Item that match the predicate. There might be more units matching the predicate, but they will not be participating to the resulting set. The value must be greater than or equal to Minimum: minCount .
If not provided, the component will match all units that satisfy the predicate.1 ​ |
CountOnCustomLineItemUnits
type ​String​ | "CountOnCustomLineItemUnits" |
predicate ​String​ | Valid CustomLineItem predicate that determines the units participating in the Discount. |
minCount ​Int​ | Minimum number of units of a Custom Line Item that match the predicate. Default:Â1 ​Minimum: 0 ​ |
maxCount ​Int​ | Maximum number of units of a Custom Line Item that match the predicate. There might be more units matching the predicate, but they will not be participating to the resulting set. The value must be greater than or equal to Minimum: minCount .
If not provided, the component will match all units that satisfy the predicate.1 ​ |
SelectionMode
Defines which matching items are to be discounted.
Cheapest
Select the cheapest items.
MostExpensive
Select the most expensive items.
If two or more items have the same Price, it is not predictable which of the items are participating in the Discount and which are not. What we guarantee is that the total Discount over all participating items is correct.
Discount always refers to the current Price including already applied Discounts.
StackingMode
Describes how the Cart Discount interacts with other Discounts.
Stacking
Applies other matching Discounts after applying this one.
StopAfterThisDiscount
Doesn't apply any more matching Discounts after this one if it's successfully applied.
freeAbove
on a ShippingRate. To avoid unwanted scenarios, we highly recommend not using Cart Discounts on shipping
target and freeAbove
together.DiscountApplicationMode
This mode determines how absolute Discounts are applied on Line Items or Custom Line Items.
ProportionateDistribution
Distributes the Discount proportionately across eligible Line Items or Custom Line Items.
EvenDistribution
Distributes the Discount evenly across eligible Line Items or Custom Line Items.
IndividualApplication
Applies the Discount individually to eligible Line Item or Custom Line Item.
Get CartDiscount
Get CartDiscount by ID
view_orders:{projectKey}
view_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/cart-discounts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Get CartDiscount by Key
view_orders:{projectKey}
view_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/cart-discounts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Get CartDiscount in Store
Get CartDiscount by ID
view_orders:{projectKey}
view_orders:{projectKey}:{storeKey}
view_cart_discounts:{projectKey}
view_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
id String ​ | id of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Get CartDiscount by Key
view_orders:{projectKey}
view_orders:{projectKey}:{storeKey}
view_cart_discounts:{projectKey}
view_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
key String ​ | key of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Query CartDiscounts
view_orders:{projectKey}
view_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int ​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
CartDiscountPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/cart-discounts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
]
}
Query CartDiscounts in Store
view_orders:{projectKey}
view_orders:{projectKey}:{storeKey}
view_cart_discounts:{projectKey}
view_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int ​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
CartDiscountPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
]
}
Check if CartDiscount exists
Check if CartDiscount exists by ID
id
. Returns a 200 OK
status if the CartDiscount exists or a 404 Not Found
otherwise.view_orders:{projectKey}
view_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the CartDiscount. |
curl --head https://api.{region}.commercetools.com/{projectKey}/cart-discounts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if CartDiscount exists by Key
key
. Returns a 200 OK
status if the CartDiscount exists or a 404 Not Found
otherwise.view_orders:{projectKey}
view_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the CartDiscount. |
curl --head https://api.{region}.commercetools.com/{projectKey}/cart-discounts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if CartDiscount exists by Query Predicate
200 OK
status if any CartDiscounts match the query predicate, or a 404 Not Found
otherwise.view_orders:{projectKey}
view_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/cart-discounts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if CartDiscount exists in Store
Check if CartDiscount exists by ID
id
. Returns a 200 OK
status if the CartDiscount exists or a 404 Not Found
otherwise.view_orders:{projectKey}
view_orders:{projectKey}:{storeKey}
view_cart_discounts:{projectKey}
view_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
id String ​ | id of the CartDiscount. |
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if CartDiscount exists by Key
key
. Returns a 200 OK
status if the CartDiscount exists or a 404 Not Found
otherwise.view_orders:{projectKey}
view_orders:{projectKey}:{storeKey}
view_cart_discounts:{projectKey}
view_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
key String ​ | key of the CartDiscount. |
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if CartDiscount exists by Query Predicate
200 OK
status if any CartDiscounts match the query predicate, or a 404 Not Found
otherwise.view_orders:{projectKey}
view_orders:{projectKey}:{storeKey}
view_cart_discounts:{projectKey}
view_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create CartDiscount
manage_orders:{projectKey}
manage_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/cart-discounts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "black-friday-sale",
"name" : {
"en" : "Black Friday Sale"
},
"description" : {
"en" : "10% discount on all items in cart"
},
"value" : {
"type" : "relative",
"permyriad" : 1000
},
"cartPredicate" : "lineItemTotal(true = true) >= "500.00 USD"",
"target" : {
"type" : "lineItems",
"predicate" : "categories.id = ("{{category-id}}")"
},
"sortOrder" : "0.01",
"stores" : [ {
"key" : "europe",
"typeId" : "store"
} ],
"isActive" : true,
"requiresDiscountCode" : true,
"stackingMode" : "Stacking"
}
DATA
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Create CartDiscount in Store
stores
field are added to the CartDiscount.manage_orders:{projectKey}
manage_orders:{projectKey}:{storeKey}
manage_cart_discounts:{projectKey}
manage_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "black-friday-sale",
"name" : {
"en" : "Black Friday Sale"
},
"description" : {
"en" : "10% discount on all items in cart"
},
"value" : {
"type" : "relative",
"permyriad" : 1000
},
"cartPredicate" : "lineItemTotal(true = true) >= "500.00 USD"",
"target" : {
"type" : "lineItems",
"predicate" : "categories.id = ("{{category-id}}")"
},
"sortOrder" : "0.01",
"stores" : [ {
"key" : "europe",
"typeId" : "store"
} ],
"isActive" : true,
"requiresDiscountCode" : true,
"stackingMode" : "Stacking"
}
DATA
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Update CartDiscount
Update CartDiscount by ID
manage_orders:{projectKey}
manage_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the CartDiscount on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of CartDiscountUpdateAction​ | Update actions to be performed on the CartDiscount. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/cart-discounts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeValue",
"value" : {
"type" : "relative",
"permyriad" : 1500
}
} ]
}
DATA
{
"id": "{{cart-discount-id}}",
"version": 2,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1500
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-12-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Update CartDiscount by Key
manage_orders:{projectKey}
manage_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the CartDiscount on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of CartDiscountUpdateAction​ | Update actions to be performed on the CartDiscount. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/cart-discounts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeValue",
"value" : {
"type" : "relative",
"permyriad" : 1500
}
} ]
}
DATA
{
"id": "{{cart-discount-id}}",
"version": 2,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1500
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-12-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Update CartDiscount in Store
Update CartDiscount by ID
manage_orders:{projectKey}
manage_orders:{projectKey}:{storeKey}
manage_cart_discounts:{projectKey}
manage_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
id String ​ | id of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the CartDiscount on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of CartDiscountUpdateAction​ | Update actions to be performed on the CartDiscount. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeValue",
"value" : {
"type" : "relative",
"permyriad" : 1500
}
} ]
}
DATA
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Update CartDiscount by Key
manage_orders:{projectKey}
manage_orders:{projectKey}:{storeKey}
manage_cart_discounts:{projectKey}
manage_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
key String ​ | key of the CartDiscount. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the CartDiscount on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of CartDiscountUpdateAction​ | Update actions to be performed on the CartDiscount. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeValue",
"value" : {
"type" : "relative",
"permyriad" : 1500
}
} ]
}
DATA
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Update actions
Set Key
action ​String​ | "setKey" |
key ​String​ | Value to set. If empty, any existing value will be removed. MinLength:Â2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
{
"action": "setKey",
"key": "new-key"
}
Change Value
action ​String​ | "changeValue" |
value ​ | New value to set.
When trying to set a CartDiscountValueGiftLineItemDraft an InvalidInput error is returned. |
{
"action": "changeValue",
"value": {
"type": "absolute",
"money": [
{
"currencyCode": "EUR",
"centAmount": 40099
}
],
"applicationMode": "IndividualApplication"
}
}
Change Cart Predicate
action ​String​ | "changeCartPredicate" |
cartPredicate ​String​ | New value to set. |
{
"action": "changeCartPredicate",
"cartPredicate": "shippingInfo.taxRate.country = \"DE\""
}
Change Target
action ​String​ | "changeTarget" |
target ​ | New value to set. |
{
"action": "changeTarget",
"target": {
"type": "lineItems",
"predicate": "sku = \"myOtherSKU\""
}
}
Change IsActive
action ​String​ | "changeIsActive" |
isActive ​Boolean​ | New value to set.
If set to
true , the Discount will be applied to the Cart.If the limit for active Cart Discounts is reached, a MaxCartDiscountsReached error is returned. |
{
"action": "changeIsActive",
"isActive": false
}
Change Name
action ​String​ | "changeName" |
name ​ | New value to set. |
{
"action": "changeName",
"name": {
"en": "New name",
"de": "Neuer Name"
}
}
Set Description
action ​String​ | "setDescription" |
description ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setDescription",
"description": {
"en": "New description",
"de": "neue Beschreibung"
}
}
Change Sort Order
action ​String​ | "changeSortOrder" |
sortOrder ​String​ | New value to set (between 0 and 1 ).
A Discount with a higher sortOrder is prioritized. |
{
"action": "changeSortOrder",
"sortOrder": "0.1"
}
Change Requires DiscountCode
action ​String​ | "changeRequiresDiscountCode" |
requiresDiscountCode ​Boolean​ | New value to set.
If set to true , the Discount can only be used in connection with a DiscountCode. |
{
"action": "changeRequiresDiscountCode",
"requiresDiscountCode": false
}
Set Valid From
action ​String​ | "setValidFrom" |
validFrom ​DateTime​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setValidFrom",
"validFrom": "2025-10-15T15:00:00.000Z"
}
Set Valid Until
action ​String​ | "setValidUntil" |
validUntil ​DateTime​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setValidUntil",
"validUntil": "2025-11-15T20:00:00.000Z"
}
Set Valid From and Until
action ​String​ | "setValidFromAndUntil" |
validFrom ​DateTime​ | Value to set. If empty, any existing value will be removed. |
validUntil ​DateTime​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setValidFromAndUntil",
"validFrom": "2025-10-15T15:00:00.000Z",
"validUntil": "2025-11-15T15:05:00.000Z"
}
Change Stacking Mode
action ​String​ | "changeStackingMode" |
stackingMode ​StackingMode​ | New value to set. |
{
"action": "changeStackingMode",
"stackingMode": "StopAfterThisDiscount"
}
Add Store
action ​String​ | "addStore" |
store ​ | Store to add.
A failed update can return the following errors:
|
{
"action": "addStore",
"store": {
"key": "{{store-key}}"
}
}
Remove Store
action ​String​ | "removeStore" |
store ​ | Store to remove. |
{
"action": "removeStore",
"store": {
"key": "{{store-key}}"
}
}
Set Stores
action ​String​ | "setStores" |
stores ​Array of StoreResourceIdentifier​ | Stores to set.
Overrides the current list of Stores.
If empty, any existing values will be removed.
A failed update can return the following errors:
500 ​ |
{
"action": "setStores",
"stores": [
{
"key": "store-one"
},
{
"key": "store-two"
},
{
"key": "store-three"
}
]
}
Set Custom Type
action ​String​ | "setCustomType" |
type ​ | Defines the Type that extends the CartDiscount with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the CartDiscount. |
fields ​ | Sets the Custom Fields fields for the CartDiscount. |
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set CustomField
action ​String​ | "setCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If value is absent or null , this field will be removed if it exists.
Removing a field that does not exist returns an InvalidOperation error.
If value is provided, it is set for the field defined by name . |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}
Delete CartDiscount
Delete CartDiscount by ID
manage_orders:{projectKey}
manage_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the CartDiscount. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/cart-discounts/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Delete CartDiscount by Key
manage_orders:{projectKey}
manage_cart_discounts:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the CartDiscount. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/cart-discounts/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Delete CartDiscount in Store
Delete CartDiscount by ID
manage_cart_discounts:{projectKey}:{storeKey}
scope for all Stores associated with the CartDiscount.manage_orders:{projectKey}
manage_orders:{projectKey}:{storeKey}
manage_cart_discounts:{projectKey}
manage_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
id String ​ | id of the CartDiscount. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}
Delete CartDiscount by Key
manage_cart_discounts:{projectKey}:{storeKey}
scope for all Stores associated with the CartDiscount.manage_orders:{projectKey}
manage_orders:{projectKey}:{storeKey}
manage_cart_discounts:{projectKey}
manage_cart_discounts:{projectKey}:{storeKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
storeKey String ​ | key of the Store. |
key String ​ | key of the CartDiscount. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/cart-discounts/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "{{cart-discount-id}}",
"version": 1,
"key": "black-friday-sale",
"name": {
"en": "Black Friday Sale"
},
"description": {
"en": "10% discount on all items in cart"
},
"value": {
"type": "relative",
"permyriad": 1000
},
"cartPredicate": "lineItemTotal(true = true) >= \"500.00 USD\"",
"target": {
"type": "lineItems",
"predicate": "categories.id = (\"{{category-id}}\")"
},
"sortOrder": "0.01",
"stores": [
{
"typeId": "store",
"key": "europe"
}
],
"isActive": true,
"references": [
{
"typeId": "category",
"id": "{{category-id}}"
}
],
"stackingMode": "Stacking",
"requiresDiscountCode": true,
"createdAt": "2024-11-21T13:08:15.962Z",
"lastModifiedAt": "2024-11-21T13:08:15.962Z",
"lastModifiedBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{{client-id}}",
"isPlatformClient": false
}
}