This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Carts

A Cart is a representation of a shopping cart containing items that a customer intends to purchase.

A maximum of 10 000 000 Carts can be added to a Project. If a Project contains more Carts, the least recently modified resources are automatically deleted. Learn more about this limit. The number of Discount Codes in a Cart is limited to 10.

Representations

Cart

id
String

Unique identifier of the Cart.

version
Int

Current version of the Cart.

key
String

User-defined unique identifier of the Cart.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
customerId
String

id of the Customer that the Cart belongs to.

customerEmail
String

Email address of the Customer that the Cart belongs to.

customerGroup

Reference to the Customer Group of the Customer that the Cart belongs to. Used for LineItem Price selection.

anonymousId
String

Anonymous session associated with the Cart.

businessUnit

Reference to a Business Unit the Cart belongs to.

Reference to a Store the Cart belongs to.

lineItems
Array of LineItem

Line Items added to the Cart.

customLineItems
Array of CustomLineItem

Custom Line Items added to the Cart.

totalLineItemQuantity
Int

Sum of all LineItem quantities, excluding CustomLineItems. Only present when the Cart has at least one LineItem.

totalPrice

Sum of the totalPrice field of all LineItems and CustomLineItems, and if available, the price field of ShippingInfo. If a discount applies on totalPrice, this field holds the discounted value.

Taxes are included if TaxRate includedInPrice is true for each price.

taxedPrice
  • For a Cart with Platform TaxMode, it is automatically set when a shipping address is set.
  • For a Cart with External TaxMode, it is automatically set when shippingAddress and external Tax Rates for all Line Items, Custom Line Items, and Shipping Methods in the Cart are set.

If a discount applies on totalPrice, this field holds the discounted values.

taxedShippingPrice

Sum of the taxedPrice field of ShippingInfo across all Shipping Methods.

discountOnTotalPrice

Discounts that apply on the Cart totalPrice.

taxMode

Indicates how Tax Rates are set.

Default: Platform
taxRoundingMode

Indicates how monetary values are rounded when calculating taxes for taxedPrice.

Default: HalfEven
taxCalculationMode

Indicates how taxes are calculated when calculating taxes for taxedPrice.

Default: LineItemLevel
inventoryMode

Indicates how stock quantities are tracked for Line Items in the Cart.

Default: None
cartState

Current status of the Cart.

Default: Active
billingAddress

Billing address associated with the Cart.

shippingAddress

Shipping address for a Cart with Single ShippingMode. Determines eligible ShippingMethod rates and Tax Rates of Line Items.

shippingMode

Indicates whether the Cart has one or multiple Shipping Methods.

Default: Single
shippingKey
String

User-defined unique identifier of the Shipping Method in a Cart with Single ShippingMode.

shippingInfo

Shipping-related information of a Cart with Single ShippingMode. Automatically set when a Shipping Method is set.

shippingRateInput

Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

shippingCustomFields

Custom Fields of the Shipping Method in a Cart with Single ShippingMode.

shipping
Array of Shipping

Shipping-related information of a Cart with Multiple ShippingMode. Updated automatically each time a new Shipping Method is added.

itemShippingAddresses
Array of Address

Additional shipping addresses of the Cart as specified by LineItems using the shippingDetails field.

For Carts with Single ShippingMode: eligible Shipping Methods or applicable Tax Rates are determined by the address in shippingAddress, and not itemShippingAddresses.

discountCodes
Array of DiscountCodeInfo

Discount Codes applied to the Cart. A Cart that has directDiscounts cannot have discountCodes.

directDiscounts
Array of DirectDiscount

Direct Discounts added to the Cart. A Cart that has discountCodes cannot have directDiscounts.

refusedGifts

Automatically set when a Line Item with GiftLineItem LineItemMode is removed from the Cart.

paymentInfo

Payment information related to the Cart.

country
locale

Languages of the Cart. Can only contain languages supported by the Project.

origin

Indicates how the Cart was created.

Default: Customer
deleteDaysAfterLastModification
Int

Number of days after which an active Cart is deleted since its last modification. Configured in Project settings.

Default: 90
custom

Custom Fields of the Cart.

createdAt

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

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

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

lastModifiedByBETA

Present on resources updated after 1 February 2019 except for events not tracked.

CartDraft

key
String

User-defined unique identifier for the Cart.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
currency

Currency the Cart uses.

customerId
String

id of the Customer that the Cart belongs to.

customerEmail
String

Email address of the Customer that the Cart belongs to.

ResourceIdentifier to the Customer Group of the Customer that the Cart belongs to. Used for LineItem Price selection.

It is automatically set if the Customer referenced in customerId belongs to a Customer Group. It can also be set explicitly when no customerId is present.

anonymousId
String

Anonymous session associated with the Cart.

ResourceIdentifier to the Business Unit the Cart should belong to. When the customerId of the Cart is also set, the Customer must be an Associate of the Business Unit.

ResourceIdentifier to the Store the Cart should belong to. Once set, it cannot be updated.

lineItems
Array of LineItemDraft

Line Items to add to the Cart.

customLineItems

Custom Line Items to add to the Cart.

taxMode

Determines how Tax Rates are set.

Default: Platform
externalTaxRateForShippingMethod

External Tax Rate for the shippingMethod if the Cart has External TaxMode.

taxRoundingMode

Determines how monetary values are rounded when calculating taxes for taxedPrice.

Default: HalfEven
taxCalculationMode

Determines how taxes are calculated for taxedPrice.

Default: LineItemLevel
inventoryMode

Determines how stock quantities are tracked for Line Items in the Cart.

Default: None
billingAddress

Billing address associated with the Cart.

shippingAddress

Shipping address for a Cart with Single ShippingMode. Determines eligible ShippingMethod rates and Tax Rates of Line Items. Must be one of the itemShippingAddresses when that field is also provided.

Shipping Method for a Cart with Single ShippingMode. If the referenced ShippingMethod has a predicate that does not match the Cart, an InvalidOperation error is returned when creating a Cart.

shippingRateInput

Used as an input to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

shippingMode
  • If set to Single, only a single Shipping Method can be added to the Cart.
  • If set to Multiple, multiple Shipping Methods can be added to the Cart.
Default: Single
customShipping

Custom Shipping Methods for a Cart with Multiple ShippingMode.

shipping
Array of ShippingDraft

Shipping Methods for a Cart with Multiple ShippingMode.

itemShippingAddresses
Array of BaseAddress

Multiple shipping addresses of the Cart. Each address must contain a key that is unique in this Cart. The keys are used by LineItems to reference these addresses under their shippingDetails.

For Carts with Single ShippingMode: eligible Shipping Methods or applicable Tax Rates are determined by the address shippingAddress, and not itemShippingAddresses.

discountCodes
Array of String

code of the existing DiscountCodes to add to the Cart.

country

Used for LineItem Price selection. If used for Create Cart in Store, the provided country must be one of the Store's countries.

locale

Languages of the Cart. Can only contain languages supported by the Project.

origin

Indicates how the Cart was created.

Default: Customer
deleteDaysAfterLastModification
Int

Number of days after which an active Cart is deleted since its last modification. If not provided, the default value for this field configured in Project settings is assigned.

Create a ChangeSubscription for Carts to receive a ResourceDeletedDeliveryPayload upon deletion of the Cart.

custom

Custom Fields for the Cart.

CartPagedQueryResponse

PagedQueryResult with results containing an array of Cart.

limit
Int
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 withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of Cart

Carts matching the query.

CartReference

id
String

Unique identifier of the referenced Cart.

typeId
String
"cart"

References a Cart.

obj
Cart

Contains the representation of the expanded Cart. Only present in responses to requests with Reference Expansion for Carts.

CartResourceIdentifier

ResourceIdentifier to a Cart. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id
String

Unique identifier of the referenced Cart. Required if key is absent.

key
String

User-defined unique identifier of the referenced Cart. Required if id is absent.

typeId
String
"cart"

References a Cart.

ReplicaCartDraft

Used for replicating an existing Cart or Order.

key
String

User-defined unique identifier for the Cart.

reference
Union

Reference to a Cart or Order that is replicated.

LineItemMode

Indicates how a Line Item is added to a Cart.

Standard

The Line Item is added during Cart creation or using the Add LineItem update action. The Line Item quantity can be changed without restriction.

GiftLineItem

The Line Item is added automatically by a Cart Discount with CartDiscountValueGiftLineItem.

The quantity cannot be increased, and it won't be merged when the same Line Item is added to the Cart. If the gift is removed, an entry is added to the refusedGifts array and the discount won't be applied to the Cart. The price cannot be changed externally.

All other updates, such as the ones related to Custom Fields, can be used.

LineItemPriceMode

This mode indicates how the price is set for the Line Item.

Platform

The price is selected from the Product Variant. This is the default mode.

ExternalPrice

The Line Item price is set externally. Cart Discounts can apply to Line Items with this price mode. All update actions that change the quantity of a Line Item with this price mode require the externalPrice field to be given.

ExternalTotal

The Line Item price with the total is set externally. Cart Discounts are deactivated for Line Items with this price mode. Although a Line Item with this price mode has both price and totalPrice set externally, only totalPrice is used to calculate the total price of a Cart. All update actions that change the quantity of a Line Item with this price mode can set the new price with the externalTotal field. If the externalTotal field is not given in the update actions, the external price is unset and the price mode is set to Platform.

CustomLineItemPriceMode

Determines if Cart Discounts can be applied to a Custom Line Item in the Cart.

Standard

Allows application of Cart Discounts for the Custom Line Item.

This is the default mode for backwards compatibility.

External

Deactivates application of Cart Discounts for the Custom Line Item despite a matching CartDiscountCustomLineItemsTarget.

RoundingMode

Determines how monetary values are rounded.

HalfEven

Round half to even

Default mode for a new Cart.

HalfUp

Round half up

HalfDown

Round half down

The following example shows how decimal values are rounded:

Value to roundHalfUpHalfDownHalfEven
23.5242324
24.5252424
25.5262526

TaxCalculationMode

Determines in which Tax calculation mode taxed prices are calculated.

LineItemLevel

Taxes are calculated after the unit price is multiplied by the quantity. This is the default mode.

For example, ($1.08 * 3 = $3.24) * 1.19 = $3.8556 -> $3.86 rounded

UnitPriceLevel

Taxes are calculated on the unit price before multiplying by the quantity.

For example, ($1.08 * 1.19 = $1.2852 -> $1.29 rounded) * 3 = $3.87

The combination of UnitPriceLevel and ExternalTotal LineItemPriceMode is not supported. Requests using this combination will be rejected with an InvalidOperation error.

TaxMode

Indicates how taxes are set on the Cart.

Platform

Tax Rates are selected automatically from the TaxCategories based on the Cart shippingAddress. This is the default tax mode for a new Cart.

totalNet, totalGross, and taxPortions fields are calculated based on the taxRoundingMode.

External

Tax Rates are set externally per ExternalTaxRateDraft. A Cart can be ordered only if all Line Items, Custom Line Items, and the Shipping Method have an external Tax Rate set.

totalNet, totalGross, and taxPortions fields are calculated based on the taxRoundingMode.

ExternalAmount

Tax amounts, Tax Rates, and tax portions are set externally per ExternalTaxAmountDraft. A Cart can be ordered only if the Cart and all Line Items, Custom Line Items, and the Shipping Method have an external tax amount and rate set.

Price-specific update actions on Carts require external recalculation of the total gross price. Hence, the externalTaxAmount is removed in these cases and must be reset with Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount update actions.

Disabled

No taxes are added to the Cart.

Note that this tax mode cannot be set on the My Carts API.

InventoryMode

Indicates how Line Items in a Cart are tracked.

None

Adding and ordering items from a Cart are independent of the Inventory with no inventory checks or modifications.

This is the default mode.

TrackOnly

Orders are tracked on the Inventory, and ordering a LineItem deducts the available quantity on the respective InventoryEntry.

An Order can be created even if the Line Item quantity is zero or negative, but if no matching Inventory Entry exists for the Line Item, an OutOfStock error is returned.

ReserveOnOrder

Line Items in a Cart are only reserved for the duration of the ordering transaction. If a Line Item is not available when creating an Order, an OutOfStock error is returned. This is because the InventoryEntry availableQuantity is insufficient (but is still updated) for the ordered Line Item quantity.

However, an Order can be created if the InventoryEntry restockableInDays is set (including 0).

ShippingMode

Single

Cart can contain only a single Shipping Method. This is the default mode for backwards compatibilty.

Multiple

Cart can contain multiple Shipping Methods.

CartState

Indicates the current status of a Cart.

Active

The default state where a Cart can be updated and ordered.

Merged

An anonymous Cart was merged into a Customer's Cart on sign-in, and no further operations are allowed on the Cart.

Ordered

A Cart was ordered, and no further operations are allowed on the Cart.

Frozen

A Cart is frozen. Update actions that can change the price of (Custom) Line Items are not allowed.

CartOrigin

Indicates who created the Cart.

Customer

Cart was created by a Customer.

This is the default value.

Merchant

Cart was created by a merchant on behalf of a Customer.

Quote

Cart was created as part of a Quote.

LineItem

The representation of a Line Item in a Cart or in an Order.

id
String

Unique identifier of the LineItem.

key
String

User-defined unique identifier of the LineItem.

productId
String

id of the Product the Line Item is based on.

productKey
String

key of the Product.

This field is only present on:

  • Line Items in a Cart when the key is available on that specific Product at the time the LineItem was created or updated on the Cart.
  • Line Items in an Order when the key is available on the specific Product at the time the Order was created from the Cart.

Present on resources created or updated after 3 December 2021.

name

Name of the Product.

productSlug

slug of the current version of the Product. Updated automatically if the slug changes. Empty if the Product has been deleted. The productSlug field of LineItem is not expanded when using Reference Expansion.

productType

Product Type of the Product.

variant

Holds the data of the Product Variant added to the Cart.

The data is saved at the time the Product Variant is added to the Cart and is not updated automatically when Product Variant data changes. Must be updated using the Recalculate update action.

price

Price of a Line Item selected from the Product Variant according to the Product priceMode. If the priceMode is Embedded ProductPriceMode and the variant field hasn't been updated, the price may not correspond to a price in variant.prices.

quantity
Int

Number of Line Items of the given Product Variant present in the Cart or Order.

Default: 1
totalPrice

Total price of this Line Item equalling price multiplied by quantity. If the Line Item is discounted, the total price is the discountedPricePerQuantity multiplied by quantity. Includes taxes if the TaxRate includedInPrice is true.

discountedPricePerQuantity

Discounted price of a single quantity of the Line Item.

taxedPrice

Automatically set after taxRate is set.

taxedPricePortions
Array of MethodTaxedPrice

Total taxed prices based on the quantity of Line Item assigned to each Shipping Method. Only applicable for Carts with Multiple ShippingMode. Automatically set after perMethodTaxRate is set.

state
Array of ItemState

State of the Line Item in the Cart or the Order.

taxRate
  • For a Cart with Platform TaxMode, the taxRate of Line Items is set automatically once a shipping address is set. The rate is based on the TaxCategory that applies for the shipping address.
  • For a Cart with External TaxMode, the taxRate of Line Items can be set using ExternalTaxRateDraft.
perMethodTaxRate
Array of MethodTaxRate

Tax Rate per Shipping Method for a Cart with Multiple ShippingMode. For a Cart with Platform TaxMode it is automatically set after the Shipping Method is added. For a Cart with External TaxMode, the Tax Rate must be set with ExternalTaxRateDraft.

supplyChannel

Identifies Inventory entries that are reserved. The referenced Channel has the InventorySupply ChannelRoleEnum.

distributionChannel

Used to select a Product Price. The referenced Channel has the ProductDistribution ChannelRoleEnum.

priceMode

Indicates how the Price for the Line Item is set.

lineItemMode

Indicates how the Line Item is added to the Cart.

Default: Standard
inventoryMode

Inventory mode specific to this Line Item only, and valid for the entire quantity of the Line Item. Only present if the inventory mode is different from the inventoryMode specified on the Cart.

shippingDetails

Container for Line Item-specific addresses.

addedAt

Date and time (UTC) the Line Item was added to the Cart.

custom

Custom Fields of the Line Item.

lastModifiedAt

Date and time (UTC) the Line Item was last updated.

LineItemDraft

For Product Variant identification, either the productId and variantId, or sku must be provided.

key
String

User-defined unique identifier of the LineItem.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
productId
String

id of a published Product.

variantId
Int

id of the ProductVariant in the Product. If not provided, the Master Variant is used.

sku
String

sku of the ProductVariant.

quantity
Int

Quantity of the Product Variant to add to the Cart.

Default: 1
addedAt

Date and time (UTC) the Product Variant is added to the Cart. If not set, it defaults to the current date and time.

Optional for backwards compatibility reasons.

distributionChannel

Used to select a Product Price. The referenced Channel must have the ProductDistribution ChannelRoleEnum.

If the Cart is bound to a Store with distributionChannels set, the Channel must match one of the Store's distribution channels.

supplyChannel

Used to identify Inventory entries that must be reserved. The referenced Channel must have the InventorySupply ChannelRoleEnum.

externalPrice

Sets the LineItem price value, and the priceMode to ExternalPrice LineItemPriceMode.

externalTotalPrice

Sets the LineItem price and totalPrice values, and the priceMode to ExternalTotal LineItemPriceMode.

externalTaxRate

Sets the external Tax Rate for the Line Item, if the Cart has the External TaxMode.

perMethodExternalTaxRate

Sets the external Tax Rates for individual Shipping Methods, if the Cart has the External TaxMode and Multiple ShippingMode.

inventoryMode

Inventory mode specific to the Line Item only, and valid for the entire quantity of the Line Item. Set only if the inventory mode should be different from the inventoryMode specified on the Cart.

shippingDetails

Container for Line Item-specific addresses.

custom

Custom Fields for the Line Item.

CustomLineItem

A generic item that can be added to the Cart but is not bound to a Product that can be used for discounts (negative money), vouchers, complex cart rules, additional services, or fees. You control the lifecycle of this item.

id
String

Unique identifier of the Custom Line Item.

key
String

User-defined unique identifier of the Custom Line Item.

name

Name of the Custom Line Item.

money

Money value of the Custom Line Item.

taxedPrice

Automatically set after the taxRate is set.

taxedPricePortions
Array of MethodTaxedPrice

Total taxed prices based on the quantity of the Custom Line Item assigned to each Shipping Method. Only applicable for Carts with Multiple ShippingMode. Automatically set after perMethodTaxRate is set.

totalPrice

Total price of the Custom Line Item (money multiplied by quantity). If the Custom Line Item is discounted, the total price is discountedPricePerQuantity multiplied by quantity.

Includes taxes if the TaxRate includedInPrice is true.

slug
String

User-defined identifier used in a deep-link URL for the Custom Line Item. It matches the pattern [a-zA-Z0-9_-]{2,256}.

quantity
Int

Number of Custom Line Items in the Cart or Order.

Default: 1
state
Array of ItemState

State of the Custom Line Item in the Cart or Order.

taxCategory

Used to select a Tax Rate when a Cart has the Platform TaxMode.

taxRate
  • For a Cart with Platform TaxMode, the taxRate of Custom Line Items is set automatically once a shipping address is set. The rate is based on the TaxCategory that applies for the shipping address.
  • For a Cart with External TaxMode, the taxRate of Custom Line Items can be set using ExternalTaxRateDraft.
perMethodTaxRate
Array of MethodTaxRate

Tax Rate per Shipping Method for a Cart with Multiple ShippingMode. For a Cart with Platform TaxMode it is automatically set after the Shipping Method is added. For a Cart with External TaxMode, the Tax Rate must be set with ExternalTaxRateDraft.

discountedPricePerQuantity

Discounted price of a single quantity of the Custom Line Item.

shippingDetails

Container for Custom Line Item-specific addresses.

Indicates whether Cart Discounts with a matching CartDiscountCustomLineItemsTarget are applied to the Custom Line Item.

custom

Custom Fields of the Custom Line Item.

CustomLineItemDraft

key
String

User-defined unique identifier of the Custom Line Item.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
name

Name of the Custom Line Item.

quantity
Int

Number of Custom Line Items to add to the Cart.

Default: 1
money

Money value of the Custom Line Item. The value can be negative.

slug
String

User-defined identifier used in a deep-link URL for the Custom Line Item. It must match the pattern [a-zA-Z0-9_-]{2,256}.

Used to select a Tax Rate when a Cart has the Platform TaxMode. This field is required for Platform TaxMode.

externalTaxRate

External Tax Rate for the Custom Line Item if the Cart has the External TaxMode.

shippingDetails

Container for Custom Line Item-specific addresses.

  • If Standard, Cart Discounts with a matching CartDiscountCustomLineItemsTarget are applied to the Custom Line Item.
  • If External, Cart Discounts are not considered on the Custom Line Item.
Default: Standard
custom

Custom Fields for the Custom Line Item.

TaxedPrice

totalNet

Total net price of the Cart or Order.

totalGross

Total gross price of the Cart or Order.

taxPortions
Array of TaxPortion

Taxable portions added to the total net price.

Calculated from the TaxRates.

totalTax

Total tax applicable for the Cart or Order.

Automatically calculated as the difference between the totalGross and totalNet values.

TaxedItemPrice

totalNet

Total net amount of the Line Item or Custom Line Item.

totalGross

Total gross amount of the Line Item or Custom Line Item.

totalTax

Total tax applicable for the Line Item or Custom Line Item. Automatically calculated as the difference between the totalGross and totalNet values.

TaxPortion

The tax portions are calculated from the TaxRates. If a Tax Rate has SubRates, they are used and can be identified by name. Tax portions from Line Items with the same rate and name are accumulated to the same tax portion.

name
String

Name of the tax portion.

rate
Float

A number in the range 0-1.

Maximum: 1
amount

Money value of the tax portion.

TaxPortionDraft

Represents the portions that sum up to the totalGross field of a TaxedPrice.

The portions are calculated from the TaxRates. If a Tax Rate has SubRates, they are used and can be identified by name. Tax portions from Line Items with the same rate and name will be accumulated to the same tax portion.

name
String

Name of the tax portion.

rate
Float

A number in the range 0-1.

Maximum: 1
amount

Money value for the tax portion.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.

name
String

Name of the Tax Rate.

amount
Float

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
Maximum: 1
includedInPrice
Boolean
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false
country

Country for which the tax applies.

state
String

State within the specified country.

subRates
Array of SubRate

For countries (such as the US) where the total tax is a combination of multiple taxes (such as state and local taxes). The total of all subrates must equal the TaxRate amount.

ExternalTaxAmountDraft

totalGross

Total gross amount (totalNet + taxPortions) of the Line Item or Custom Line Item.

Tax Rates and subrates of states and countries.

Changes on the Cart or OrderEdit that have a financial impact invalidate the previously set total gross price. For example, when a Cart Discount reduces the Line Item price, the previously set total gross price becomes invalid and the recalculated total gross price must be set again with an ExternalTaxAmountDraft by another update action.

ExternalLineItemTotalPrice

price

Price of the Line Item.

totalPrice

Total price of the Line Item.

MethodExternalTaxRateDraft

shippingMethodKey
String

User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.

External Tax Rate for the Shipping Method, if the Cart has External TaxMode.

MethodTaxRate

shippingMethodKey
String

User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.

taxRate

Tax Rate for the Shipping Method.

MethodTaxedPrice

shippingMethodKey
String

User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.

taxedPrice

Total taxed price based on the quantity of the Line Item or Custom Line Item assigned to the Shipping Method identified by shippingMethodKey.

DiscountedLineItemPriceForQuantity

quantity
Int

Number of Line Items or Custom Line Items in the Cart.

discountedPrice

Discounted price of the Line Item or Custom Line Item.

DiscountedLineItemPrice

value

Money value of the discounted Line Item or Custom Line Item.

includedDiscounts

Discount applicable on the Line Item or Custom Line Item.

DiscountedLineItemPortion

discount

A CartDiscountReference or DirectDiscountReference of the applicable discount on the Line Item.

discountedAmount

Money value of the applicable discount.

DiscountedLineItemPortionDraft

discount

A CartDiscountReference or DirectDiscountReference for the discount applicable on the Line Item.

discountedAmount

Money value for the discount applicable.

DiscountOnTotalPrice

discountedAmount

Money value of the discount on the total price of the Cart or Order.

includedDiscounts

Discounts that impact the total price of the Cart or Order.

discountedNetAmount

Money value of the discount on the total net price of the Cart or Order. Present only when taxedPrice of the Cart or Order exists.

discountedGrossAmount

Money value of the discount on the total gross price of the Cart or Order. Present only when taxedPrice of the Cart or Order exists.

DiscountedTotalPricePortion

discount

Cart Discount related to the discounted price.

discountedAmount

Money value of the discount.

DirectDiscount

Represents a CartDiscount that is only associated with a single Cart or Order.

id
String

Unique identifier of the Direct Discount.

Effect of the Discount on the Cart.

target

Segment of the Cart that is discounted.

Empty when the value is set to giftLineItem.

DirectDiscountDraft

Represents a CartDiscount that can only be associated with a single Cart or Order.

Direct Discounts are always active and valid, and have the default Stacking StackingMode. They apply in the order in which they are listed in the directDiscounts array of Carts or Orders, and do not have a sorting order like Cart Discounts.

If a Direct Discount is present, any matching Cart Discounts in the Project are ignored. Additionally, a Cart or Order supports either Discount Codes or Direct Discounts at the same time.

Defines the effect the Discount will have.

target

Defines what segment of the Cart will be discounted.

If value is set to giftLineItem, this must not be set.

Example: json
{
"value": {
"type": "relative",
"permyriad": 1000
},
"target": {
"type": "lineItems",
"predicate": "1=1"
}
}

DirectDiscountReference

id
String

Unique identifier of the referenced DirectDiscount.

typeId
String
"direct-discount"

References a DirectDiscount.

DiscountCodeInfo

discountCode

Discount Code associated with the Cart or Order.

Indicates the state of the Discount Code applied to the Cart or Order.

DiscountCodeState

Indicates the state of a Discount Code in a Cart.

If an Order is created from a Cart with a state other than MatchesCart, a DiscountCodeNonApplicable error is returned.

NotActive

The Discount Code is not active or does not contain any active Cart Discounts.

NotValid

The Discount Code is not valid or does not contain any valid Cart Discounts. Validity is determined by the CartDiscount validFrom and validUntil dates.

DoesNotMatchCart

The Discount Code is active and contains at least one active and valid Cart Discount. The DiscountCode cartPredicate does not match the Cart or the contained active discount's cart predicates do no match the Cart.

MatchesCart

The Discount Code is active and contains at least one active and valid Cart Discount. The DiscountCode cartPredicate matches the Cart and at least one of the contained active discount's cart predicates matches the Cart.

MaxApplicationReached

The maxApplications or maxApplicationsPerCustomer for a DiscountCode has been reached.

ApplicationStoppedByPreviousDiscount

The Discount Code is active and no discounts are applied after a discount with StopAfterThisDiscount StackingMode is defined.

ShippingInfo

shippingMethodName
String

Name of the Shipping Method.

Determined based on the ShippingRate and its tiered prices, and either the sum of LineItem prices or the shippingRateInput field.

shippingRate

Used to determine the price.

taxedPrice

Automatically set after the taxRate is set.

taxRate

Automatically set in the Platform TaxMode after the shipping address is set.

For the External TaxMode the Tax Rate must be set explicitly with the ExternalTaxRateDraft.

taxCategory

Used to select a Tax Rate when a Cart has the Platform TaxMode.

shippingMethod

Not set if a custom Shipping Method is used.

deliveries
Array of Delivery

Information on how items are delivered to customers.

discountedPrice

Discounted price of the Shipping Method.

shippingMethodState

Indicates whether the ShippingMethod referenced in this ShippingInfo is allowed for the Cart.

CustomShippingDraft

key
String

User-defined unique identifier of the custom Shipping Method in the Cart with Multiple ShippingMode.

shippingMethodName
String

Name of the custom Shipping Method.

shippingAddress

Determines the shipping rate and Tax Rate of the associated Line Items.

shippingRate

Determines the shipping price.

shippingRateInput

Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

Tax Category used to determine a shipping Tax Rate if the Cart has the Platform TaxMode.

externalTaxRate

Tax Rate used to tax a shipping expense if the Cart has the External TaxMode.

deliveries
Array of DeliveryDraft

Deliveries to be shipped with the custom Shipping Method.

custom

Custom Fields for the custom Shipping Method.

Shipping

shippingKey
String

User-defined unique identifier of the Shipping in a Cart with Multiple ShippingMode.

shippingInfo

Automatically set when the Shipping Method is added.

shippingAddress

Determines the shipping rates and Tax Rates of associated Line Items.

shippingRateInput

Used as an input to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

shippingCustomFields

Custom Fields of Shipping with Multiple ShippingMode.

ShippingDraft

Wraps all shipping-related information (such as address, rate, deliveries) per Shipping Method for Carts with multiple Shipping Methods.

key
String

User-defined unique identifier for the Shipping in a Cart with Multiple ShippingMode.

shippingMethod

Shipping Methods added to the Cart with Multiple ShippingMode.

shippingAddress

Determines the shipping rate and Tax Rate of the associated Line Items.

shippingRateInput

Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

externalTaxRate

Tax Rate used for taxing a shipping expense if the Cart has the External TaxMode.

deliveries
Array of DeliveryDraft

Deliveries to be shipped with the Shipping Method.

custom

Custom Fields for Shipping.

ShippingMethodState

Determines whether a ShippingMethod is allowed for a Cart.

DoesNotMatchCart

The ShippingMethod predicate does not match the Cart.

Ordering this Cart returns an ShippingMethodDoesNotMatchCart error.

MatchesCart

Either the ShippingMethod predicate matches the Cart or there is no predicate defined.

ShippingRateInput

Generic type for the input used to select a ShippingRatePriceTier. The specific data type depends on the shippingRateInputType.type configured in the Project:

ClassificationShippingRateInput

key
String

Key of the value used as a programmatic identifier.

type
String
"Classification"
label

Descriptive localized label of the value.

ScoreShippingRateInput

type
String
"Score"
score
Int

Abstract value for categorizing a Cart.

ShippingRateInputDraft

Generic draft type for setting the input to select a ShippingRatePriceTier. The specific data type to use depends on the shippingRateInputType.type configured in the Project:

ClassificationShippingRateInputDraft

key
String

Key of the value used as a programmatic identifier.

type
String
"Classification"

ScoreShippingRateInputDraft

type
String
"Score"
score
Int

Abstract value for categorizing a Cart.

ItemShippingDetails

targets
Array of ItemShippingTarget

Holds information on the quantity of Line Items or Custom Line Items and the address it is shipped.

valid
Boolean
  • true if the quantity of Line Items or Custom Line Items is equal to the sum of sub-quantities defined in targets.
  • false if the quantity of Line Items or Custom Line Items is not equal to the sum of sub-quantities defined in targets. Ordering a Cart when the value is false returns an InvalidItemShippingDetails error.

ItemShippingDetailsDraft

For order creation and updates, the sum of the targets must match the quantity of the Line Items or Custom Line Items.

targets
Array of ItemShippingTarget

Holds information on the quantity of Line Items or Custom Line Items and the address it is shipped.

If multiple shipping addresses are present for a Line Item or Custom Line Item, sub-quantities must be specified.

ItemShippingTarget

Determines the address (as a reference to an address in itemShippingAddresses) and the quantity shipped to the address.

If multiple shipping addresses are present for a Line Item or Custom Line Item, sub-quantities must be specified. An array of addresses and sub-quantities is stored per Line Item or Custom Line Item.

addressKey
String

Key of the address in the Cart itemShippingAddresses. Duplicate address keys are not allowed.

quantity
Int

Quantity of Line Items or Custom Line Items shipped to the address with the specified addressKey.

If a quantity is updated to 0 when defining ItemShippingDetailsDraft, the targets are removed from a Line Item or Custom Line Item in the resulting ItemShippingDetails.

shippingMethodKey
String

User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.

It connects Line Item or Custom Line Item quantities with individual Shipping Methods.

ItemState

quantity
Int

Number of Line Items or Custom Line Items in this State.

state

State of the Line Items or Custom Line Items in a custom workflow.

Get Cart

The following methods retrieve a Cart accessible globally in the Project. For retrieving Carts available in a Store only, use the Get Cart in Store methods instead.

Get Cart by ID

GET
https://api.{region}.commercetools.com/{projectKey}/carts/{id}

To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Get Cart by Key

GET
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}

To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Get Cart by Customer ID

GET
https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId}

Retrieves the recently modified active Cart of a Customer with CartOrigin Customer. If no active Cart exists, this method returns a ResourceNotFound error.

To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

customerId
String

customerId of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Get Cart in Store

The following methods retrieve a Cart from a specific Store. For retrieving Carts accessible globally in the Project, use the Get Cart methods instead.

Get Cart in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}

If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Get Cart in Store by Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}

If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Get Cart in Store by Customer ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId}

Retrieves the recently modified active Cart of a Customer with CartOrigin Customer. If no active Cart exists, this method returns a ResourceNotFound error.

If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

customerId
String

customerId of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Query Carts

GET
https://api.{region}.commercetools.com/{projectKey}/carts
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
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
offset
Int

Number of elements skipped.

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.

Response:
200CartPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CartPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"type": "Cart",
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2015-09-22T15:36:17.510Z",
"lastModifiedAt": "2015-09-22T15:41:55.816Z",
"lineItems": [
{
"id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name": {
"en": "SAPPHIRE"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "sapphire1421832124423"
},
"variant": {
"id": 1,
"sku": "sku_SAPPHIRE_variant1_1421832124423",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity": 2,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 2,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
},
{
"type": "Cart",
"id": "668e5783-73c8-4f2d-91f4-3c90b872c700",
"version": 3,
"createdAt": "2015-10-07T07:33:05.894Z",
"lastModifiedAt": "2015-10-07T07:33:06.070Z",
"lineItems": [
{
"id": "90dff06c-272e-47fa-b8de-923dce092474",
"productId": "7b1203f4-66c0-438c-9a30-f4fb6be79bdf",
"name": {
"de": "WB ATHLETIC PANZER",
"en": "WB ATHLETIC TANK"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "wb-athletic-tank1421832124574"
},
"variant": {
"id": 1,
"sku": "sku_WB_ATHLETIC_TANK_variant1_1421832124574",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/253265444_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"custom": {
"type": {
"typeId": "type",
"id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
},
"fields": {
"offer_name": "SuperMax"
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"country": "DE",
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
}
]
}

Query Carts in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts

Queries carts in a specific Store.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
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
offset
Int

Number of elements skipped.

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.

Response:
200CartPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CartPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"type": "Cart",
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2015-09-22T15:36:17.510Z",
"lastModifiedAt": "2015-09-22T15:41:55.816Z",
"lineItems": [
{
"id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name": {
"en": "SAPPHIRE"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "sapphire1421832124423"
},
"variant": {
"id": 1,
"sku": "sku_SAPPHIRE_variant1_1421832124423",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity": 2,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 2,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
},
{
"type": "Cart",
"id": "668e5783-73c8-4f2d-91f4-3c90b872c700",
"version": 3,
"createdAt": "2015-10-07T07:33:05.894Z",
"lastModifiedAt": "2015-10-07T07:33:06.070Z",
"lineItems": [
{
"id": "90dff06c-272e-47fa-b8de-923dce092474",
"productId": "7b1203f4-66c0-438c-9a30-f4fb6be79bdf",
"name": {
"de": "WB ATHLETIC PANZER",
"en": "WB ATHLETIC TANK"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "wb-athletic-tank1421832124574"
},
"variant": {
"id": 1,
"sku": "sku_WB_ATHLETIC_TANK_variant1_1421832124574",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/253265444_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"custom": {
"type": {
"typeId": "type",
"id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
},
"fields": {
"offer_name": "SuperMax"
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"country": "DE",
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
}
]
}

Check if Cart exists

Check if Cart exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/carts/{id}

Checks if a Cart exists for a given id. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}

Checks if a Cart exists for a given key. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists by Customer ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId}

Checks if a Cart of a Customer exists. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

customerId
String

customerId of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/carts

Checks if a Cart exists for a given Query Predicate. Returns a 200 OK status if any Carts match the Query Predicate, or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists in Store

Check if Cart exists in Store by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}

Checks if a Cart exists for a given id. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists in Store by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}

Checks if a Cart exists for a given key. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists in Store by Customer ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId}

Checks if a Cart of a Customer exists. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

customerId
String

customerId of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists in Store by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts

Checks if a Cart exists for a given Query Predicate. Returns a 200 OK status if any Carts match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Cart

POST
https://api.{region}.commercetools.com/{projectKey}/carts

Creating a Cart fails with an InvalidOperation error if the ShippingMethod referenced in the CartDraft has a predicate that does not match the Cart.

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:CartDraftasapplication/json
Response:
201Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"currency" : "EUR"
}
DATA
201 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Create Cart in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts

Creates a Cart in the Store specified by storeKey. When using this endpoint the Cart's store field is always set to the Store specified in the path parameter. If the referenced ShippingMethod in the CartDraft has a predicate that does not match, an InvalidOperation error is returned.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:CartDraftasapplication/json
Response:
201Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"currency" : "EUR"
}
DATA
201 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Replicate Cart

POST
https://api.{region}.commercetools.com/{projectKey}/carts/replicate

Creates a new Cart by replicating an existing Cart or Order. Can be useful in cases where a customer wants to cancel a recent order to make some changes or reorder a previous order.

The replicated Cart preserves Customer information, Line Items and Custom Line Items, Custom Fields, Discount Codes, and other settings of the Cart or Order. If the Line Items become invalid, for example, due to removed Products or Prices, they are removed from the new Cart. If the Customer switches to another Customer Group, the new Cart is updated with the new value. It has up-to-date Tax Rates, Prices, and Line Item product data and is in Active CartState.

The new Cart does not contain Payments or Deliveries. The State of Line Items and Custom Line Items is reset to initial.

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Request Body:ReplicaCartDraftasapplication/json
Response:
201Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/carts/replicate -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"reference" : {
"id" : "74dcac8b-0c67-4f37-b693-3acd33e3c457",
"typeId" : "cart"
}
}
DATA
201 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Replicate Cart in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/replicate

Creates a new Cart by replicating an existing Cart or Order. Can be useful in cases where a customer wants to cancel a recent order to make some changes or reorder a previous order.

The replicated Cart preserves Customer information, Line Items and Custom Line Items, Custom Fields, Discount Codes, and other settings of the Cart or Order. If the Line Items become invalid, for example, due to removed Products or Prices, they are removed from the new Cart. If the Customer switches to another Customer Group, the new Cart is updated with the new value. It has up-to-date Tax Rates, Prices, and Line Item product data and is in Active CartState.

The new Cart does not contain payments or deliveries. The State of Line Items and Custom Line Items is reset to initial.

OAuth 2.0 Scopes:
manage_orders:{projectKey}:{storeKey} , manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Request Body:ReplicaCartDraftasapplication/json
Response:
201Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/replicate -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"reference" : {
"id" : "74dcac8b-0c67-4f37-b693-3acd33e3c457",
"typeId" : "cart"
}
}
DATA
201 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Update Cart

The following methods update a Cart accessible globally in the Project. For updating Carts available in a Store only, use the Update Cart in Store methods instead.

Calling these methods might lead to additional Cart updates not explicitly requested by update actions.

Update Cart by ID

POST
https://api.{region}.commercetools.com/{projectKey}/carts/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of CartUpdateAction

Update actions to be performed on the Cart.

Response:
200Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Update Cart by Key

POST
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of CartUpdateAction

Update actions to be performed on the Cart.

Response:
200Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Update Cart in Store

The following methods update a Cart from a specific Store. For updating Carts accessible globally in the Project, use the Update Cart methods instead.

Calling these methods might lead to additional Cart updates not explicitly requested by update actions.

Update Cart in Store by ID

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}

Updates a Cart in the Store specified by storeKey. If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of CartUpdateAction

Update actions to be performed on the Cart.

Response:
200Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Update Cart in Store by Key

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}

If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of CartUpdateAction

Update actions to be performed on the Cart.

Response:
200Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Update actions

on Cart

Set Key

action
String
"setKey"
key
String

Value to set. If empty, any existing key will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action": "setKey",
"key": "myNewKey"
}

Set Customer ID

Setting the Cart's customerId can lead to updates on all its LineItem prices.

If the Customer with the specified id cannot be found, this update action returns a ReferencedResourceNotFound error.

action
String
"setCustomerId"
customerId
String

id of an existing Customer. If empty, any value is removed.

Example: json
{
"action": "setCustomerId",
"customerId": "{{customer-id}}"
}

Set Customer Email

action
String
"setCustomerEmail"
email
String

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

Example: json
{
"action": "setCustomerEmail",
"email": "email@example.com"
}

Set Customer Group

This update action can only be used if a Customer is not assigned to a Cart. If a Customer is already assigned, the Cart has the same Customer Group as the assigned Customer.

Setting the Customer Group also updates the LineItem prices according to the Customer Group.

action
String
"setCustomerGroup"

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

Example: json
{
"action": "setCustomerGroup",
"customerGroup": {
"id": "{{customer-group-id}}",
"typeId": "customer-group"
}
}

Set Anonymous ID

action
String
"setAnonymousId"
anonymousId
String

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

Example: json
{
"action": "setAnonymousId",
"anonymousId": "idString"
}

Set Business Unit

Updates the Business Unit on the Cart. The Cart must have an existing Business Unit assigned already.

action
String
"setBusinessUnit"

New Business Unit to assign to the Cart, which must have access to the Store that is set on the Cart.

Example: json
{
"action": "setBusinessUnit",
"businessUnit": {
"key": "{{business-unit-key}}",
"typeId": "business-unit"
}
}

Add LineItem

If the Cart contains a LineItem for a Product Variant with the same LineItemMode, Custom Fields, supply and distribution channel, then only the quantity of the existing Line Item is increased. If LineItem shippingDetails is set, it is merged. All addresses will be present afterwards and, for address keys present in both shipping details, the quantity will be summed up. A new Line Item is added when the externalPrice or externalTotalPrice is set in this update action. The LineItem price is set as described in LineItem Price selection.

If the Tax Rate is not set, a MissingTaxRateForCountry error is returned.

If the Line Items do not have a Price according to the Product priceMode value for a selected currency and/or country, Customer Group, or Channel, a MatchingPriceNotFound error is returned.

action
String
"addLineItem"
key
String

User-defined unique identifier of the LineItem.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
productId
String

id of the published Product.

Either the productId and variantId, or sku must be provided.

variantId
Int

id of the ProductVariant in the Product. If not provided, the Master Variant is used.

Either the productId and variantId, or sku must be provided.

sku
String

SKU of the ProductVariant.

Either the productId and variantId, or sku must be provided.

quantity
Int

Quantity of the Product Variant to add to the Cart.

Default: 1
addedAt

Date and time (UTC) the Product Variant is added to the Cart. If not set, it defaults to the current date and time.

Optional for backwards compatibility reasons.

distributionChannel

Used to select a Product Price. The Channel must have the ProductDistribution ChannelRoleEnum. If the Cart is bound to a Store with distributionChannels set, the Channel must match one of the Store's distribution channels.

supplyChannel

Used to identify Inventory entries that must be reserved. The Channel must have the InventorySupply ChannelRoleEnum.

externalPrice

Sets the LineItem price value, and the priceMode to ExternalPrice LineItemPriceMode.

externalTotalPrice

Sets the LineItem price and totalPrice values, and the priceMode to ExternalTotal LineItemPriceMode.

externalTaxRate

External Tax Rate for the Line Item, if the Cart has the External TaxMode.

perMethodExternalTaxRate

Sets the external Tax Rates for individual Shipping Methods, if the Cart has the External TaxMode and Multiple ShippingMode.

inventoryMode

Inventory mode specific to the Line Item only, and valid for the entire quantity of the Line Item. Set only if the inventory mode should be different from the inventoryMode specified on the Cart.

shippingDetails

Container for Line Item-specific addresses.

custom

Custom Fields for the Line Item.

Example: json
{
"action": "addLineItem",
"productId": "{{product-id}}",
"variantId": 2,
"quantity": 1,
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
},
"distributionChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
},
"externalTaxRate": {
"name": "StandardExternalTaxRate",
"amount": 0.19,
"country": "DE",
"state": "Bavaria"
},
"shippingDetails": {
"targets": [
{
"addressKey": "AddressKeyStringFromAddress",
"quantity": 2
}
]
}
}

Remove LineItem

The LineItem price is updated as described in LineItem Price selection.

action
String
"removeLineItem"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

quantity
Int

Amount to subtract from the LineItem's quantity. If absent, the LineItem is removed from the Cart.

externalPrice

Sets the LineItem price to the given value when decreasing the quantity of a Line Item with the ExternalPrice LineItemPriceMode.

externalTotalPrice

Sets the LineItem price and totalPrice to the given value when decreasing the quantity of a Line Item with the ExternalTotal LineItemPriceMode.

shippingDetailsToRemove

Container for Line Item-specific addresses to remove.

Example: json
{
"action": "removeLineItem",
"lineItemId": "{{lineItemId}}",
"quantity": 1,
"externalPrice": {
"currencyCode": "EUR",
"centAmount": 4000
},
"shippingDetailsToRemove": {
"targets": [
{
"addressKey": "AddressKeyStringFromAddress",
"quantity": 2
}
]
}
}

Add CustomLineItem

If the Cart already contains a CustomLineItem with the same slug, name, money, taxCategory, state, and Custom Fields, then only the quantity of the existing Custom Line Item is increased. If CustomLineItem shippingDetails are set, they are merged with the targets that already exist on the ItemShippingDetails of the Custom Line Item. In case of overlapping address keys the ItemShippingTarget quantity is summed up.

If the Cart already contains a Custom Line Item with the same slug that is otherwise not identical, an InvalidOperation error is returned.

If the Tax Rate is not set, a MissingTaxRateForCountry error is returned.

action
String
"addCustomLineItem"
key
String

User-defined unique identifier of the Custom Line Item.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
money

Money value of the Custom Line Item. The value can be negative.

name

Name of the Custom Line Item.

quantity
Int

Number of Custom Line Items to add to the Cart.

Default: 1
slug
String

User-defined identifier used in a deep-link URL for the Custom Line Item. It must match the pattern [a-zA-Z0-9_-]{2,256}.

Used to select a Tax Rate when a Cart has the Platform TaxMode.

If TaxMode is Platform, this field must not be empty.

externalTaxRate

An external Tax Rate can be set if the Cart has External TaxMode.

shippingDetails

Container for Custom Line Item-specific addresses.

  • If Standard, Cart Discounts with a matching CartDiscountCustomLineItemsTarget are applied to the Custom Line Item.
  • If External, Cart Discounts are not considered on the Custom Line Item.
Default: Standard
custom

Custom Fields for the Custom Line Item.

Example: json
{
"action": "addCustomLineItem",
"name": {
"en": "Name EN",
"de": "Name DE"
},
"quantity": 1,
"money": {
"currencyCode": "EUR",
"centAmount": 4200
},
"slug": "mySlug",
"taxCategory": {
"typeId": "tax-category",
"id": "{{tax-category-id}}"
}
}

Remove CustomLineItem

This update action does not support specifying quantities, unlike the Remove LineItem update action.

If shippingDetails must be partially removed, use the Change CustomLineItem Quantity update action.

action
String
"removeCustomLineItem"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

Example: json
{
"action": "removeCustomLineItem",
"customLineItemId": "{{customLineItemId}}"
}

Add Shopping List

Adds all LineItems of a ShoppingList to the Cart.

action
String
"addShoppingList"

Shopping List that contains the Line Items to be added.

distributionChannel

distributionChannel to set for all LineItems that are added to the Cart. The Channel must have the ProductDistribution ChannelRoleEnum.

supplyChannel

supplyChannel to set for all LineItems that are added to the Cart. The Channel must have the InventorySupply ChannelRoleEnum.

Example: json
{
"action": "addShoppingList",
"shoppingList": {
"id": "{{shopping-list-id}}",
"typeId": "shopping-list"
},
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
},
"distributionChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}

Set Cart Total Tax

This update action results in the taxedPrice field being added to the Cart when the ExternalAmount TaxMode is used.

action
String
"setCartTotalTax"
externalTotalGross

The Cart's total gross price becoming the totalGross field (totalNet + taxes) on the Cart's taxedPrice.

externalTaxPortions
Array of TaxPortionDraft

Set if the externalTotalGross price is a sum of portions with different tax rates.

Example: json
{
"action": "setCartTotalTax",
"externalTotalGross": {
"currencyCode": "EUR",
"centAmount": 10000
}
}

Change TaxMode

  • When External TaxMode is changed to Platform or Disabled, all previously set external Tax Rates are removed.
  • When set to Platform, Line Items, Custom Line Items, and Shipping Method require a Tax Category with a Tax Rate for the Cart's shippingAddress.
action
String
"changeTaxMode"
taxMode

The new TaxMode.

Example: json
{
"action": "changeTaxMode",
"taxMode": "Platform"
}

Change Tax RoundingMode

Changing the tax rounding mode leads to recalculation of taxes.

action
String
"changeTaxRoundingMode"
taxRoundingMode

New value to set.

Example: json
{
"action": "changeTaxRoundingMode",
"taxRoundingMode": "HalfUp"
}

Change TaxCalculationMode

Changing the tax calculation mode leads to recalculation of taxes.

action
String
"changeTaxCalculationMode"
taxCalculationMode

New value to set.

Example: json
{
"action": "changeTaxCalculationMode",
"taxCalculationMode": "LineItemLevel"
}

Add DiscountCode

Adds a DiscountCode to the Cart to activate the related Cart Discounts. Adding a Discount Code is only possible if no DirectDiscount has been applied to the Cart. Discount Codes can be added to frozen Carts, but their DiscountCodeState is then DoesNotMatchCart.

The maximum number of Discount Codes in a Cart is restricted by a limit.

Specific Error Code: MatchingPriceNotFound

action
String
"addDiscountCode"
code
String

code of a DiscountCode.

Example: json
{
"action": "addDiscountCode",
"code": "mydiscountcode"
}

Remove DiscountCode

action
String
"removeDiscountCode"
discountCode

Discount Code to remove from the Cart.

Example: json
{
"action": "removeDiscountCode",
"discountCode": {
"typeId": "discount-code",
"id": "{{discount-code-id}}"
}
}

Set DirectDiscounts

Adds a DirectDiscount, but only if no DiscountCode has been added to the Cart. Either a Discount Code or a Direct Discount can exist on a Cart at the same time.

action
String
"setDirectDiscounts"
discounts
  • If set, all existing Direct Discounts are replaced. The discounts apply in the order they are added to the list.
  • If empty, all existing Direct Discounts are removed and all affected prices on the Cart or Order are recalculated.
Example: json
{
"action": "setDirectDiscounts",
"discounts": [
{
"value": {
"type": "relative",
"permyriad": 1000
},
"target": {
"type": "lineItems",
"predicate": "1=1"
}
}
]
}

Add Payment

action
String
"addPayment"

Payment to add to the Cart. Must not be assigned to another Order or active Cart already.

Example: json
{
"action": "addPayment",
"payment": {
"id": "{{payment-id}}",
"typeId": "payment"
}
}

Remove Payment

action
String
"removePayment"

Payment to remove from the Cart.

Example: json
{
"action": "removePayment",
"payment": {
"id": "{{payment-id}}",
"typeId": "payment"
}
}

Set Billing Address

action
String
"setBillingAddress"
address

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

Example: json
{
"action": "setBillingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Set Shipping Address

Setting the shipping address also sets the TaxRate of Line Items and calculates the TaxedPrice.

If a matching price cannot be found for the given shipping address during Line Item Price selection, a MissingTaxRateForCountry error is returned.

If you want to allow shipping to states inside a country that are not explicitly covered by a TaxRate, set the countryTaxRateFallbackEnabled field to true in the CartsConfiguration by using the Change CountryTaxRateFallbackEnabled update action.

action
String
"setShippingAddress"
address

Value to set. If not set, the shipping address is unset, and the taxedPrice and taxRate are unset in all Line Items of the Cart.

Example: json
{
"action": "setShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Add ItemShippingAddress

Adds an address to a Cart when shipping to multiple addresses is desired.

action
String
"addItemShippingAddress"
address

Address to append to itemShippingAddresses.

The new Address must have a key that is unique across this Cart.

Example: json
{
"action": "addItemShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Remove ItemShippingAddress

An address can only be removed if it is not referenced in any ItemShippingTarget of the Cart.

action
String
"removeItemShippingAddress"
addressKey
String

key of the Address to remove from itemShippingAddresses.

Example: json
{
"action": "removeItemShippingAddress",
"addressKey": "{{addressKey}}"
}

Update ItemShippingAddress

Updates an address in itemShippingAddresses by keeping the Address key.

action
String
"updateItemShippingAddress"
address

The new Address with the same key as the Address it will replace.

Example: json
{
"action": "updateItemShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Add ShippingMethod

Adds a Shipping Method for a specified shipping address to a Cart with Multiple ShippingMode.

action
String
"addShippingMethod"
shippingKey
String

User-defined identifier for the Shipping that must be unique across the Cart with Multiple ShippingMode.

RecourceIdentifier to a ShippingMethod to add to the Cart with Multiple ShippingMode. If the referenced Shipping Method has a predicate that does not match the Cart, an InvalidOperation error is returned.

shippingAddress

Determines the shipping rate and Tax Rate of the Line Items.

shippingRateInput

Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

externalTaxRate

Tax Rate used to tax a shipping expense if the Cart has the External TaxMode.

deliveries
Array of DeliveryDraft

Deliveries to be shipped with the referenced Shipping Method.

custom

Custom Fields for the Shipping Method.

Example: json
{
"action": "addShippingMethod",
"shippingKey": "shippingMethodKey1",
"shippingMethod": {
"id": "{{shipping-method-id}}",
"typeId": "shipping-method"
},
"shippingAddress": {
"key": "exampleKey",
"streetName": "Example Street",
"streetNumber": "4711",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE"
},
"shippingRateInput": {
"type": "Classification",
"key": "shippingRateString"
},
"externalTaxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}

Remove ShippingMethod

Removes a Shipping Method from a Cart that has the Multiple ShippingMode.

action
String
"removeShippingMethod"
shippingKey
String

User-defined unique identifier of the Shipping Method to remove from the Cart.

Example: json
{
"action": "removeShippingMethod",
"shippingKey": "shippingMethodKey1"
}

Set ShippingMethod

To set the Cart's Shipping Method the Cart must have the Single ShippingMode and a shippingAddress.

action
String
"setShippingMethod"

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

If the referenced Shipping Method has a predicate that does not match the Cart, an InvalidOperation error is returned.

externalTaxRate

An external Tax Rate can be set if the Cart has the External TaxMode.

Example: json
{
"action": "setShippingMethod",
"shippingMethod": {
"id": "{{shipping-method-id}}",
"typeId": "shipping-method"
}
}

Add Custom ShippingMethod

To add a custom Shipping Method (independent of the ShippingMethods managed through the Shipping Methods API) to the Cart, it must have the Multiple ShippingMode.

action
String
"addCustomShippingMethod"
shippingKey
String

User-defined identifier for the custom Shipping Method that must be unique across the Cart with Multiple ShippingMode.

shippingMethodName
String

Name of the custom Shipping Method.

shippingAddress

Determines the shipping rate and Tax Rate of the associated Line Items.

shippingRate

Determines the shipping price.

shippingRateInput

Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

Tax Category used to determine a shipping Tax Rate if the Cart has the Platform TaxMode.

externalTaxRate

Tax Rate used to tax a shipping expense if the Cart has the External TaxMode.

deliveries
Array of DeliveryDraft

Deliveries to be shipped with the custom Shipping Method.

custom

Custom Fields for the custom Shipping Method.

Example: json
{
"action": "addCustomShippingMethod",
"shippingKey": "shippingMethodKey1",
"shippingMethodName": "oneOfCustomShippingMethods",
"shippingAddress": {
"key": "exampleKey",
"streetName": "Example Street",
"streetNumber": "4711",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE"
},
"shippingRate": {
"price": {
"currencyCode": "EUR",
"centAmount": 4200
}
},
"taxCategory": {
"id": "{{tax-category-id}}",
"typeId": "tax-category"
},
"deliveries": []
}

Set Custom ShippingMethod

To set the Cart's custom Shipping Method (independent of the ShippingMethods managed through the Shipping Methods API) the Cart must have the Single ShippingMode and a shippingAddress.

To unset a custom Shipping Method on a Cart, use the Set ShippingMethod update action without the shippingMethod field instead.

action
String
"setCustomShippingMethod"
shippingMethodName
String

Name of the custom Shipping Method.

shippingRate

Determines the shipping price.

Tax Category used to determine the Tax Rate when the Cart has the Platform TaxMode.

externalTaxRate

External Tax Rate for the shippingRate to be set if the Cart has the External TaxMode.

Example: json
{
"action": "setCustomShippingMethod",
"shippingMethodName": "myCustomShippingMethod",
"shippingRate": {
"price": {
"currencyCode": "EUR",
"centAmount": 4200
}
},
"taxCategory": {
"id": "{{tax-category-id}}",
"typeId": "tax-category"
}
}

Set ShippingRateInput

Input used to select a ShippingRatePriceTier. If no matching tier can be found, or the input is not set, the default price for the shipping rate is used.

action
String
"setShippingRateInput"
shippingRateInput

The data type of this field depends on the shippingRateInputType.type configured in the Project:

Example: json
{
"action": "setShippingRateInput",
"shippingRateInput": {
"type": "Classification",
"key": "shippingRateString"
}
}

Set Locale

action
String
"setLocale"
locale

Value to set. Must be one of the Project's languages. If empty, any existing value will be removed.

Example: json
{
"action": "setLocale",
"locale": "de-DE"
}

Set Country

Setting the country can lead to changes in the LineItem prices.

action
String
"setCountry"
country

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

If the Cart is bound to a store, the provided value must be included in the Store's countries. Otherwise a CountryNotConfiguredInStore error is returned.

Example: json
{
"action": "setCountry",
"country": "DE"
}

Set DeleteDaysAfterLastModification

Number of days after which a Cart with Active CartState is deleted since its last modification.

If a ChangeSubscription exists for Carts, a ResourceDeletedDeliveryPayload is sent.

action
String
"setDeleteDaysAfterLastModification"
deleteDaysAfterLastModification
Int

Value to set. If not provided, the default value for this field configured in Project settings is assigned.

Example: json
{
"action": "setDeleteDaysAfterLastModification",
"deleteDaysAfterLastModification": 90
}

Set Custom Type

action
String
"setCustomType"

Defines the Type that extends the Cart with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Cart.

fields

Sets the Custom Fields fields for the Cart.

Example: json
{
"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 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.

Example: json
{
"action": "setCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Recalculate

This update action does not set any Cart field in particular, but it triggers several Cart updates to bring prices and discounts to the latest state. Those can become stale over time when no Cart updates have been performed for a while and prices on related Products have changed in the meanwhile.

If the priceMode of the Product related to a Line Item is of Embedded ProductPriceMode, the updated price of that LineItem may not correspond to a Price in the variant.prices anymore.

action
String
"recalculate"
updateProductData
Boolean
  • Leave empty or set to false to only update the Prices and TaxRates of the Line Items.
  • Set to true to update the Line Items' product data (like name, variant and productType) also.
Default: false
Example: json
{
"action": "recalculate",
"updateProductData": true
}

Freeze Cart

Changes the CartState from Active to Frozen. Results in a Frozen Cart. Fails with InvalidOperation error when the Cart is empty.

  • action - String - "freezeCart"

Unfreeze Cart

Changes the CartState from Frozen to Active. Reactivates a Frozen Cart.

This action updates all prices in the Cart according to latest Prices on related Product Variants and Shipping Methods and by applying all discounts currently being active and applicable for the Cart.

  • action - String - "unfreezeCart"

on Line Item

Change LineItem Quantity

When multiple shipping addresses are set for a Line Item, use the Remove LineItem and Add LineItem update action to change the shipping details. Since it is not possible for the API to infer how the overall change in the Line Item quantity should be distributed over the sub-quantities, the shippingDetails field is kept in its current state to avoid data loss.

To change the Line Item quantity and shipping details together, use this update action in combination with the Set LineItem ShippingDetails update action in a single Cart update command.

The LineItem price is set as described in LineItem Price selection.

action
String
"changeLineItemQuantity"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

quantity
Int

New value to set.

If 0, the Line Item is removed from the Cart.

externalPrice

Sets the LineItem price to the given value when changing the quantity of a Line Item with the ExternalPrice LineItemPriceMode.

The LineItem price is updated as described in LineItem Price selection.

externalTotalPrice

Sets the LineItem price and totalPrice to the given value when changing the quantity of a Line Item with the ExternalTotal LineItemPriceMode.

Example: json
{
"action": "changeLineItemQuantity",
"lineItemId": "{{lineItemId}}",
"quantity": 1
}

Set LineItem TaxRate

Can be used if the Cart has the External TaxMode.

action
String
"setLineItemTaxRate"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

externalTaxRate

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

shippingKey
String

key of the ShippingMethod used for this Line Item. This is required for Carts with Multiple ShippingMode.

Example: json
{
"action": "setLineItemTaxRate",
"lineItemId": "{{lineItemId}}",
"externalTaxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}

Set LineItem TaxAmount

Can be used if the Cart has the ExternalAmount TaxMode.

action
String
"setLineItemTaxAmount"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

externalTaxAmount

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

shippingKey
String

key of the ShippingMethod used for this Line Item. This is required for Carts with Multiple ShippingMode.

Example: json
{
"action": "setLineItemTaxAmount",
"lineItemId": "{{lineItemId}}",
"externalTaxAmount": {
"totalGross": {
"currencyCode": "EUR",
"centAmount": 100
},
"taxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}
}

Set LineItem Price

Sets the LineItem price and changes the priceMode to ExternalPrice LineItemPriceMode.

action
String
"setLineItemPrice"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

externalPrice

Value to set. If externalPrice is not given and the priceMode is ExternalPrice, the external price is unset and the priceMode is set to Platform.

Example: json
{
"action": "setLineItemPrice",
"lineItemId": "{{lineItemId}}",
"externalPrice": {
"currencyCode": "EUR",
"centAmount": 4000
}
}

Set LineItem TotalPrice

Sets the LineItem totalPrice and price, and changes the priceMode to ExternalTotal LineItemPriceMode.

action
String
"setLineItemTotalPrice"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

externalTotalPrice

Value to set. If externalTotalPrice is not given and the priceMode is ExternalTotal, the external price is unset and the priceMode is set to Platform.

Example: json
{
"action": "setLineItemTotalPrice",
"lineItemId": "{{lineItemId}}",
"externalTotalPrice": {
"price": {
"currencyCode": "EUR",
"centAmount": 4200
},
"totalPrice": {
"currencyCode": "EUR",
"centAmount": 4200
}
}
}

Set LineItem DistributionChannel

Setting a distribution channel for a LineItem can lead to an updated price as described in LineItem Price selection.

action
String
"setLineItemDistributionChannel"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

distributionChannel
  • If present, a Reference to the Channel is set for the LineItem specified by lineItemId.
  • If not present, the current Reference to a distribution channel is removed from the LineItem specified by lineItemId. The Channel must have the ProductDistribution ChannelRoleEnum.
Example: json
{
"action": "setLineItemDistributionChannel",
"lineItemId": "{{lineItemId}}",
"distributionChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}

Set LineItem SupplyChannel

Performing this action has no impact on inventory that should be reserved.

action
String
"setLineItemSupplyChannel"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

supplyChannel
  • If present, a Reference to the Channel is set for the LineItem specified by lineItemId.
  • If not present, the current Reference to a supply channel will be removed from the LineItem specified by lineItemId. The Channel must have the InventorySupply ChannelRoleEnum.
Example: json
{
"action": "setLineItemSupplyChannel",
"lineItemId": "{{lineItemId}}",
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}

Set LineItem ShippingDetails

action
String
"setLineItemShippingDetails"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

shippingDetails

Value to set. If empty, the existing value is removed.

Example: json
{
"action": "setLineItemShippingDetails",
"lineItemId": "{{lineItemId}}",
"shippingDetails": {
"targets": [
{
"addressKey": "{{addressKey}}",
"quantity": 1
}
]
}
}

Apply DeltaToLineItemShippingDetailsTargets

To override the shipping details, see Set LineItem ShippingDetails.

action
String
"applyDeltaToLineItemShippingDetailsTargets"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

targetsDelta
Array of ItemShippingTarget

Using positive or negative quantities increases or decreases the number of items shipped to an address.

Example: json
{
"action": "applyDeltaToLineItemShippingDetailsTargets",
"lineItemId": "{{lineItemId}}",
"targetsDelta": [
{
"addressKey": "addressKeyString",
"quantity": 1
}
]
}

Set LineItem Custom Type

action
String
"setLineItemCustomType"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

Defines the Type that extends the Line Item with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Line Item.

fields

Sets the Custom Fields fields for the Line Item.

Example: json
{
"action": "setLineItemCustomType",
"lineItemId": "{{lineItemId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set LineItem CustomField

action
String
"setLineItemCustomField"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

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.

Example: json
{
"action": "setLineItemCustomField",
"lineItemId": "{{lineItemId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Set LineItem InventoryMode

action
String
"setLineItemInventoryMode"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

inventoryMode

Inventory mode specific to the Line Item only, and valid for the entire quantity of the Line Item. Set only if the inventory mode should be different from the inventoryMode specified on the Cart.

Example: json
{
"action": "setLineItemInventoryMode",
"lineItemId": "{{lineItemId}}",
"inventoryMode": "TrackOnly"
}

on Custom Line Item

Change CustomLineItem Quantity

When multiple shipping addresses are set for a Custom Line Item, use the Add CustomLineItem update action to change the shipping details. Since it is not possible for the API to infer how the overall change in the Custom Line Item quantity should be distributed over the sub-quantities, the shippingDetails field is kept in its current state to avoid data loss.

To change the Custom Line Item quantity and shipping details together, use this update action in combination with the Set CustomLineItem ShippingDetails update action in a single Cart update command.

action
String
"changeCustomLineItemQuantity"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

quantity
Int

New value to set.

If 0, the Custom Line Item is removed from the Cart.

Example: json
{
"action": "changeCustomLineItemQuantity",
"customLineItemId": "{{customlineItemId}}",
"quantity": 1
}

Set CustomLineItem TaxRate

Can be used if the Cart has the External TaxMode.

action
String
"setCustomLineItemTaxRate"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

externalTaxRate

Value to set. If empty, an existing value is removed.

shippingKey
String

key of the ShippingMethod used for this Custom Line Item. This is required for Carts with Multiple ShippingMode.

Example: json
{
"action": "setCustomLineItemTaxRate",
"customLineItemId": "{{customLineItemId}}",
"externalTaxRate": {
"name": "TaxRateName",
"country": "DE",
"amount": 0.19
}
}

Set CustomLineItem TaxAmount

Can be used if the Cart has the ExternalAmount TaxMode.

action
String
"setCustomLineItemTaxAmount"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

externalTaxAmount

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

shippingKey
String

key of the ShippingMethod used for this Custom Line Item. This is required for Carts with Multiple ShippingMode.

Example: json
{
"action": "setCustomLineItemTaxAmount",
"customLineItemId": "{{customLineItemId}}",
"externalTaxAmount": {
"totalGross": {
"centAmount": 2000000,
"currencyCode": "EUR"
},
"taxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}
}

Change CustomLineItem Price Mode

action
String
"changeCustomLineItemPriceMode"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

New value to set. Must not be empty.

Example: json
{
"action": "changeCustomLineItemPriceMode",
"customLineItemId": "{{customLineItemId}}",
"mode": "External"
}

Change CustomLineItem Money

action
String
"changeCustomLineItemMoney"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

money

Value to set. Must not be empty. Can be a negative amount.

Example: json
{
"action": "changeCustomLineItemMoney",
"customLineItemId": "{{customLineItemId}}",
"money": {
"currencyCode": "EUR",
"centAmount": 4200
}
}

Set CustomLineItem ShippingDetails

action
String
"setCustomLineItemShippingDetails"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

shippingDetails

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

Example: json
{
"action": "setCustomLineItemShippingDetails",
"customLineItemId": "{{customlineItemId}}",
"shippingDetails": {
"targets": [
{
"addressKey": "{{addressKey}}",
"quantity": 1
}
]
}
}

Apply DeltaToCustomLineItemShippingDetailsTargets

action
String
"applyDeltaToCustomLineItemShippingDetailsTargets"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

targetsDelta
Array of ItemShippingTarget

Using positive or negative quantities increases or decreases the number of items shipped to an address.

Example: json
{
"action": "applyDeltaToCustomLineItemShippingDetailsTargets",
"customLineItemId": "{{customlineItemId}}",
"targetsDelta": [
{
"addressKey": "addressKeyString",
"quantity": 1
}
]
}

Set CustomLineItem Custom Type

action
String
"setCustomLineItemCustomType"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

Defines the Type that extends the CustomLineItem with Custom Fields. If absent, any existing Type and Custom Fields are removed from the CustomLineItem.

fields

Sets the Custom Fields fields for the CustomLineItem.

Example: json
{
"action": "setCustomLineItemCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
},
"customLineItemId": "{{customLineItemId}}"
}

Set CustomLineItem CustomField

action
String
"setCustomLineItemCustomField"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

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.

Example: json
{
"action": "setCustomLineItemCustomField",
"customLineItemId": "{{customLineItemId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Billing Address

Set Billing Address Custom Type

action
String
"setBillingAddressCustomType"

Defines the Type that extends the billingAddress with Custom Fields. If absent, any existing Type and Custom Fields are removed from the billingAddress.

fields

Sets the Custom Fields fields for the billingAddress.

Example: json
{
"action": "setBillingAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Billing Address CustomField

action
String
"setBillingAddressCustomField"
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.

Example: json
{
"action": "setBillingAddressCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Shipping Address

Set Shipping Address Custom Type

action
String
"setShippingAddressCustomType"

Defines the Type that extends the shippingAddress with Custom Fields. If absent, any existing Type and Custom Fields are removed from the shippingAddress.

fields

Sets the Custom Fields fields for the shippingAddress.

Example: json
{
"action": "setShippingAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Shipping Address CustomField

action
String
"setShippingAddressCustomField"
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.

Example: json
{
"action": "setShippingAddressCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on ItemShipping Address

Set ItemShipping Address Custom Type

action
String
"setItemShippingAddressCustomType"
addressKey
String

key of the Address in itemShippingAddress.

Defines the Type that extends the itemShippingAddress with Custom Fields. If absent, any existing Type and Custom Fields are removed from the itemShippingAddress.

fields

Sets the Custom Fields fields for the itemShippingAddress.

Example: json
{
"action": "setItemShippingAddressCustomType",
"addressKey": "{{address-key}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set ItemShipping Address CustomField

action
String
"setItemShippingAddressCustomField"
addressKey
String

key of the Address in itemShippingAddress.

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.

Example: json
{
"action": "setItemShippingAddressCustomField",
"addressKey": "{{address-key}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Shipping Method

Set ShippingMethod TaxAmount

A Shipping Method tax amount can be set if the Cart has the ExternalAmount TaxMode.

action
String
"setShippingMethodTaxAmount"
shippingKey
String

key of the ShippingMethod to update. This is required for Carts with Multiple ShippingMode.

externalTaxAmount

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

Example: json
{
"action": "setShippingMethodTaxAmount",
"shippingKey": "shipping-method-key",
"externalTaxAmount": {
"totalGross": {
"centAmount": 2000000,
"currencyCode": "EUR"
},
"taxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}
}

Set ShippingMethod TaxRate

A Shipping Method Tax Rate can be set if the Cart has the External TaxMode.

action
String
"setShippingMethodTaxRate"
shippingKey
String

key of the ShippingMethod to update. This is required for Carts with Multiple ShippingMode.

externalTaxRate

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

Example: json
{
"action": "setShippingMethodTaxRate",
"shippingKey": "shipping-method-key",
"externalTaxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}

Set Shipping Custom Type

This action sets, overwrites, or removes any existing Custom Type and Custom Fields for the Cart's shippingMethod or shipping.

action
String
"setShippingCustomType"
shippingKey
String

The shippingKey of the Shipping to customize. Used to specify which Shipping Method to customize on a Cart with Multiple ShippingMode. Leave this empty to customize the one and only ShippingMethod on a Single ShippingMode Cart.

Defines the Type that extends the specified ShippingMethod with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShippingMethod.

fields

Sets the Custom Fields fields for the shippingMethod.

Example: json
{
"action": "setShippingCustomType",
"shippingKey": "shippingMethodKey1",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Shipping CustomField

action
String
"setShippingCustomField"
shippingKey
String

The shippingKey of the Shipping to customize. Used to specify which Shipping Method to customize on a Cart with Multiple ShippingMode. Leave this empty to customize the one and only ShippingMethod on a Single ShippingMode Cart.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setShippingCustomField",
"shippingKey": "shippingMethodKey1",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Delete Cart

The following methods delete a Cart accessible globally in the Project. For deleting Carts available in a Store only, use the Delete Cart in Store methods instead.

Delete Cart by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/carts/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Cartasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/carts/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Delete Cart by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Cart.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Cartasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/carts/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Delete Cart in Store

The following methods delete a Cart from a specific Store. For deleting Carts accessible globally in the Project, use the Delete Cart methods instead.

Delete Cart in Store by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}

If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Cartasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}

Delete Cart in Store by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}

If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFound error.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
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 Cart.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Cartasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}