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-CartDraft-CartPagedQueryResponse-CartReference-CartResourceIdentifier-ReplicaCartDraft-LineItemMode-LineItemPriceMode-CustomLineItemPriceMode-RoundingMode-TaxCalculationMode-TaxMode-InventoryMode-ShippingMode-CartState-CartOrigin
LineItem-LineItemDraft
CustomLineItem-CustomLineItemDraft
TaxedPrice-TaxedPriceDraft-TaxedItemPrice-TaxPortion-TaxPortionDraft-ExternalTaxRateDraft-ExternalTaxAmountDraft-ExternalLineItemTotalPrice-MethodTaxRate-MethodTaxedPrice
DiscountedLineItemPriceForQuantity-DiscountedLineItemPrice-DiscountedLineItemPortion
DirectDiscount-DirectDiscountDraft-DirectDiscountReference
DiscountCodeInfo-DiscountCodeState
ShippingInfo-CustomShippingDraft
Shipping-ShippingDraft
ShippingMethodState
ShippingRateInput-ClassificationShippingRateInput-ScoreShippingRateInput-ShippingRateInputDraft-ClassificationShippingRateInputDraft-ScoreShippingRateInputDraft
ItemShippingDetails-ItemShippingDetailsDraft-ItemShippingTarget

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: 2​MaxLength: 256​Pattern: ^[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​
CustomerGroupReference​

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​BETA
BusinessUnitKeyReference​

Reference to a Business Unit the Cart belongs to.

store​
StoreKeyReference​

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​
CentPrecisionMoney​

Sum of the totalPrice field of all LineItems and CustomLineItems, and if available, the price field of ShippingInfo.

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

taxedPrice​
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 the external Tax Rate for all Line Items, Custom Line Items, and Shipping Methods in the Cart are set.
taxedShippingPrice​
TaxedPrice​

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

taxMode​
TaxMode​

Indicates how Tax Rates are set.

Default: Platform​
taxRoundingMode​
RoundingMode​

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

Default: HalfEven​
taxCalculationMode​
TaxCalculationMode​

Indicates how taxes are calculated when calculating taxes for taxedPrice.

Default: LineItemLevel​
inventoryMode​
InventoryMode​

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

Default: None​
cartState​
CartState​

Current status of the Cart.

Default: Active​
billingAddress​
Address​

Billing address associated with the Cart.

shippingAddress​
Address​

Shipping address associated with the Cart. Determines eligible ShippingMethod rates and Tax Rates of Line Items.

shippingMode​
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​
ShippingInfo​

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

shippingRateInput​
ShippingRateInput​

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

shippingCustomFields​
CustomFields​

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.

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​
Array of CartDiscountReference​

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

paymentInfo​
PaymentInfo​

Payment information related to the Cart.

country​
CountryCode​

Used for LineItem Price selection.

locale​
Locale​

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

origin​
CartOrigin​

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​
CustomFields​

Custom Fields of the Cart.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

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

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

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

CartDraft

key​
String​

User-defined unique identifier for the Cart.

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

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.

customerGroup​
CustomerGroupResourceIdentifier​

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.

businessUnit​BETA
BusinessUnitResourceIdentifier​

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.

store​
StoreResourceIdentifier​

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​
Array of CustomLineItemDraft​

Custom Line Items to add to the Cart.

taxMode​
TaxMode​

Determines how Tax Rates are set.

Default: Platform​
externalTaxRateForShippingMethod​
ExternalTaxRateDraft​

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

taxRoundingMode​
RoundingMode​

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

Default: HalfEven​
taxCalculationMode​
TaxCalculationMode​

Determines how taxes are calculated when calculating taxes for taxedPrice.

Default: LineItemLevel​
inventoryMode​
InventoryMode​

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

Default: None​
billingAddress​
BaseAddress​

Billing address associated with the Cart.

shippingAddress​
BaseAddress​

Shipping address associated with the Cart. Determines eligible ShippingMethod rates and Tax Rates of Line Items.

shippingMethod​
ShippingMethodResourceIdentifier​

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​
ShippingRateInputDraft​

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

shippingMode​
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​
Array of CustomShippingDraft​

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.

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​
CountryCode​

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

locale​
Locale​

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

origin​
CartOrigin​

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​
CustomFieldsDraft​

Custom Fields for the Cart.

CartPagedQueryResponse

PagedQueryResult with results containing an array of Cart.

limit​
Int​

Number of results requested.

offset​
Int​

Number of elements skipped.

count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter 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

Reference to a Cart.

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.

id​
String​

Unique identifier of the referenced Cart. Either id or key is required.

key​
String​

User-defined unique identifier of the referenced Cart. Either id or key is required.

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 evenExternal link icon

Default mode for a new Cart.

HalfUp

Round half upExternal link icon

HalfDown

Round half downExternal link icon

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

Information icon

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 (BETA).

LineItem

The representation of a Line Item in a Cart.

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 Line Item was created or updated on the Cart.
  • Orders 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​
LocalizedString​

Name of the Product.

productSlug​
LocalizedString​

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​
ProductTypeReference​

Product Type of the Product.

variant​
ProductVariant​

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​

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.

Default: 1​
totalPrice​
CentPrecisionMoney​

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​
Array of DiscountedLineItemPriceForQuantity​

Discounted price of a single quantity of the Line Item.

taxedPrice​
TaxedItemPrice​

Automatically set after taxRate is set.

taxedPricePortions​
Array of MethodTaxedPrice​

Taxed price of the Shipping Method that is automatically set after perMethodTaxRate is set.

state​
Array of ItemState​

State of the Line Item in the Cart.

taxRate​
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​
ChannelReference​

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

distributionChannel​
ChannelReference​

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

priceMode​
LineItemPriceMode​

Indicates how the Price for the Line Item is set.

lineItemMode​
LineItemMode​

Indicates how the Line Item is added to the Cart.

Default: Standard​
inventoryMode​
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​
ItemShippingDetails​

Container for Line Item-specific addresses.

addedAt​
DateTime​

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

custom​
CustomFields​

Custom Fields of the Line Item.

lastModifiedAt​
DateTime​

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: 2​MaxLength: 256​Pattern: ^[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​
DateTime​

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​
ChannelResourceIdentifier​

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​
ChannelResourceIdentifier​

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

externalPrice​
Money​

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

externalTotalPrice​
ExternalLineItemTotalPrice​

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

externalTaxRate​
ExternalTaxRateDraft​

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

inventoryMode​
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​
ItemShippingDetailsDraft​

Container for Line Item-specific addresses.

custom​
CustomFieldsDraft​

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.

name​
LocalizedString​

Name of the Custom Line Item.

money​
TypedMoney​

Money value of the Custom Line Item.

taxedPrice​
TaxedItemPrice​

Automatically set after the taxRate is set.

totalPrice​
CentPrecisionMoney​

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.

Default: 1​
state​
Array of ItemState​

State of the Custom Line Item in the Cart.

taxCategory​
TaxCategoryReference​

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

taxRate​
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.
discountedPricePerQuantity​
Array of DiscountedLineItemPriceForQuantity​

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

shippingDetails​
ItemShippingDetails​

Container for Custom Line Item-specific addresses.

priceMode​
CustomLineItemPriceMode​

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

custom​
CustomFields​

Custom Fields of the Custom Line Item.

CustomLineItemDraft

name​
LocalizedString​

Name of the Custom Line Item.

quantity​
Int​

Number of Custom Line Items to add to the Cart.

Default: 1​
money​
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}.

taxCategory​
TaxCategoryResourceIdentifier​

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

externalTaxRate​
ExternalTaxRateDraft​

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

shippingDetails​
ItemShippingDetailsDraft​

Container for Custom Line Item-specific addresses.

priceMode​
CustomLineItemPriceMode​
  • 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​
CustomFieldsDraft​

Custom Fields for the Custom Line Item.

TaxedPrice

totalNet​
CentPrecisionMoney​

Total net price of the Cart or Order.

totalGross​
CentPrecisionMoney​

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​
CentPrecisionMoney​

Total tax applicable for the Cart or Order.

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

TaxedPriceDraft

totalNet​
Money​

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

totalGross​
Money​

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

taxPortions​
Array of TaxPortionDraft​

Taxable portions added to the totalGross.

Calculated from the TaxRates.

TaxedItemPrice

totalNet​
CentPrecisionMoney​

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

totalGross​
CentPrecisionMoney​

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

totalTax​
CentPrecisionMoney​

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​
CentPrecisionMoney​

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​

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​
CountryCode​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​BETA
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).

ExternalTaxAmountDraft

Cannot be used in LineItemDraft or CustomLineItemDraft.

Can only be set by these update actions:

totalGross​
Money​

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

taxRate​
ExternalTaxRateDraft​

Tax Rates and subrates of states and countries.

Warning icon

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​
Money​

Price of the Line Item.

The value is selected from the Product Variant according to the Product priceMode.

totalPrice​
Money​

Total price of the Line Item.

MethodTaxRate

shippingMethodKey​
String​

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

taxRate​
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​
TaxedItemPrice​

Taxed price for the Shipping Method.

DiscountedLineItemPriceForQuantity

quantity​
Int​

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

discountedPrice​
DiscountedLineItemPrice​

Discounted price of the Line Item or Custom Line Item.

DiscountedLineItemPrice

value​
TypedMoney​

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

includedDiscounts​
Array of DiscountedLineItemPortion​

Discount applicable on the Line Item or Custom Line Item.

DiscountedLineItemPortion

discount​
Reference​

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

discountedAmount​
TypedMoney​

Money value of the discount applicable.

DirectDiscount

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

id​
String​

Unique identifier of the Direct Discount.

value​
CartDiscountValue​

Effect of the Discount on the Cart.

target​
CartDiscountTarget​

Part 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.

value​
CartDiscountValue​

Defines the effect the Discount will have.

target​
CartDiscountTarget​

Defines what part 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"
  }
}
Clipboard icon

DirectDiscountReference

Reference to a DirectDiscount.

id​
String​

Unique identifier of the referenced DirectDiscount.

typeId​
String​
"direct-discount"

References a DirectDiscount.

DiscountCodeInfo

discountCode​
DiscountCodeReference​

Discount Code associated with the Cart or Order.

state​
DiscountCodeState​

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.

price​
CentPrecisionMoney​

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

shippingRate​
ShippingRate​

Used to determine the price.

taxedPrice​
TaxedItemPrice​

Automatically set after the taxRate is set.

taxRate​
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​
TaxCategoryReference​

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

shippingMethod​
ShippingMethodReference​

Not set if a custom Shipping Method is used.

deliveries​
Array of Delivery​

Information on how items are delivered to customers.

discountedPrice​
DiscountedLineItemPrice​

Discounted price of the Shipping Method.

shippingMethodState​
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​
BaseAddress​

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

shippingRate​
ShippingRateDraft​

Determines the shipping price.

shippingRateInput​
ShippingRateInputDraft​

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

taxCategory​
TaxCategoryResourceIdentifier​

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

externalTaxRate​
ExternalTaxRateDraft​

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​
CustomFieldsDraft​

Custom Fields for the custom Shipping Method.

Shipping

shippingKey​
String​

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

shippingInfo​
ShippingInfo​

Automatically set when the Shipping Method is added.

shippingAddress​
Address​

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

shippingRateInput​
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​
CustomFields​

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​
ShippingMethodReference​

Shipping Methods added to the Cart with Multiple ShippingMode.

shippingAddress​
BaseAddress​

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

shippingRateInput​
ShippingRateInputDraft​

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

externalTaxRate​
ExternalTaxRateDraft​

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​
CustomFieldsDraft​

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​
LocalizedString​

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 quantities with individual shipping addresses.

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Cart
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Cart
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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, a ResourceNotFound error is returned.

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Cart
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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, a ResourceNotFound error is returned.

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Cart
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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, a ResourceNotFound error is returned.

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Cart
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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, a ResourceNotFound error is returned.

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

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Cart
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}'
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
​
QueryPredicate
​
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
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200CartPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
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"
  } ]
}
Clipboard icon

Query Carts in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts
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
​
QueryPredicate
​
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
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200CartPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
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"
  } ]
}
Clipboard icon

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
​
Expansion
​
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
Clipboard icon
201 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

Create Cart in Store

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

The store field in the created Cart is set to the Store specified by the storeKey path parameter.

Specific Error Codes: CountryNotConfiguredInStore

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
​
Expansion
​
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
Clipboard icon
201 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
Clipboard icon
201 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
Clipboard icon
201 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
​
Expansion
​
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 409 Conflict is 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
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
​
Expansion
​
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 409 Conflict is 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
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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, a ResourceNotFound 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.

id
​
String
​

id of the Cart.

Query parameters:
expand
​
Expansion
​
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 409 Conflict is 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
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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" : [ ]
}
Clipboard icon

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
​
Expansion
​
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 409 Conflict is 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
Clipboard icon
200 Response Example: Cartjson
{
  "type" : "Cart",
  "id" : "27b39077-aa57-48a5-b504-914f68fa44dc",
  "version" : 1,
  "versionModifiedAt" : "2023-01-23T13:06:28.569Z",
  "lastMessageSequenceNumber" : 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",