This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.
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
. Learn more about this limit.
Cart Discounts can be defined globally for the Project or specific to one or more (up to 500
) Stores.
In the latter case the Cart Discount is only applied to Carts that belong to one of the Stores referenced in the CartDiscount's stores
array.
In case the array is empty or unspecified the Discount is applied to all Carts.
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 |
cartPredicate String | Valid Cart Predicate. |
target | Segment of the Cart that is discounted. Empty, if the |
sortOrder String | Value between |
stores Array of StoreKeyReference | |
isActive Boolean | Indicates if the CartDiscount is active and can be applied to the Cart. |
validFrom | Date and time (UTC) from which the Discount is effective. |
validUntil | Date and time (UTC) until which the Discount is effective. |
requiresDiscountCode Boolean | Indicates if the Discount is used in connection with a DiscountCode. Default:false |
references Array of Reference | References of all resources that are addressed in the predicate. The API generates this array from the predicate. |
stackingMode | Indicates whether the application of the CartDiscount causes other discounts to be ignored. Default:Stacking |
custom | Custom Fields of the CartDiscount. |
createdAt | Date and time (UTC) for the CartDiscount was initially created. |
createdBy BETA | Present on resources created after 1 February 2019 except for events not tracked. |
lastModifiedAt | Date and time (UTC) for the CartDiscount was last updated. |
lastModifiedBy BETA | Present on resources updated after 1 February 2019 except for events not tracked. |
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 |
cartPredicate String | Valid Cart Predicate. |
target | Segment of the Cart that will be discounted. Must not be set if the |
sortOrder String | Value between |
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 | Date and time (UTC) from which the Discount is effective. |
validUntil | 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. Default:false |
stackingMode | Specifies whether the application of this discount causes the following discounts to be ignored. Default:Stacking |
custom | Custom Fields of the CartDiscount. |
CartDiscountPagedQueryResponse
PagedQueryResult with results
containing an array of CartDiscount.
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
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 |
results Array of CartDiscount | CartDiscounts matching the query. |
CartDiscountReference
Reference to a CartDiscount.
id String | Unique identifier of the referenced CartDiscount. |
typeId String | "cart-discount" References a CartDiscount. |
obj | Contains the representation of the expanded CartDiscount. Only present in responses to requests with Reference Expansion for CartDiscounts. |
CartDiscountResourceIdentifier
ResourceIdentifier to a CartDiscount. Either 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 String | User-defined unique identifier of the referenced CartDiscount. Required if |
typeId String | "cart-discount" References a CartDiscount. |
CartDiscountValue
Defines the effect the Discount will have on the specified 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.
CartDiscountValueRelative
Discounts the CartDiscountTarget relative to its price.
type String | "relative" |
permyriad Int | Fraction (per ten thousand) the price is reduced by. For example, |
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
Discounts the CartDiscountTarget by an absolute amount (not allowed for MultiBuyLineItemsTarget and MultiBuyCustomLineItemsTarget).
type String | "absolute" |
money Array of CentPrecisionMoney | Cent precision money values in different currencies. |
CartDiscountValueFixed
Sets the DiscountedLineItemPrice of the CartDiscountLineItemsTarget or CartDiscountCustomLineItemsTarget 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 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. |
CartDiscountValueGiftLineItem
Adds a free Line Item as a gift to the Cart.
A Gift Line Item is automatically added to the Cart when the Discount Predicate evaluates as true. However, only one Gift Line Item can be added to a Cart.
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.
If at creation time the Discount can not be applied to any Cart (for example because the Product, the Product 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 Product Variant, or a Channel have been deleted) or because no Price can be selected for the particular Cart.
type String | "giftLineItem" |
product | Reference to a Product. |
variantId Int | ProductVariant of the Product. |
supplyChannel | Channel must have the ChannelRoleEnum |
distributionChannel | Channel must have the ChannelRoleEnum |
Cannot be combined with MultiBuyLineItemsTarget.
CartDiscountValueDraft
Defines the effect the Discount will have on the specified target. Relative or absolute Discount values or a fixed item Price value can be specified. To specify a Gift Line Item Cart Discount, use the Gift Line Item draft.
CartDiscountValueRelativeDraft
type String | "relative" |
permyriad Int | Fraction (per ten thousand) the price is reduced by. For example, |
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 has multiple values of the same currency, the API returns an InvalidOperation error. If the array is empty, the discount does not apply. |
CartDiscountValueFixedDraft
Sets the DiscountedLineItemPrice of the CartDiscountLineItemsTarget or CartDiscountCustomLineItemsTarget 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 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 has multiple values of the same currency, the API returns an InvalidOperation error. If the array is empty, the discount does not apply. |
CartDiscountValueGiftLineItemDraft
Can only be used in a CartDiscountDraft with no target
specified.
Hence, this type can not be used in the Change Value update action.
type String | "giftLineItem" |
product | ResourceIdentifier of a Product. |
variantId Int | ProductVariant of the Product. |
supplyChannel | Channel must have the role |
distributionChannel | Channel must have the role |
CartDiscountTarget
Defines what segment of the Cart will be discounted.
Discounts can be applied on LineItems, CustomLineItems, ShippingInfo, or Cart totalPrice
.
CartDiscountLineItemsTarget
Discount is applied to LineItems matching the predicate
.
type String | "lineItems" |
predicate String | Valid LineItem target predicate. |
CartDiscountCustomLineItemsTarget
Discount is applied to CustomLineItems matching the predicate
.
type String | "customLineItems" |
predicate String |
CartDiscountShippingCostTarget
Discount is applied to the shipping costs of the Cart.
type String | "shipping" |
CartDiscountTotalPriceTarget
Discount is applied to the total price of the Cart.
type String | "totalPrice" |
MultiBuyLineItemsTarget BETA
Multi-buy Discounts represent a "Buy X items, get Y of them at a discounted rate" type of discount. Multi-buy Line Items can only be discounted relatively.
To select the items relevant for the Discount, a LineItem Predicate is applied. Unlike LineItems Target, a multi-buy Discount is not applied on each LineItem as a whole, but on individual items that are contained in all matching Line Items and subsumed under their 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 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. |
A multi-buy Discount can occur multiple times in a Cart, but any item will only be considered once per multi-buy Discount. A single application of a multi-buy Discount is defined by the 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.
A participation is represented by a DiscountedLineItemPortion with discountedAmount.centAmount
= 0
.
To recap, the matching items of a Discount application are sliced into maxOccurence
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
Multi-buy Custom Line Items can only be discounted relatively.
To select the items relevant for the Discount, a CustomLineItem Predicate is applied. Unlike CustomLineItems Target, a multi-buy Discount is not applied on each CustomLineItem as a whole, but on individual items that are contained in all matching Custom Line Items and subsumed under their quantity
fields.
This Discount target is similar to 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 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. |
SelectionMode
Defines which matching items are to be discounted.
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 cheapest or most expensive ones will be discounted, depending on this setting.
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.
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
view_orders:{projectKey} ,
view_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Get CartDiscount by Key
view_orders:{projectKey} ,
view_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
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 |
|
storeKey String |
|
id String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
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 |
|
storeKey String |
|
key String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Query CartDiscounts
view_orders:{projectKey} ,
view_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. 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. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to |
application/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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}]}
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 |
|
storeKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. 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. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to |
application/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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}]}
Check if CartDiscount exists
Check if CartDiscount exists by ID
Checks if a CartDiscount exists for a given 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 |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/cart-discounts/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if CartDiscount exists by Key
Checks if a CartDiscount exists for a given 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 String |
|
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
Checks if a CartDiscount exists for a given Query Predicate. Returns a 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 |
|
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
Checks if a CartDiscount exists for a given 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 |
|
storeKey String |
|
id String |
|
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
Checks if a CartDiscount exists for a given 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 |
|
storeKey String |
|
key String |
|
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
Checks if a CartDiscount exists for a given Query Predicate. Returns a 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 |
|
storeKey String |
|
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
Creating a Cart Discount produces the CartDiscountCreated Message.
manage_orders:{projectKey} ,
manage_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
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{"name" : {"en" : "Summer Sale"},"value" : {"type" : "relative","permyriad" : 1000},"cartPredicate" : "1=1","target" : {"type" : "lineItems","predicate" : "1=1"},"sortOrder" : "0.1","stores" : [ {"key" : "{{store-key}}"} ],"isActive" : true,"requiresDiscountCode" : false}DATA
{"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Create CartDiscount in Store
When using the endpoint, the Store specified in the path and the Stores specified in the payload's stores
field are added to the CartDiscount.
Creating a Cart Discount produces the CartDiscountCreated Message.
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 |
|
storeKey String |
|
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{"name" : {"en" : "Summer Sale"},"value" : {"type" : "relative","permyriad" : 1000},"cartPredicate" : "1=1","target" : {"type" : "lineItems","predicate" : "1=1"},"sortOrder" : "0.1","stores" : [ {"key" : "{{store-key}}"} ],"isActive" : true,"requiresDiscountCode" : false}DATA
{"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Update CartDiscount
Update CartDiscount by ID
manage_orders:{projectKey} ,
manage_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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" : 1000}} ]}DATA
{"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Update CartDiscount by Key
manage_orders:{projectKey} ,
manage_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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" : 1000}} ]}DATA
{"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Update CartDiscount in Store
Update CartDiscount by ID
To update a CartDiscount, you must have permissions for all Stores the CartDiscount is associated with, except when removing a Store.
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 |
|
storeKey String |
|
id String |
|
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" : 1000}} ]}DATA
{"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Update CartDiscount by Key
To update a CartDiscount, you must have permissions for all Stores the CartDiscount is associated with, except when removing a Store.
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 |
|
storeKey String |
|
key String |
|
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" : 1000}} ]}DATA
{"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
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
Changes the CartDiscountValue for relative, absolute and fixed price CartDiscounts. Changing to Gift Line Item is not supported.
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}]}}
Change Cart Predicate
action String | "changeCartPredicate" |
cartPredicate String | New value to set. |
{"action": "changeCartPredicate","cartPredicate": "cartPredicateString"}
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 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": "NewNameEN","de": "NewNameDE"}}
Set Description
action String | "setDescription" |
description | Value to set. If empty, any existing value will be removed. |
{"action": "setDescription","description": {"en": "New Description EN","de": "New Description DE"}}
Change Sort Order
action String | "changeSortOrder" |
sortOrder String | New value to set (between |
{"action": "changeSortOrder","sortOrder": "0.2"}
Change Requires DiscountCode
action String | "changeRequiresDiscountCode" |
requiresDiscountCode Boolean | New value to set.
If set to |
{"action": "changeRequiresDiscountCode","requiresDiscountCode": true}
Set Valid From
action String | "setValidFrom" |
validFrom | Value to set. If empty, any existing value will be removed. |
{"action": "setValidFrom","validFrom": "2017-10-15T15:00:00.000Z"}
Set Valid Until
action String | "setValidUntil" |
validUntil | Value to set. If empty, any existing value will be removed. |
{"action": "setValidUntil","validUntil": "2017-10-15T20:00:00.000Z"}
Set Valid From and Until
action String | "setValidFromAndUntil" |
validFrom | Value to set. If empty, any existing value will be removed. |
validUntil | Value to set. If empty, any existing value will be removed. |
{"action": "setValidFromAndUntil","validFrom": "2017-10-15T15:00:00.000Z","validUntil": "2017-10-15T15:05:00.000Z"}
Change Stacking Mode
action String | "changeStackingMode" |
stackingMode | New value to set. |
{"action": "changeStackingMode","stackingMode": "Stacking"}
Add Store
If a referenced Store does not exist, a ReferencedResourceNotFound error is returned.
This action generates a CartDiscountStoreAdded Message.
action String | "addStore" |
store | Store to add. A failed update can return the following errors:
|
{"action": "addStore","store": {"key": "{{store-key}}"}}
Remove Store
If a referenced Store does not exist, a ReferencedResourceNotFound error is returned.
This action generates a CartDiscountStoreRemoved Message.
action String | "removeStore" |
store | Store to remove. |
{"action": "removeStore","store": {"key": "{{store-key}}"}}
Set Stores
If a referenced Store does not exist, a ReferencedResourceNotFound error is returned.
This action generates a CartDiscountStoresSet Message.
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": {"exampleStringTypeField": "TextString"}}
Set CustomField
action String | "setCustomField" |
name String | Name of the Custom Field. |
value | If |
{"action": "setCustomField","name": "ExampleStringTypeField","value": "TextString"}
Delete CartDiscount
Delete CartDiscount by ID
Deleting a Cart Discount produces the CartDiscountDeleted Message.
manage_orders:{projectKey} ,
manage_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Delete CartDiscount by Key
Deleting a Cart Discount produces the CartDiscountDeleted Message.
manage_orders:{projectKey} ,
manage_cart_discounts:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Delete CartDiscount in Store
Delete CartDiscount by ID
To delete a CartDiscount, specify the manage_cart_discounts:{projectKey}:{storeKey}
scope for all Stores associated with the CartDiscount.
Deleting a Cart Discount produces the CartDiscountDeleted Message.
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 |
|
storeKey String |
|
id String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}
Delete CartDiscount by Key
To delete a CartDiscount, specify the manage_cart_discounts:{projectKey}:{storeKey}
scope for all Stores associated with the CartDiscount.
Deleting a Cart Discount produces the CartDiscountDeleted Message.
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 |
|
storeKey String |
|
key String |
|
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": "c2f93298-c967-44af-8c2a-d2220bf39eb2","version": 1,"createdAt": "1970-01-01T00:00:00.001Z","lastModifiedAt": "1970-01-01T00:00:00.001Z","name": {"en": "Summer Sale"},"value": {"type": "relative","permyriad": 1000},"cartPredicate": "1=1","target": {"type": "lineItems","predicate": "1=1"},"sortOrder": "0.1","stores": [{"key": "{{store-key}}","typeId": "store"}],"isActive": true,"requiresDiscountCode": false,"references": [],"stackingMode": "Stacking"}