Carts

Representations

All representations are JSON objects submitted or received as payload to API requests or responses.

Cart

• id - String
  The unique ID of the cart.
• key - String - Optional
  User-specific unique identifier of the cart.
• version - Number
  The current version of the cart.
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• customerId - String - Optional
• customerEmail - String - Optional
• anonymousId - String - Optional
  Identifies carts and orders belonging to an anonymous session (the customer has not signed up/in yet).
• store - KeyReference to a Store - Optional
• lineItems - Array of LineItem
• customLineItems - Array of CustomLineItem
• totalLineItemQuantity - The sum off all the lineItems quantities. Does not take customLineItems into consideration.
• totalPrice - CentPrecisionMoney
  The sum of all totalPrice fields of the lineItems and customLineItems, as well as the price field of shippingInfo (if it exists). totalPrice may or may not include the taxes: it depends on the taxRate.includedInPrice property of each price.
• taxedPrice - TaxedPrice - Optional
  Not set until the shipping address is set. Will be set automatically in the Platform TaxMode. For the External tax mode it will be set as soon as the external tax rates for all line items, custom line items, and shipping in the cart are set.
• cartState - CartState
• shippingAddress - Address - Optional
  The shipping address is used to determine the eligible shipping methods and rates as well as the tax rate of the line items.
• billingAddress - Address - Optional
• inventoryMode - InventoryMode
• taxMode - TaxMode
• taxRoundingMode - RoundingMode
  When calculating taxes for taxedPrice, the selected mode is used for rounding.
• taxCalculationMode - TaxCalculationMode
  When calculating taxes for taxedPrice, the selected mode is used for calculating the price with LineItemLevel (horizontally) or UnitPriceLevel (vertically) calculation mode.
• customerGroup - Reference to a CustomerGroup - Optional
  Set automatically when the customer is set and the customer is a member of a customer group. Used for product variant price selection.
• country - String - Optional
  A two-digit country code as per ISO 3166-1 alpha-2. Used for product variant price selection.
• shippingInfo - ShippingInfo - Optional
  Set automatically once the ShippingMethod is set.
• discountCodes - Array of DiscountCodeInfo
• refusedGifts - Array of References to CartDiscounts
  Automatically filled when a line item with LineItemMode GiftLineItem is removed from the cart.
• custom - CustomFields - Optional
• paymentInfo - PaymentInfo - Optional
• locale - String conforming to IETF language tag - Optional
• deleteDaysAfterLastModification - Number - Optional
  The cart will be deleted automatically if it hasn't been modified for the specified amount of days.
• shippingRateInput -ShippingRateInput - Optional
  The shippingRateInput is used as an input to select a ShippingRatePriceTier.
• origin - CartOrigin
  The origin field indicates how this cart was created. The value Customer indicates, that the cart was created by the customer.
• itemShippingAddresses - Array of Addresses
  Contains addresses for carts with multiple shipping addresses. Line items reference these addresses under their shippingDetails. The addresses captured here are not used to determine eligible shipping methods or the applicable tax rate. Only the cart's shippingAddress is used for this.

Cart fields that can be used in query predicates: id, version, createdAt, lastModifiedAt, customerId, customerEmail, anonymousId, country, totalPrice, taxedPrice, shippingAddress, billingAddress, customerGroup, lineItems, customLineItems, shippingInfo, discountCodes, paymentInfo, cartState, inventoryMode, locale, shippingRateInput, taxCalculationMode, itemShippingAddresses.

Cart Price precision

• Prices with TypedMoney can have cent-precision and high-precision.
• When calculating net and gross prices, prices with decimals are rounded. In case the fraction of centAmount is exactly 0.5, the RoundingMode defined by taxRoundingMode is applied on the cart's price.
• The tax portions are derived from the net prices in case the tax is not included in the price, meaning the includedInPrice-field in the TaxRate for the product is set tofalse. When the tax is included in the price (includedInPrice:true), then the tax portions are derived from the gross prices. This only applies when the Platform TaxMode is used.
• When prices are discounted with relative discounts, they are always rounded in favor of the customer with the half down rounding.

Cart tax rate selection

A cart cannot calculate taxes for the items in it until the shippingAddress property is set. The shippingAddress.country and shippingAddress.state properties affect the selection criteria. These are compared to the TaxRate's country and state fields. A tax rate is only eligible if the country and state properties are an exact match. Because the state field is optional on both TaxRate and shippingAddress, this means the following:

• If shippingAddress.country and TaxRate.country are an exact match , and no state properties are present, the TaxRate applies to the cart.
• If shippingAddress.country and TaxRate.country are an exact match, but either shippingAddress.state or TaxRate.state are present, the tax rate does not apply to the cart.
• If shippingAddress.country and TaxRate.country are an exact match, and shippingAddress.state and TaxRate.state are an exact match, the tax rate applies to the cart.
• If shippingAddress.country and TaxRate.country are present, and shippingAddress.state and TaxRate.state are present, but there is a mismatch of either country or state, the tax rate does not apply to the cart.

If you need to include a state or country sub-unit for shipping purposes, use shippingAddress.region to avoid tax rate conflicts.

CartDraft

A CartDraft is the object submitted as payload to a Create Cart method.

• currency - String - Required
  A three-digit currency code as per ISO 4217.
• key - String - Optional
  User-specific unique identifier of the cart.
• customerId - String - Optional
  Id of an existing Customer.
• customerEmail - String - Optional
• customerGroup - ResourceIdentifier of a CustomerGroup - Optional
  Will be set automatically when the customerId is set and the customer is a member of a customer group. Can be set explicitly when no customerId is present.
• anonymousId - String - Optional
  Assigns the new cart to an anonymous session (the customer has not signed up/in yet).
• store - ResourceIdentifier of a Store - Optional Assigns the new cart to the store. The store assignment can not be modified.
• country - String - Optional
  A two-digit country code as per ISO 3166-1 alpha-2.
• inventoryMode - InventoryMode - Optional
  Default inventory mode is None.
• taxMode - TaxMode - Optional
  The default tax mode is Platform.
• taxRoundingMode - RoundingMode - Optional
  The default tax rounding mode is HalfEven.
• taxCalculationMode - TaxCalculationMode - Optional
  The default tax calculation mode is LineItemLevel.
• lineItems - Array of LineItemDraft - Optional
• customLineItems - Array of CustomLineItemDraft - Optional
• shippingAddress - AddressDraft - Optional
  The shipping address is used to determine the eligible shipping methods and rates as well as the tax rate of the line items.
• billingAddress - AddressDraft - Optional
• shippingMethod - ResourceIdentifier of a ShippingMethod - Optional
• externalTaxRateForShippingMethod - ExternalTaxRateDraft - Optional
  An external tax rate can be set for the shippingMethod if the cart has the External TaxMode.
• custom - CustomFieldsDraft - Optional
  The custom fields.
• locale - String conforming to IETF language tag - Optional
  Must be one of the languages supported for this project.
• deleteDaysAfterLastModification - Number - Optional
  The cart will be deleted automatically if it hasn't been modified for the specified amount of days. If not set, the default value configured in the Project is used.
  If a ChangeSubscription for carts exists, a ResourceDeleted notification will be sent.
• shippingRateInput - ShippingRateInputDraft - Optional
  The shippingRateInput is used as an input to select a ShippingRatePriceTier.
  Based on the definition of ShippingRateInputType. If CartClassificationType is defined, it must be ClassificationShippingRateInput. If CartScoreType is defined, it must be ScoreShippingRateInput. Otherwise it can not bet set.
• origin - CartOrigin - Optional
  The default origin is Customer.
• itemShippingAddresses - Array of AddresseDrafts - Optional
  Contains addresses for carts with multiple shipping addresses. Each address must contain a key which is unique in this cart. Line items will use these keys to reference the addresses under their shippingDetails. The addresses captured here are not used to determine eligible shipping methods or the applicable tax rate. Only the cart's shippingAddress is used for this.
• discountCodes - Array of Strings - Optional
  The code of existing DiscountCodes.

ReplicaCartDraft

Body to create a new cart by replicating an existing cart or order.

• reference - Reference to either a Cart or an Order
• key - String - Optional
  User-specific unique identifier of the cart.

LineItem

A line item is a snapshot of a product variant at the time it was added to the cart. The snapshot is created from the ProductProjection as follows:

• The current projection is used.
• If the cart is bound to a Store
  • For Stores with active Product Selections BETA Product must be included by at least one of the active selections.
  • all LocalizedStrings are filtered according to the locales defined in the store.
  • all Prices are filtered according to the product distribution channels defined in the store. Prices without channel are included.
  • all ProductVariantAvailabilities are filtered according to the inventory supply channels defined in the store. Inventory entries without channel are included.

Since a product variant may change at any time, the ProductVariant data is copied into the field variant. The relation to the current ProductProjection is kept but the line item will not automatically update if the product variant changes. On the cart, the line item can be updated manually. The productSlug refers to the current version of the product. It can be used to link to the product. If the product has been deleted, the line item remains but refers to a non-existent product and the productSlug is left empty.

Please also note that creating an order is impossible if the product or product variant a line item relates to has been deleted.

• id - String
  The unique ID of this LineItem.
• productId - String
• productKey - String - Optional
  User-defined unique identifier for the Product. Only present on Line Items in a Cart when the key is available on that specific Product at the time the Line Item is created or updated on the Cart. On Order resources this field is only present when the key is available on the specific Product at the time the Order is created from the Cart.
  This field is in general not present on Carts that had no updates until 3 December 2021 and on Orders created before this date.
• name - LocalizedString
  The product name.
• productSlug - LocalizedString - Optional
  The slug of a product is inserted on the fly. It can therefore be used to link to the product detail page of the product. It is empty if the product has been deleted.
  The slug is also empty if the cart or order is retrieved via Reference Expansion or is a snapshot in a Message.
• productType - Reference to a ProductType - Optional
• variant - ProductVariant
  The variant data is saved when the variant is added to the cart, and not updated automatically. It can manually be updated with the Recalculate update action.
• price - Price
  The price of a line item is selected from the prices array of the product variant. If the variant field hasn't been updated, the price may not correspond to a price in variant.prices.
• taxedPrice - TaxedItemPrice - Optional
  Set once the taxRate is set.
• totalPrice - CentPrecisionMoney
  The total price of this line item. If the line item is discounted, then the totalPrice is the DiscountedLineItemPriceForQuantity multiplied by quantity. Otherwise the total price is the product price multiplied by the quantity. totalPrice may or may not include the taxes: it depends on the taxRate.includedInPrice property.
• quantity - Number
  The amount of a LineItem in the cart. Must be a positive integer.
• addedAt - DateTime - Optional
  When the line item was added to the cart. Optional for backwards compatibility reasons only.
• state - Array of ItemState
• taxRate -TaxRate - Optional
  Will be set automatically in the Platform TaxMode once the shipping address is set is set. For the External tax mode the tax rate has to be set explicitly with the ExternalTaxRateDraft.
• supplyChannel - Reference to a Channel - Optional
  The supply channel identifies the inventory entries that should be reserved. The Channel must have the InventorySupply ChannelRoleEnum. If the cart is bound to a Store with supplyChannels set, the channel has to match one of the store's supply channels.
• distributionChannel - Reference to a Channel - Optional
  The distribution channel is used to select a ProductPrice. The Channel has ProductDistribution ChannelRoleEnum If the cart is bound to a Store with distributionChannels set, the channel has to match one of the store's distribution channels.
• discountedPricePerQuantity - Array of DiscountedLineItemPriceForQuantity
• priceMode - LineItemPriceMode
• lineItemMode - LineItemMode
• custom - CustomFields - Optional
• shippingDetails - ItemShippingDetails - Optional
  Container for line item specific address(es).
• lastModifiedAt - DateTime - Optional
  The date when the LineItem was last modified by one of the following actions: setLineItemShippingDetails, addLineItem, removeLineItem, or changeLineItemQuantity. Optional only for backwards compatible reasons. When the LineItem is created lastModifiedAt is set to addedAt.

LineItem fields that can be used in query predicates: productId, name, quantity, variant, price, discountedPricePerQuantity.

LineItem Price selection

The price of a LineItem is selected from the prices array of the product variant based on several conditions:

• selection based on the distribution channel, the currency, the country and the customer group

  The selection of the price is based on the provided distributionChannel and on the currency, country, and the customer group of the cart. If a price with an exact match cannot be found, wildcards (all countries, all channels, all CustomerGroups) are used.
  The list below defines how the price is selected. If a price could not be found in one step the rule in the next step will be applied until a price could be found. The priority order for the selection of the price is customer group > channel > country (customer group has the highest priority and country the lowest).
  The price for a specific currency is determined in the following order:

  1. Find a price for the country, customer group and channel.
  2. Find a price for the customer group and channel for all countries.
  3. Find a price for the customer group and country for all channels.
  4. Find a price for the customer group for all channels and all countries.
  5. Find a price for the country and channel for all customer groups.
  6. Find a price for the channel for all customer groups and all countries.
  7. Find a price for the country for all customer groups and all channels.
  8. Find a price for all customer groups, all channels and all countries.

• selection based on the validity period

  For all of the price selection steps, the prices with a validity period are checked before the prices without any validity period.
  If a currently valid price is found, it is used first.

• tier price selection based on the quantity

  If the product Price has some tier prices, the tier price valid for the line item quantity is selected.
  If no tier price can be used, the base Price is used.

LineItemDraft Product Variant identification

To specify which Product Variant is used for the LineItemDraft the variant can be identified either by

• the combination of its product ID and its variant ID, or by
• its SKU.

Choose one of the options below:

Identification by IDs

• productId - String - Required
  ID of an existing Product.
• variantId - Number - Optional
  ID of an existing ProductVariant in the product. If not given, the master variant is used.

Identification by SKU

• sku - String - Required
  SKU of an existing ProductVariant.

LineItemDraft

• LineItemDraft Product Variant identification - Required
• quantity - Number - Optional - Defaults to 1
  The amount of a LineItemin the cart. Must be a positive integer.
• supplyChannel - ResourceIdentifier of a Channel - Optional
  By providing supply channel information, you can unique identify inventory entries that should be reserved. The Channel must have the InventorySupply ChannelRoleEnum
• distributionChannel - ResourceIdentifier of a Channel - Optional
  The channel is used to select a ProductPrice. The Channel must have the ProductDistribution ChannelRoleEnum If the cart is bound to a Store with distributionChannels set, the channel has to match one of the store's distribution channels.
• externalTaxRate - ExternalTaxRateDraft - Optional
  An external tax rate can be set if the cart has the External TaxMode.
• externalPrice - Money - Optional
  Sets the line item price to the given value and sets the line item priceMode to ExternalPrice LineItemPriceMode.
• externalTotalPrice - ExternalLineItemTotalPrice - Optional
  Sets the line item price and totalPrice to the given values and sets the line item priceMode to ExternalTotal LineItemPriceMode.
• custom - CustomFieldsDraft - Optional
  The custom fields.
• shippingDetails - ItemShippingDetailsDraft - Optional
  Container for line item specific address(es).
• addedAt - DateTime - Optional
  When the line item was added to the cart. Defaults to the current date and time.

The logic to select the price is described in LineItem Price selection.

CustomLineItem

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

• id - String
  The unique ID of this CustomLineItem.
• name - LocalizedString
  The name of this CustomLineItem.
• money - TypedMoney
  The cost to add to the cart. The amount can be negative.
• taxedPrice - TaxedItemPrice - Optional
  Set once the taxRate is set.
• totalPrice - CentPrecisionMoney
  The total price of this custom line item. If custom line item is discounted, then the totalPrice would be the discounted custom line item price multiplied by quantity. Otherwise a total price is just a money multiplied by the quantity. totalPrice may or may not include the taxes: it depends on the taxRate.includedInPrice property.
• slug - String
  A unique String in the cart to identify this CustomLineItem.
• quantity - Number
  The amount of a CustomLineItem in the cart. Must be a positive integer.
• state - Array of ItemState
• taxCategory - Reference to a TaxCategory - Optional
• taxRate - TaxRate - Optional
  Will be set automatically in the Platform TaxMode once the shipping address is set is set. For the External tax mode the tax rate has to be set explicitly with the ExternalTaxRateDraft.
• discountedPricePerQuantity- Array of DiscountedLineItemPriceForQuantity
• custom - CustomFields - Optional
• shippingDetails - ItemShippingDetails - Optional
  Container for custom line item specific address(es).

CustomLineItem fields that can be used in query predicates: slug, name, quantity, money, state, discountedPricePerQuantity.

CustomLineItemDraft

• name - LocalizedString
• quantity - Number - Optional - Defaults to 1
  The amount of a CustomLineItem in the Cart. Must be a positive integer.
• money - Money
  The cost to add to the cart. The amount can be negative.
• slug - String
• taxCategory - ResourceIdentifier of a TaxCategory - Required only for Platform TaxMode
  The given tax category will be used to select a tax rate when a cart has the TaxMode Platform.
• externalTaxRate - ExternalTaxRateDraft - Optional
  An external tax rate can be set if the cart has the External TaxMode.
• custom - CustomFieldsDraft - Optional
  The custom fields.
• shippingDetails - ItemShippingDetailsDraft - Optional
  Container for custom line item specific address(es).

ExternalTaxRateDraft

• name - String
• amount - Number - Optional
  Percentage in the range of [0..1]. Must be supplied if no subRates are specified. If subRates are specified then the amount can be omitted or it must be the sum of the amounts of all subRates.
• includedInPrice - Boolean - When true, the line item price is considered the gross price and the amount is applied to calculate the net price. When set to false, the line item price will be considered the net price and the amount will be applied to calculate the gross price. See example of calculation below. The default value for includedInPrice is false.
• country - String
  A two-digit country code as per ISO 3166-1 alpha-2.
• state - String - Optional
  The state in the country
• subRates - Array of SubRate - Optional BETA
  For countries (for example the US) where the total tax is a combination of multiple taxes (for example state and local taxes).

The following example shows the impact of includedInPrice in the cart calculation. The cart has taxMode HalfEven and taxCalculationMode is LineItemLevel.

As seen, when includedInPrice is true, the tax is calculated in a top-down manner. When includedInPrice is false, the tax is calculated in a bottom-up manner.

ExternalTaxAmountDraft

ExternalTaxAmountDraft cannot be used in LineItemDraft or CustomLineItemDraft. It can only be set using the Update Actions for Carts (namely, Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount) or OrderEdits (namely, Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount).

• totalGross - Money
  The total gross amount of the item (totalNet + taxes).
• taxRate - ExternalTaxRateDraft

TaxedPrice

• totalNet - CentPrecisionMoney
• totalGross - CentPrecisionMoney
• taxPortions - Array of TaxPortion

TaxedPrice fields that can be used in query predicates: totalNet, totalGross.

TaxedItemPrice

• totalNet - CentPrecisionMoney
• totalGross - CentPrecisionMoney

TaxedItemPrice fields can not be used in query predicates.

TaxPortion

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 that have the same rate and name will be accumulated to the same tax portion.

• name - String - Optional
• rate - Number
  A number in the range [0..1]
• amount - CentPrecisionMoney

CartState

• Active - The cart can be updated and ordered. It is the default state.
• Merged - Anonymous cart whose content was merged into a customers cart on signin. No further operations on the cart are allowed.
• Ordered - The cart was ordered. No further operations on the cart are allowed.

InventoryMode

Values of the InventoryMode enumeration:

• TrackOnly
  Orders are tracked on inventory. That means, ordering a LineItem will decrement the available quantity on the respective InventoryEntry.
  Creating an order will succeed even if the line item's available quantity is zero or negative. But creating an order will fail with an OutOfStock error if no matching inventory entry exists for a line item.

• ReserveOnOrder
  Creating an order will fail with an OutOfStock error if an unavailable line item exists. However, the following exceptions apply:

  • When any line item's respective InventoryEntry has the restockableInDays value set (including 0), then these line items will not cause an error
    • This is caused when the availableQuantity is insufficient for the ordered line item quantity (the availableQuantity is still updated).

  Note: Line items in the cart are only reserved for the duration of the ordering transaction.

• None
  Adding items to cart and ordering is independent of inventory. No inventory checks or modifications. This is the default mode for a new cart.

TaxMode

Values of the TaxMode enumeration:

• Platform
  The tax rates are selected by the platform from the TaxCategories based on the cart shipping address. The totalNet and totalGross as well as the taxPortions fields are calculated by the platform according to the taxRoundingMode.
• External
  The tax rates are set externally per ExternalTaxRateDraft. A cart with this tax mode can only be ordered if all line items, all custom line items and the shipping method have an external tax rate set. The totalNet and totalGross as well as the taxPortions fields are calculated by the platform according to the taxRoundingMode.
• ExternalAmount
  The tax amounts and the tax rates as well as the tax portions are set externally per ExternalTaxAmountDraft. A cart with this tax mode can only be ordered if the cart itself and all line items, all custom line items and the shipping method have an external tax amount and rate set. Furthermore, update actions on Carts relevant to prices require external recalculation of the total gross. Hence, the ExternalTaxAmount is removed in these cases and requires you to reset them with the appropriate Update Action: Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount.
• Disabled
  No taxes are added to the cart.

RoundingMode

The rounding mode specifies how the platform should round monetary values.
The values of the RoundingMode enumeration:

• HalfEven - Round half to even
  Default rounding mode as used in IEEE 754 computing functions and operators.
• HalfUp - Round half up
• HalfDown - Round half down

Examples how decimal values are rounded:

TaxCalculationMode

The tax calculation mode specifies how the platform performs calculation of taxes.
The values of the TaxCalculationMode enumeration:

• LineItemLevel - Default
  This calculation mode calculates the taxes after the unit price is multiplied with the quantity. For example ($1.08 * 3 = $3.24) * 1.19 = $3.8556 -> $3.86 rounded
• UnitPriceLevel
  This calculation mode calculates the taxes on the unit price before multiplying with the quantity. For example ($1.08 * 1.19 = $1.2852 -> $1.29 rounded) * 3 = $3.87

The combination of UnitPriceLevel and LineItemPriceMode ExternalTotal is not supported.
The API will reject the request with an error message if this combination is used.

Due to the principle of rounding at every calculation step, this slight difference in when to apply the tax can end up having a considerable effect on the cart total. In the following example, we assume that tax of 19% is included in the price for all line items, that the rounding mode is half even and that the price precision is two decimals.

As seen with this example, as long as a line item has quantity of 1, the two modes have no impact on the total net value of a line item (see Line Item #1, 4, and 6). However, as soon as quantity is more than 1, the two modes calculate the total net value of a line item with a difference of several cents (see Line Item #2, 3, and 5). Depending on the specific line item values, the chosen mode can give a greater or lesser net value (see line item #2 compared to #3). Accumulated in the cart total, the difference amounts to 6 cents. The connection to rounding is especially clear with Line Item #5. Due to rounding after applying tax to 0.01 and multiplying with quantity 50 upon that, the net value when using UnitPriceLevel ends up being equal to the gross value. With LineItemLevel, where quantity multiplication is performed as a first calculation step, the rounding occurs to a greater value and net value ends up being $0.42.

LineItemPriceMode

Values of the LineItemPriceMode enumeration:

• Platform
  The price is selected form the product variant. This is the default mode.
• ExternalPrice The line item price was 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 was set externally. Cart discounts are deactivated for the line items with this price mode. Although a line item with this price mode has both price and totalPrice externally set, only totalPrice will be used to calculate the total price of a cart. All update actions that change the quantity of a line item with this price mode can set the new price with the externalTotal field. If the externalTotal field is not given in an update action that changes line item quantity then the external price is unset and the price mode is set back to Platform.

LineItemMode

Values of the LineItemMode enumeration:

• Standard
  The line item was added during cart creation or with the update action addLineItem. Its quantity can be changed without restrictions.
• GiftLineItem
  The line item was added automatically, because a discount has added a free gift to the cart. The quantity can not be increased, and it won't be merged when the same product variant is added. If the gift is removed, an entry is added to the refusedGifts array and the discount won't be applied again to the cart. The price can not be changed externally. All other updates, such as the ones related to custom fields, can be used.

ShippingInfo

• shippingMethodName - String
• price - CentPrecisionMoney
  Determined based on the ShippingRate and its tiered prices, and either the sum of LineItem prices or the shippingRateInput field.
• shippingRate - ShippingRate
  The shipping rate used to determine the price.
• taxedPrice - TaxedItemPrice - Optional
  Set once the taxRate is set.
• taxRate - TaxRate - Optional
  Will be set automatically in the Platform TaxMode once the shipping address is set is set. For the External tax mode the tax rate has to be set explicitly with the ExternalTaxRateDraft.
• taxCategory - Reference to a TaxCategory - Optional
• shippingMethod - Reference to a ShippingMethod - Optional
  Not set if custom shipping method is used.
• deliveries - Array of Delivery
  Deliveries are compilations of information on how the articles are being delivered to the customers.
• discountedPrice - DiscountedLineItemPrice - Optional
• shippingMethodState - ShippingMethodState
  Indicates whether the ShippingMethod referenced in this ShippingInfo is allowed for the cart or not.

DiscountCodeInfo

• discountCode - Reference to a DiscountCode
• state - DiscountCodeState - Optional

DiscountCodeState

Values of the DiscountCodeState enumeration:

• NotActive
  The discount code is not active or it does not contain any active cart discounts.
• NotValid
  The discount code is not valid or it does not contain any valid cart discounts. Validity is determined based on the validFrom and validUntil dates.
• DoesNotMatchCart
  The discount code is active and it contains at least one active and valid CartDiscount. But its cart predicate does not match the cart or none of the contained active discount's cart predicates match the cart
• MatchesCart
  The discount code is active and it contains at least one active and valid CartDiscount. The discount code cartPredicate matches the cart and at least one of the contained active discount's cart predicates matches the cart.
• MaxApplicationReached
  maxApplications or maxApplicationsPerCustomer for discountCode has been reached.
• ApplicationStoppedByPreviousDiscount
  The discount code is active and none of the discounts were applied because the discount application was stopped by one discount that has the StackingMode of StopAfterThisDiscount defined.

ShippingMethodState

Values of the ShippingMethodState enumeration:

• DoesNotMatchCart
  The ShippingMethod predicate does not match the cart. Ordering this cart will fail with error ShippingMethodDoesNotMatchCart.
• MatchesCart
  Either there is no predicate defined for the ShippingMethod or the given predicate matches the cart.

DiscountedLineItemPriceForQuantity

• quantity - Number - Required
• discountedPrice- DiscountedLineItemPrice - Required

DiscountedLineItemPrice

• value - TypedMoney
• includedDiscounts - Array of DiscountedLineItemPortion

DiscountedLineItemPortion

• discount - Reference to a CartDiscount
• discountedAmount - TypedMoney

ExternalLineItemTotalPrice

• price - Money - Required
• totalPrice - CentPrecisionMoneyDraft - Required

ShippingRateInput

ClassificationShippingRateInput

• type - String - "Classification"
• key - String
• label - LocalizedString

ScoreShippingRateInput

• type - String - "Score"
• score - Number

ShippingRateInputDraft

Based on the definition of ShippingRateInputType, only one of the following is allowed. It is not possible to set a value for the shippingRateInput on the cart if CartValue is selected as ShippingRateInputType.

ClassificationShippingRateInput

• type - String - "Classification"
• key - String

ScoreShippingRateInput

• type - String - "Score"
• score - Number

ItemShippingDetails

If multiple shipping addresses are needed for a cart, ItemShippingDetails contains the information where the individual items should be sent to. If needed, it is possible to set different addresses per sub-quantity of a line item. If a quantity in targets is updated to be 0, the target will automatically be removed from a (custom) line item.

• targets - Array of ItemShippingTarget
  Used to map what sub-quantity should be shipped to which address.
  Duplicate address keys are not allowed.
• valid - Boolean
  true if the quantity of the (custom) line item is equal to the sum of the sub-quantities in targets, false otherwise.
  A cart cannot be ordered when the value is false. The error InvalidItemShippingDetails will be triggered.

ItemShippingDetailsDraft

Draft object for ItemShippingDetails.

• targets - Array of ItemShippingTargets
  Used to capture one or more (custom) line item specific shipping addresses. By specifying sub-quantities, it is possible to set multiple shipping addresses for one line item.

A cart can have shippingDetails where the targets sum does not match the quantity of the line item or custom line item. For the order creation and order updates the targets sum must match the quantity.

ItemShippingTarget

Each item shipping target determines the address (as a reference to an address in itemShippingAddresses) and the quantity that should be shipped to this address. Should multiple shipping addresses be needed for one (custom) line item, sub-quantities are specified. Thus, an array of addresses and sub-quantities is stored per (custom) line item. Upon order creation, the sum of sub-quantities must add up to the total quantity of the (custom) line item.

• addressKey - String
  The key of the address in the cart's itemShippingAddresses
• quantity - Number
  The quantity of items that should go to the address with the specified addressKey.
  Only positive values are allowed. Using 0 as quantity is also possible in a draft object, but the element will not be present in the resulting ItemShippingDetails.

CartOrigin

Values of the CartOrigin enumeration:

• Customer
  The cart was created by the customer. This is the default value.
• Merchant
  The cart was created by the merchant on behalf of the customer.

Get a Cart

Get a Cart by ID

Endpoint: /{projectKey}/carts/{id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: Cart

The cart may not contain up-to-date prices, discounts etc. If you want to ensure they're up-to-date, send an Update request with the Recalculate update action instead.

Get a Cart by Key

Endpoint: /{projectKey}/carts/key={key}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: Cart

Get a cart by its key.

The cart may not contain up-to-date prices, discounts etc. If you want to ensure they're up-to-date, send an Update request with the Recalculate update action instead.

Get a Cart in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/{id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}
Response Representation: Cart

Returns a cart by its ID from a specific Store. The {storeKey} path parameter maps to a Store's key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

The cart may not contain up-to-date prices, discounts etc. If you want to ensure they're up-to-date, send an Update request with the Recalculate update action instead.

Get a Cart in a Store by Key

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/key={key}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}
Response Representation: Cart

Returns a cart by its key from a specific Store. The {storeKey} path parameter maps to a Store's key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

The cart may not contain up-to-date prices, discounts etc. If you want to ensure they're up-to-date, send an Update request with the Recalculate update action instead.

Get a Cart by Customer ID

Endpoint: /{projectKey}/carts/customer-id={id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: Cart

Retrieves the active cart of the customer that has been modified most recently. It does not consider carts with CartOrigin Merchant. If no active cart exists, a 404 Not Found error is returned.

The cart may not contain up-to-date prices, discounts etc. If you want to ensure they're up-to-date, send an Update request with the Recalculate update action.

Get a Cart in a Store by Customer ID

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/customer-id={id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}
Response Representation: Cart

Retrieves the active cart of the customer that has been modified most recently in a specific Store. The {storeKey} path parameter maps to a Store's key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

The cart may not contain up-to-date prices, discounts etc. If you want to ensure they're up-to-date, send an Update request with the Recalculate update action.

Query Carts

Query Carts

Endpoint: /{projectKey}/carts
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Cart
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Query Carts in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/carts
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with results containing an array of Cart
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Queries carts in a specific Store. The {storeKey} path parameter maps to a Store's key.

Create a Cart

Create a Cart

Endpoint: /{projectKey}/carts
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Request Representation: CartDraft
Response Representation: Cart

Creating a cart can fail with an InvalidOperation if the referenced shipping method in the CartDraft has a predicate which does not match the cart.

Create a Cart in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/carts
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Request Representation: CartDraft
Response Representation: Cart

Creates a cart in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

When using this endpoint the cart's store field is always set to the store specified in the path parameter.

Creating a cart can fail with an InvalidOperation if the referenced shipping method in the CartDraft has a predicate which does not match the cart.

Update a Cart

After all update actions have been performed, the cart will also:

• Remove any line items that are invalid (due to removed products, product variants, or prices)
• Update any line item price fields if the result of the price selection has changed because of a product update
• Update the ShippingInfo, in particular the price and shippingMethodState fields
• Update the discounts, which may affect the totalPrice fields of (custom) line items and the discountedPrice field of the shipping info
• Update the totalPrice field of the cart
• Update the tax rates, in particular the taxedPrice fields
• Update the productKey on line items

If you want to perform the updates mentioned above without additional update actions, you can send a request with only the Recalculate update action.

To update the product data saved in the line items, use the Recalculate update action with updateProductData set to true.

Update a Cart by ID

Endpoint: /{projectKey}/carts/{id}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Response Representation: Cart
Fields:

• version - Number - Required
  The expected version of the cart on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the cart.

Update a Cart by Key

Endpoint: /{projectKey}/carts/key={key}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Response Representation: Cart
Fields:

• version - Number - Required
  The expected version of the cart on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the cart.

Updates the cart by its key.

Update a Cart in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/{id}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Response Representation: Cart
Fields:

• version - Number - Required
  The expected version of the cart on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the cart.

Updates a cart in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Update a Cart in a Store by Key

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/key={key}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Response Representation: Cart
Fields:

• version - Number - Required
  The expected version of the cart on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the cart.

Updates a cart in the store specified by {storeKey} and Cart key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Update actions

Set Key

• action - String - "setKey"
• key - String - Optional
  If key is absent or null, the existing key, if any, will be removed.

UpdateAction on line item

Add LineItem

Remove LineItem

Change LineItem Quantity

Set LineItem TaxRate

Set LineItem TaxAmount

Set LineItem Price

Set LineItem TotalPrice

Set LineItem DistributionChannel

Set LineItem SupplyChannel

Sets the supply channel of the given LineItem.

• action - String - "setLineItemSupplyChannel"
• lineItemId - String - Required
  ID of an existing LineItem in the cart.
• supplyChannel - ResourceIdentifier of a Channel - Optional
  If present a Reference to the channel will be 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. Performing this action has no impact on inventory that should be reserved.

Set LineItem Custom Type

This action sets, overwrites, or removes the custom type and fields for an existing LineItem.

• action - String - "setLineItemCustomType"
• type - ResourceIdentifier of a Type - Optional
  If set, the custom type is set to this new value.
  If absent, the custom type and any existing CustomFields are removed at the same time.
• lineItemId - String
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
  If set, the custom fields are set to this new value.

Set LineItem CustomField

Apply DeltaToLineItemShippingDetailsTargets

Increases or decreases the shipping details, the amount of items going to which address, for a line item. See SetLineItemShippingDetails to override the shipping details.

• action - String - "applyDeltaToLineItemShippingDetailsTargets"
• lineItemId - String
  The ID of the line item that is to be updated.
• targetsDelta - Array of ItemShippingTarget
  Using positive quantities will increase the amount of items which should go to an address, and negative quantities decrease the amount.

Set LineItemShippingDetails

UpdateAction on custom line item

Add CustomLineItem

Remove CustomLineItem

Change CustomLineItem Quantity

Change CustomLineItem Money

Set CustomLineItem Custom Type

Set CustomLineItem CustomField

Set CustomLineItem TaxRate

Set CustomLineItem TaxAmount

Apply DeltaToCustomLineItemShippingDetailsTargets

Increases or decreases the shipping details, the amount of items going to which address, for a line item.

• action - String - "applyDeltaToCustomLineItemShippingDetailsTargets"
• customLineItemId - String
  The ID of the custom line item that is to be updated.
• targetsDelta - Array of ItemShippingTarget
  Using positive quantities will increase the amount of items which should go to an address, and negative quantities decrease the amount.

Set CustomLineItemShippingDetails

Set Customer Email

• action - String - "setCustomerEmail"
• email - String - Optional

Set Shipping Address

Sets the shipping address of the cart. Setting the shipping address also sets the TaxRate of the line items and calculates the TaxedPrice. If the address is not provided, the shipping address is unset, the taxedPrice is unset and the taxRates are unset in all line items.

• action - String - "setShippingAddress"
• address - AddressDraft - Optional

Extended flexibility on taxRates selection is possible when countryTaxRateFallbackEnabled project setting is set to true, which allows shipping to states not explicitly covered inside a country. For more information, see changeCountryTaxRateFallbackEnabled.

Specific Error Codes:

• MissingTaxRateForCountry
  You could changeCountryTaxRateFallbackEnabled to allow extended tax rate selection.

Set Billing Address

• action - String - "setBillingAddress"
• address - AddressDraft - Optional

Set Country

Set ShippingMethod

Set Custom ShippingMethod

Add DiscountCode

Remove DiscountCode

Set Customer Group

Set Custom Type

Set CustomField

Set Shipping Address Custom Type

Set Shipping Address CustomField

Set Billing Address Custom Type

Set Billing Address CustomField

Set ItemShipping Address Custom Type

Set ItemShipping Address CustomField

Set Delivery Address Custom Type

Set Delivery Address CustomField

Set ShippingMethod TaxAmount

Set ShippingMethod TaxRate

Change TaxMode

Change Tax RoundingMode

Set ShippingRateInput

Change TaxCalculationMode

Add Shopping List

Set Customer ID

Sets the customer ID of the cart. When the customer ID is set, the LineItem prices are updated.

• action - String - "setCustomerId"
• customerId - String - Optional
  If set, a customer with the given ID must exist in the project.

Specific Error Codes:

• MissingTaxRateForCountry

Set Anonymous ID

Sets the anonymous ID of the cart.

• action - String - "setAnonymousId"
• anonymousId - String - Optional
  If not set, any existing anonymous ID will be removed.

Recalculate

This update action has two use cases:

• Updating the product data that is saved in line items

• Updating prices, discounts etc. as done on every update, but without sending additional update actions

  • action - String - "recalculate"
  • updateProductData - Boolean - Optional, defaults to false
    If set to true, the line item product data (name, variant and productType) will also be updated. If set to false, only the prices and tax rates of the line item will be updated. The updated price of a line item may not correspond to a price in variant.prices anymore.

Add Payment

This action adds a payment to the PaymentInfo. The payment must not be assigned to another Order or active Cart yet.

• action - String - "addPayment"
• payment - Reference to a Payment

Remove Payment

This action removes a payment from the PaymentInfo.

• action - String - "removePayment"
• payment - Reference to a Payment

Set Cart Total Tax

The total tax amount of the cart can be set if it has the ExternalAmount TaxMode.

• action - String - "setCartTotalTax"
• externalTotalGross - Money
  The total gross amount of the cart (totalNet + taxes).
• externalTaxPortions - Array of TaxPortion - Optional

Set Locale

Sets the locale. Must be one of the languages supported for this Project.

• action - String - "setLocale"
• locale - String conforming to IETF language tag - Optional

Set DeleteDaysAfterLastModification

Sets deleteDaysAfterLastModification. The cart will be deleted automatically if it hasn't been modified for the specified amount of days. If a ChangeSubscription for carts exists, a ResourceDeleted notification will be sent.

• action - String - "setDeleteDaysAfterLastModification"
• deleteDaysAfterLastModification - Number - Optional

Add ItemShippingAddress

Remove ItemShippingAddress

Update ItemShippingAddress

Overview of update actions for Cart, Order and OrderEdit

Replicate an existing cart or order to a new cart

Creating a new cart by replicating an existing cart or order can be useful in case a customer wants to cancel a recent order to make some changes, or if a previous order should be ordered again.

The replica will attempt to preserve customer information, line items and custom line items, custom fields, discount codes, as well as other settings of the cart or order. If any of the line items have become invalid, for example due to removed products or prices, those items are removed from the new cart. If the customer has switched to another customer group, the new cart contains the new group.

The replica 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 the initial state.

Replicate a Cart

Endpoint: /{projectKey}/carts/replicate
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Request Representation: ReplicaCartDraft
Response Representation: Cart

The replica will not be bound to any store.

Replicate a Cart in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/replicate
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Request Representation: ReplicaCartDraft
Response Representation: Cart

The replica will be bound to the same store.

Delete a Cart

Delete a Cart by ID

Endpoint: /{projectKey}/carts/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}
Response Representation: Cart
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Removes a Cart.

Delete a Cart by Key

Endpoint: /{projectKey}/carts/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}
Response Representation: Cart
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Removes a Cart by its key.

Delete a Cart in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Response Representation: Cart
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Removes a Cart in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Delete a Cart in a Store by Key

Endpoint: /{projectKey}/in-store/key={storeKey}/carts/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Response Representation: Cart
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Removes a Cart in the store specified by {storeKey} and Cart key.
The {storeKey} path parameter maps to a Store's key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.