Queries and mutations for managing Cart Discounts in the platform.

Queries

Query Cart Discounts

QUERYcartDiscounts
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Cart Discount

QUERYcartDiscount
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Mutations

Create Cart Discount

MUTATIONcreateCartDiscount
Arguments
draft​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Update Cart Discount

MUTATIONupdateCartDiscount
Arguments
version​
Long​
actions​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Delete Cart Discount

MUTATIONdeleteCartDiscount
Arguments
version​
Long​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output types

CartDiscount

Cart discounts are recalculated every time LineItems or CustomLineItems are added or removed from the Cart or an order is created from the cart.

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

cartPredicate​
String​
stackingMode​

Indicates whether the application of the CartDiscount causes other discounts to be ignored.

Can be Stacking, or StopAfterThisDiscount​
isActive​
Boolean​

Indicates if the CartDiscount is active and can be applied to the Cart.

requiresDiscountCode​
Boolean​
Indicates if the Discount is used in connection with a DiscountCode.
key​
String​

User-defined unique identifier of the CartDiscount.

discountGroupRef​

Reference to a DiscountGroup that the CartDiscount belongs to.

name​
String​

Name of the CartDiscount.

description​
String​

Description of the CartDiscount.

nameAllLocales​
Array of LocalizedString​

Name of the CartDiscount.

descriptionAllLocales​
Array of LocalizedString​

Description of the CartDiscount.

referenceRefs​
Array of Reference​
custom​

Custom Fields of the CartDiscount.

validFrom​

Date and time (UTC) from which the Discount is effective.

validUntil​

Date and time (UTC) until which the Discount is effective.

storesRef​
Array of KeyReference​
  • If a value exists, the Cart Discount applies on Carts having a Store matching any Store defined for this field.
  • If empty, the Cart Discount applies on all Carts, irrespective of a Store.
stores​
Array of Store​
  • If a value exists, the Cart Discount applies on Carts having a Store matching any Store defined for this field.
  • If empty, the Cart Discount applies on all Carts, irrespective of a Store.
discountGroup​

Reference to a DiscountGroup that the CartDiscount belongs to.

value​
Effect of the CartDiscount on the target.
target​

Segment of the Cart that is discounted.

Absent if the value is giftLineItem.
sortOrder​
String​
Value between 0 and 1 that determines the order in which the CartDiscounts are applied; a CartDiscount with a higher value is prioritized.

It is unique among all CartDiscounts and DiscountGroups.

If the CartDiscount is part of a DiscountGroup, it uses the sort order of the DiscountGroup.

recurringOrderScope​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
id​
String​

Unique identifier of the CartDiscount.

version​
Long​

Current version of the CartDiscount.

createdAt​

Date and time (UTC) the CartDiscount was initially created.

lastModifiedAt​

Date and time (UTC) the CartDiscount was last updated.

createdBy​

IDs and references that created the CartDiscount.

lastModifiedBy​

IDs and references that last modified the CartDiscount.

StackingMode

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

CartDiscountValue

type​
String​

CartDiscountTarget

type​
String​

Cart Discount Query Result

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of CartDiscount​

Input types

CartDiscountDraft

value​
Effect of the CartDiscount on the target.
cartPredicate​
String​
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 that determines the order in which the CartDiscounts will be applied; a CartDiscount with a higher value will be prioritized.
If the value is used by another Cart Discount or Discount Group, a DuplicateField error is returned.

If the CartDiscount is part of a DiscountGroup, it will use the sort order of the DiscountGroup.

name​

Name of the CartDiscount.

description​

Description of the CartDiscount.

validFrom​

Date and time (UTC) from which the Discount is effective.

validUntil​

Date and time (UTC) until which the Discount is effective.

stackingMode​

Specifies whether the application of this discount causes the following discounts to be ignored.

Can be Stacking, or StopAfterThisDiscount​Default: Stacking​
requiresDiscountCode​
Boolean​
States whether the Discount can only be used in a connection with a DiscountCode.
Default: false​
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​
custom​

Custom Fields for the CartDiscount.

key​
String​

User-defined unique identifier for the CartDiscount.

If the value is used by another Cart Discount, a DuplicateField error is returned.
stores​
  • If defined, the Cart Discount applies on Carts having a Store matching any Store defined for this field.
  • If not defined, the Cart Discount applies on all Carts, irrespective of a Store.
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.
discountGroup​

Reference to a DiscountGroup that the CartDiscount must belong to.

A CartDiscount can only be added to a DiscountGroup if its target.type is lineItems, customLineItems, multiBuyLineItems, multiBuyCustomLineItems, or pattern; otherwise, an InvalidInput error is returned.
recurringOrderScope​

Scope of the Cart Discount for Recurring Orders.

If not set, the default is NonRecurringOrdersOnlyDraft.

CartDiscountValueInput

relative​
relativeCart​
absolute​
absoluteCart​
fixed​
fixedCart​
giftLineItem​

RelativeDiscountValueInput

permyriad​
Int​

RelativeCartDiscountValueInput

permyriad​
Int​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

DiscountApplicationMode

ProportionateDistribution
EvenDistribution
IndividualApplication

AbsoluteDiscountValueInput

money​
Array of MoneyInput​

MoneyInput

currencyCode​
centAmount​
Long​

AbsoluteCartDiscountValueInput

money​
Array of MoneyInput​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

FixedPriceDiscountValueInput

money​

CartDiscountValueBaseMoneyInput

centPrecision​
highPrecision​
currencyCode​
CurrencyCode and centAmount are deprecated. Please use Money(centPrecision) or HighPrecisionMoney(highPrecision).
centAmount​
Long​
CurrencyCode and centAmount are deprecated. Please use Money(centPrecision) or HighPrecisionMoney(highPrecision).

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

FixedPriceCartDiscountValueInput

money​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

GiftLineItemValueInput

variantId​
Int​
distributionChannel​
supplyChannel​

CartDiscountTargetInput

lineItems​
customLineItems​
shipping​
multiBuyLineItems​
multiBuyCustomLineItems​
totalPrice​
pattern​

LineItemsTargetInput

predicate​
String​

CustomLineItemsTargetInput

predicate​
String​

ShippingTargetInput

dummy​
String​

MultiBuyLineItemsTargetInput

predicate​
String​
triggerQuantity​
Long​
discountedQuantity​
Long​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

SelectionMode

Cheapest
MostExpensive

MultiBuyCustomLineItemsTargetInput

predicate​
String​
triggerQuantity​
Long​
discountedQuantity​
Long​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

CartDiscountTotalPriceTargetInput

dummy​
String​

CartDiscountPatternTargetInput

triggerPattern​
targetPattern​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

PatternComponentInput

CountOnLineItemUnits​
CountOnCustomLineItemUnits​

CountOnLineItemUnitsInput

predicate​
String​
minCount​
Int​
Default: 1​
maxCount​
Int​
excludeCount​
Int​

CountOnCustomLineItemUnitsInput

predicate​
String​
minCount​
Int​
Default: 1​
maxCount​
Int​
excludeCount​DEPRECATED
Int​

Please use 'triggerPattern' to exclude.

StackingMode

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

CartDiscountUpdateAction

setStores​
addStore​
removeStore​
setRecurringOrderScope​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
changeCartPredicate​
changeIsActive​
changeName​
changeRequiresDiscountCode​
changeSortOrder​
changeStackingMode​
changeTarget​
changeValue​
setCustomField​
setCustomType​
setDescription​
setKey​
setValidFrom​
setValidFromAndUntil​
setValidUntil​
setDiscountGroup​

Update actions

Set Stores

If a referenced Store does not exist, a ReferencedResourceNotFound error is returned.
This action generates a CartDiscountStoresSet Message.
stores​
Stores to set. Overrides the current list of Stores. Set to an empty array to remove all existing values.
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.

Add Store

If a referenced Store does not exist, a ReferencedResourceNotFound error is returned.
This action generates a CartDiscountStoreAdded Message.
Store to add.
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.

Remove Store

If a referenced Store does not exist, a ReferencedResourceNotFound error is returned.
This action generates a CartDiscountStoreRemoved Message.
Store to remove.

Set Recurring Order Scope

Sets the scope of the Cart Discount for Recurring Orders.

recurringOrderScope​

Scope of the Cart Discount for Recurring Orders.

Change Cart Predicate

cartPredicate​
String​

New value to set.

Change Is Active

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.

Change Name

name​

New value to set.

Change Requires Discount Code

requiresDiscountCode​
Boolean​
New value to set. If true, the Cart Discount can only be used with a DiscountCode.
When set to false, if the number of active Cart Discounts without a Discount Code exceeds the limit, a MaxCartDiscountsReached error is returned.

Change Sort Order

sortOrder​
String​
New value to set (between 0 and 1). A Discount with a higher sortOrder is prioritized.
If the value is used by another Cart Discount or Discount Group, a DuplicateField error is returned.

Change Stacking Mode

stackingMode​

New value to set.

Can be Stacking, or StopAfterThisDiscount​

StackingMode

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

Change Target

target​

New value to set.

For a CartDiscountValueRelative, if applicationMode is set, the target must be CartDiscountPatternTarget. If applicationMode is ProportionateDistribution or EvenDistribution, the CartDiscountPatternTarget triggerPattern must be non-empty. If either conditions are not met, an InvalidOperation error is returned.

CartDiscountTargetInput

lineItems​
customLineItems​
shipping​
multiBuyLineItems​
multiBuyCustomLineItems​
totalPrice​
pattern​

LineItemsTargetInput

predicate​
String​

CustomLineItemsTargetInput

predicate​
String​

ShippingTargetInput

dummy​
String​

MultiBuyLineItemsTargetInput

predicate​
String​
triggerQuantity​
Long​
discountedQuantity​
Long​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

SelectionMode

Cheapest
MostExpensive

MultiBuyCustomLineItemsTargetInput

predicate​
String​
triggerQuantity​
Long​
discountedQuantity​
Long​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

CartDiscountTotalPriceTargetInput

dummy​
String​

CartDiscountPatternTargetInput

triggerPattern​
targetPattern​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

PatternComponentInput

CountOnLineItemUnits​
CountOnCustomLineItemUnits​

CountOnLineItemUnitsInput

predicate​
String​
minCount​
Int​
Default: 1​
maxCount​
Int​
excludeCount​
Int​

CountOnCustomLineItemUnitsInput

predicate​
String​
minCount​
Int​
Default: 1​
maxCount​
Int​
excludeCount​DEPRECATED
Int​

Please use 'triggerPattern' to exclude.

Change Value

Changes the CartDiscountValue for relative, absolute and fixed price CartDiscounts. Changing to Gift Line Item is not supported.
value​

New value to set.

When trying to set a CartDiscountValueGiftLineItemDraft an InvalidInput error is returned.

CartDiscountValueInput

relative​
relativeCart​
absolute​
absoluteCart​
fixed​
fixedCart​
giftLineItem​

RelativeDiscountValueInput

permyriad​
Int​

RelativeCartDiscountValueInput

permyriad​
Int​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

DiscountApplicationMode

ProportionateDistribution
EvenDistribution
IndividualApplication

AbsoluteDiscountValueInput

money​
Array of MoneyInput​

MoneyInput

currencyCode​
centAmount​
Long​

AbsoluteCartDiscountValueInput

money​
Array of MoneyInput​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

FixedPriceDiscountValueInput

money​

CartDiscountValueBaseMoneyInput

centPrecision​
highPrecision​
currencyCode​
CurrencyCode and centAmount are deprecated. Please use Money(centPrecision) or HighPrecisionMoney(highPrecision).
centAmount​
Long​
CurrencyCode and centAmount are deprecated. Please use Money(centPrecision) or HighPrecisionMoney(highPrecision).

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

FixedPriceCartDiscountValueInput

money​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

GiftLineItemValueInput

variantId​
Int​
distributionChannel​
supplyChannel​

Set Custom Field

name​
String​
Name of the Custom Field.
value​
String​
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.

Set Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Description

description​

Value to set. If omitted, any existing value is removed.

Set Key

key​
String​

Value to set. If omitted, any existing value is removed.

If the value is used by another Cart Discount, a DuplicateField error is returned.

Set Valid From

validFrom​

Value to set. If omitted, any existing value is removed.

Set Valid From And Until

validFrom​

Value to set. If omitted, any existing value is removed.

validUntil​

Value to set. If omitted, any existing value is removed.

Set Valid Until

validUntil​

Value to set. If omitted, any existing value is removed.

Set Discount Group

discountGroup​

Reference to a DiscountGroup that the CartDiscount must belong to. If omitted, any existing value is removed.

A CartDiscount can only be added to a DiscountGroup if its target.type is lineItems, customLineItems, multiBuyLineItems, multiBuyCustomLineItems, or pattern; otherwise, an InvalidInput error is returned.
sortOrder​
String​
New value to set (between 0 and 1) that determines the order in which the CartDiscounts are applied; a CartDiscount with a higher value is prioritized.
Required if discountGroup is absent. If discountGroup is set, the CartDiscount will use the sort order of the DiscountGroup.