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 -TaxedItemPrice -TaxPortion -TaxPortionDraft -ExternalTaxRateDraft -ExternalTaxAmountDraft -ExternalLineItemTotalPrice -MethodExternalTaxRateDraft -MethodTaxRate -MethodTaxedPrice

DiscountedLineItemPriceForQuantity -DiscountedLineItemPrice -DiscountedLineItemPortion -DiscountedLineItemPortionDraft

DiscountOnTotalPrice -DiscountedTotalPricePortion

DirectDiscount -DirectDiscountDraft -DirectDiscountReference

DiscountCodeInfo -DiscountCodeState

ShippingInfo -CustomShippingDraft

Shipping -ShippingDraft

ShippingMethodState

ShippingRateInput -ClassificationShippingRateInput -ScoreShippingRateInput -ShippingRateInputDraft -ClassificationShippingRateInputDraft -ScoreShippingRateInputDraft

ItemShippingDetails -ItemShippingDetailsDraft -ItemShippingTarget

ItemState

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 Line Item price selection.
`anonymousId` String	Anonymous session associated with the Cart.
`businessUnit` 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. If a discount applies on `totalPrice`, this field holds the discounted value. 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 Carts with `Multiple` ShippingMode, all Line Items and Custom Line Items must be fully distributed between the Shipping Methods (via `shippingDetails`), otherwise `taxedPrice` is not automatically 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. For Carts with `Multiple` ShippingMode, all allocations must have their respective tax rates present in `perMethodTaxRate`, otherwise `taxedPrice` is not automatically set. If a discount applies on `totalPrice`, this field holds the discounted values.
`taxedShippingPrice` TaxedPrice	Sum of the `taxedPrice` field of ShippingInfo across all Shipping Methods.
`discountOnTotalPrice` DiscountOnTotalPrice	Discounts that apply on the Cart `totalPrice`.
`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 for a Cart with `Single` ShippingMode. 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: If `CartClassification`, it is ClassificationShippingRateInput. If `CartScore`, it is ScoreShippingRateInput. If `CartValue`, it cannot be used.
`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. 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` 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 Line Item 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	IDs and references that created the Cart.
`lastModifiedAt` DateTime	Date and time (UTC) the Cart was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the Cart.

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 Line Item 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` 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 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 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.
`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: If `CartClassification`, it must be ClassificationShippingRateInputDraft. If `CartScore`, it must be ScoreShippingRateInputDraft. If `CartValue`, it cannot be set.
`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`. 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` CountryCode	Used for Line Item 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` ReferenceTypeId	`"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` ReferenceTypeId	`"cart"` References a Cart.

ReplicaCartDraft

Used for replicating an existing Cart or Order.

`key` String	User-defined unique identifier for the Cart.
`reference` Can be CartReference, or OrderReference	Reference to a Cart or Order that is replicated.

LineItemMode

Indicates how a Line Item was added to a Cart.

Standard: The Line Item was added during Cart creation or the Add LineItem update action. The Line Item quantity can be changed without restriction.
GiftLineItem: One Line Item was added automatically to a Cart by a Cart Discount with CartDiscountValueGiftLineItemDraft.

The quantity cannot be increased, and it won't be merged when adding the same Line Item 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, despite a matching CartDiscountLineItemsTarget or MultiBuyLineItemsTarget. 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 externalTotalPrice field. If the externalTotalPrice 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 and MultiBuyCustomLineItemsTarget.

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 round	HalfUp	HalfDown	HalfEven
23.5	24	23	24
24.5	25	24	24
25.5	26	25	26

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.
The totalNet, totalGross, and taxPortions fields are calculated based on the taxRoundingMode.

External

Tax Rates are set externally with ExternalTaxRateDraft. A Cart can be ordered only if all Line Items, Custom Line Items, and the Shipping Method have an external Tax Rate set.
The totalNet, totalGross, and taxPortions fields are calculated based on the taxRoundingMode.

ExternalAmount

Tax amounts, Tax Rates, and tax portions are set externally with 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.
The Cart taxedPrice field must be set using Set Cart Total Tax. The Cart taxedShippingPrice field is always empty in this tax mode.
Price-affecting update actions on Carts require external recalculation of the total gross price. In these cases, taxedPrice and taxRate are removed and must be set again. The order in which the individual update actions are issued is important:
1. Issue the price-affecting update action(s).
2. Update the tax amounts using Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount.
  - If the update action changes the Line Item price, for Line Items with Platform LineItemPriceMode, you must issue Set LineItem TaxAmount in a separate request.
  - If the update action removes the externally set tax amount for the Shipping Method, you must issue Set ShippingMethod TaxAmount in a separate request.
3. Update the taxedPrice on Cart using Set Cart Total Tax.
Tax-inclusive pricing should be avoided when using TaxMode ExternalAmount because taxedItemPrice.totalNet is automatically set by the platform to the Line Item's totalPrice.

Disabled

No taxes are added to the Cart.
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. A Customer can have more than one active Cart.

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.

Add LineItem
Change LineItem Quantity
Remove LineItem
Set LineItem DistributionChannel
Set LineItem SupplyChannel
Add CustomLineItem
Change CustomLineItem Quantity
Remove CustomLineItem
Change TaxMode
Set LineItem Price
Set LineItem TotalPrice

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` 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 or Order. 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	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` 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	Sets the external Tax Rate for the Line Item, if the Cart has the `External` TaxMode and `Single` ShippingMode. If the Cart has `Multiple` ShippingMode, the Tax Rate is accepted but ignored.
`perMethodExternalTaxRate` Array of MethodExternalTaxRateDraft	Sets the external Tax Rates for individual Shipping Methods, if the Cart has the `External` TaxMode and `Multiple` ShippingMode.
`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.
`key` String	User-defined 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.
`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` 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 or Order. Default: `1`
`state` Array of ItemState	State of the Custom Line Item in the Cart or Order.
`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.
`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` 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

`key` String	User-defined unique identifier of the Custom Line Item. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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.

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.
`taxPortions` Array of TaxPortion	Taxable portions added to the total net price. Calculated from the TaxRates.
`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` Array of SubRate	Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate `amount`. These subrates are used to calculate the `taxPortions` field of a Cart or Order and the `taxedPrice` field of LineItems, CustomLineItems, and ShippingInfos.

ExternalTaxAmountDraft

Cannot be used in LineItemDraft or CustomLineItemDraft.

Can only be set by these update actions:

Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount on Carts
Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount on Order Edits

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

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.
`totalPrice` Money	Total price of the Line Item.

MethodExternalTaxRateDraft

`shippingMethodKey` String	User-defined unique identifier of the Shipping Method in a Cart with `Multiple` ShippingMode.
`taxRate` ExternalTaxRateDraft	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` 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	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` 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 of the applicable discount on the Line Item.
`discountedAmount` TypedMoney	Money value of the applicable discount.

DiscountedLineItemPortionDraft

`discount` Reference	A CartDiscountReference or DirectDiscountReference for the discount applicable on the Line Item.
`discountedAmount` TypedMoneyDraft	Money value for the discount applicable.

DiscountOnTotalPrice

`discountedAmount` TypedMoney	Money value of the discount on the total price of the Cart or Order.
`includedDiscounts` Array of DiscountedTotalPricePortion	Discounts that impact the total price of the Cart or Order.
`discountedNetAmount` TypedMoney	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` TypedMoney	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` CartDiscountReference	Cart Discount related to the discounted price.
`discountedAmount` TypedMoney	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.
`value` CartDiscountValue	Effect of the Discount on the Cart.
`target` CartDiscountTarget	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.

For an introduction to Direct Discounts and to understand how they work in Composable Commerce, see the Direct Discounts overview.

`value` CartDiscountValueDraft	Defines the effect the Discount will have.
`target` CartDiscountTarget	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

Reference to a DirectDiscount.

`id` String	Unique identifier of the referenced DirectDiscount.
`typeId` ReferenceTypeId	`"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: If `CartClassification`, it must be ClassificationShippingRateInputDraft. If `CartScore`, it must be ScoreShippingRateInputDraft. If `CartValue`, it cannot be set.
`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: If `CartClassification`, it is ClassificationShippingRateInput. If `CartScore`, it is ScoreShippingRateInput. If `CartValue`, it cannot be used.
`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: If `CartClassification`, it must be ClassificationShippingRateInputDraft. If `CartScore`, it must be ScoreShippingRateInputDraft. If `CartValue`, it cannot be set.
`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 the selected ShippingMethod is allowed for the Cart. For more information, see Predicates.

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:

If CartClassification, it is ClassificationShippingRateInput.
If CartScore, it is ScoreShippingRateInput.
If CartValue, it cannot be used.

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:

If CartClassification, it must be ClassificationShippingRateInputDraft.
If CartScore, it must be ScoreShippingRateInputDraft.
If CartValue, it cannot be set.

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` StateReference	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.

by ID

by Key

by Customer 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:

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

by ID

by Key

by Customer 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 a store specified, 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

Expansion

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": []
}

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. Default: `true`

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` 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. Default: `true`

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

by ID

by Key

by Customer ID

by Query Predicate

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 in Store

by ID

by Key

by Customer ID

by Query Predicate

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 ResourceNotFound error 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}'

Create Cart

POST

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

If the referenced ShippingMethod in the CartDraft has a predicate that does not match, or if the Shipping Method is not active, an InvalidOperation error is returned.

Specific Error Codes:

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

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.

If the referenced ShippingMethod in the CartDraft has a predicate that does not match, or if the Shipping Method is not active, an InvalidOperation error is returned.

Specific Error Codes:

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

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.

Specific Error Codes:

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 new Cart does not contain payments or deliveries. The State of Line Items and Custom Line Items is reset to initial.

Specific Error Codes:

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.

by ID

by Key

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

by ID

by Key

by Customer ID

by Query Predicate

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 a store specified, 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

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 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 actions

on Line Item -Change LineItem Quantity -Set LineItem TaxRate -Set LineItem TaxAmount -Set LineItem Price -Set LineItem TotalPrice -Set LineItem DistributionChannel -Set LineItem SupplyChannel -Set LineItem ShippingDetails -Apply DeltaToLineItemShippingDetailsTargets -Set LineItem Custom Type -Set LineItem CustomField -Set LineItem InventoryMode

on Custom Line Item -Change CustomLineItem Quantity -Set CustomLineItem TaxRate -Set CustomLineItem TaxAmount -Change CustomLineItem Price Mode -Change CustomLineItem Money -Set CustomLineItem ShippingDetails -Apply DeltaToCustomLineItemShippingDetailsTargets -Set CustomLineItem Custom Type -Set CustomLineItem CustomField

on Billing Address -Set Billing Address Custom Type -Set Billing Address CustomField

on Shipping Address -Set Shipping Address Custom Type -Set Shipping Address CustomField

on ItemShipping Address -Set ItemShipping Address Custom Type -Set ItemShipping Address CustomField

on Shipping Method -Set ShippingMethod TaxAmount -Set ShippingMethod TaxRate

on Shipping -Set Shipping Custom Type -Set Shipping CustomField

on Cart

Set Key

`action` String	`"setKey"`
`key` String	Value to set. If empty, any existing key will be removed. MinLength: `2`MaxLength: `256`Pattern: `^[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 the Customer is assigned to a CustomerGroup, this update action also sets the value for the `customerGroup` field. If empty, the update action removes the value for both `customerId` and `customerGroup`.

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 the Cart. If a Customer is already assigned, the Cart uses the Customer Group of the assigned Customer.

To reflect the new Customer Group, this update action can result in updates to the Cart. When this occurs, the following errors can be returned: MatchingPriceNotFound and MissingTaxRateForCountry.

`action` String	`"setCustomerGroup"`
`customerGroup` CustomerGroupResourceIdentifier	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

If the Cart is already associated with a Customer, an InvalidOperation error is returned.

`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"`
`businessUnit` BusinessUnitResourceIdentifier	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 Line Item 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: `2`MaxLength: `256`Pattern: `^[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` 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 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 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	Sets the external Tax Rate for the Line Item, if the Cart has the `External` TaxMode and `Single` ShippingMode. If the Cart has `Multiple` ShippingMode, the Tax Rate is accepted but ignored.
`perMethodExternalTaxRate` Array of MethodExternalTaxRateDraft	Sets the external Tax Rates for individual Shipping Methods, if the Cart has the `External` TaxMode and `Multiple` ShippingMode.
`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.

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 Line Item 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` Money	Sets the LineItem `price` to the given value when decreasing the quantity of a Line Item with the `ExternalPrice` LineItemPriceMode.
`externalTotalPrice` ExternalLineItemTotalPrice	Sets the LineItem `price` and `totalPrice` to the given value when decreasing the quantity of a Line Item with the `ExternalTotal` LineItemPriceMode.
`shippingDetailsToRemove` ItemShippingDetailsDraft	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
      }
    ]
  }
}

Change LineItems Order

`action` String	`"changeLineItemsOrder"`
`lineItemOrder` Array of String	All existing LineItem `id`s in the desired new order.

Example: json

{
  "action": "changeLineItemsOrder",
  "lineItemOrder": ["{{lineItemId2}}", "{{lineItemId}}"]
}

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: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`money` Money	Money value of the Custom Line Item. The value can be negative.
`name` LocalizedString	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}`.
`taxCategory` TaxCategoryResourceIdentifier	Used to select a Tax Rate when a Cart has the `Platform` TaxMode. If TaxMode is `Platform`, this field must not be empty.
`externalTaxRate` ExternalTaxRateDraft	An external Tax Rate can be set if the Cart has `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.

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"`
`shoppingList` ShoppingListResourceIdentifier	Shopping List that contains the Line Items to be added.
`distributionChannel` ChannelResourceIdentifier	`distributionChannel` to set for all LineItems that are added to the Cart. The Channel must have the `ProductDistribution` ChannelRoleEnum.
`supplyChannel` ChannelResourceIdentifier	`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

Can be used if the Cart has the ExternalAmount TaxMode. This update action adds the taxedPrice field to the Cart and must be used after any price-affecting change occurs within the Cart.

`action` String	`"setCartTotalTax"`
`externalTotalGross` Money	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` 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` RoundingMode	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` 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` DiscountCodeReference	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` Array of DirectDiscountDraft	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` PaymentResourceIdentifier	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` PaymentResourceIdentifier	Payment to remove from the Cart.

Example: json

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

Set Billing Address

`action` String	`"setBillingAddress"`
`address` BaseAddress	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` BaseAddress	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` BaseAddress	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` BaseAddress	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.
`shippingMethod` ShippingMethodResourceIdentifier	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` BaseAddress	Determines the shipping rate and Tax Rate of the 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: If `CartClassification`, it must be ClassificationShippingRateInputDraft. If `CartScore`, it must be ScoreShippingRateInputDraft. If `CartValue`, it cannot be set.
`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 referenced Shipping Method.
`custom` CustomFieldsDraft	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"`
`shippingMethod` ShippingMethodResourceIdentifier	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` ExternalTaxRateDraft	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` 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: If `CartClassification`, it must be ClassificationShippingRateInputDraft. If `CartScore`, it must be ScoreShippingRateInputDraft. If `CartValue`, it cannot be set.
`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.

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` ShippingRateDraft	Determines the shipping price.
`taxCategory` TaxCategoryResourceIdentifier	Tax Category used to determine the Tax Rate when the Cart has the `Platform` TaxMode.
`externalTaxRate` ExternalTaxRateDraft	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` ShippingRateInputDraft	The data type of this field depends on the `shippingRateInputType.type` configured in the Project: If `CartClassification`, it must be ClassificationShippingRateInputDraft. If `CartScore`, it must be ScoreShippingRateInputDraft. If `CartValue`, it cannot be set.

Example: json

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

Set Locale

`action` String	`"setLocale"`
`locale` 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` CountryCode	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"`
`type` TypeResourceIdentifier	Defines the Type that extends the Cart with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Cart.
`fields` FieldContainer	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` CustomFieldValue	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 Line Item 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` Money	Required when the Line Item uses `ExternalPrice` LineItemPriceMode. Sets the LineItem `price` to the given value when changing the quantity of a Line Item. The LineItem price is updated as described in Line Item price selection.
`externalTotalPrice` ExternalLineItemTotalPrice	Sets the LineItem `price` and `totalPrice` to the given value when changing the quantity of a Line Item with the `ExternalTotal` LineItemPriceMode. 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": "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` ExternalTaxRateDraft	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. This update action sets the taxedPrice and taxRate on a Line Item and must be used after any price-affecting change occurs.

`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` ExternalTaxAmountDraft	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` Money	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` ExternalLineItemTotalPrice	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 Line Item 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` ChannelResourceIdentifier	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` ChannelResourceIdentifier	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` ItemShippingDetailsDraft	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.
`type` TypeResourceIdentifier	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` FieldContainer	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` CustomFieldValue	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` 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` ExternalTaxRateDraft	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` ExternalTaxAmountDraft	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.
`mode` CustomLineItemPriceMode	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` 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` ItemShippingDetailsDraft	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.
`type` TypeResourceIdentifier	Defines the Type that extends the CustomLineItem with Custom Fields. If absent, any existing Type and Custom Fields are removed from the CustomLineItem.
`fields` FieldContainer	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` CustomFieldValue	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"`
`type` TypeResourceIdentifier	Defines the Type that extends the `billingAddress` with Custom Fields. If absent, any existing Type and Custom Fields are removed from the `billingAddress`.
`fields` FieldContainer	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` CustomFieldValue	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"`
`type` TypeResourceIdentifier	Defines the Type that extends the `shippingAddress` with Custom Fields. If absent, any existing Type and Custom Fields are removed from the `shippingAddress`.
`fields` FieldContainer	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` CustomFieldValue	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`.
`type` TypeResourceIdentifier	Defines the Type that extends the `itemShippingAddress` with Custom Fields. If absent, any existing Type and Custom Fields are removed from the `itemShippingAddress`.
`fields` FieldContainer	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` CustomFieldValue	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` ExternalTaxAmountDraft	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` ExternalTaxRateDraft	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"
  }
}

on Shipping

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.
`type` TypeResourceIdentifier	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` FieldContainer	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` CustomFieldValue	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.

by ID

by Key

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` Expansion	The parameter can be passed multiple times.
`dataErasure` Boolean	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

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

by ID

by Key

DELETE

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

If the Cart exists in the Project but does not have a store specified, 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` Expansion	The parameter can be passed multiple times.
`dataErasure` Boolean	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

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": []
}