Carts

A shopping cart holds product variants and can be ordered. Each cart either belongs to a registered customer or is an anonymous cart.

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.
  • version - Number
    The current version of the cart.
  • 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).
  • lineItems - Array of LineItem
  • customLineItems - Array of CustomLineItem
  • totalPrice - Money
    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 beta
    The cart will be deleted automatically if it hasn’t been modified for the specified amount of days and it is in the Active CartState.
  • 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.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • 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.

Prices precision:

  • Prices have a cent-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) the tax portions are derived from the gross prices. This only applies when the Platform TaxMode is used.
  • When prices that were discounted with relative discounts, they are always rounded in favor of the customer with the half down rounding.

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 .
  • customerId - String - Optional
    Id of an existing Customer.
  • customerEmail - String - Optional
  • customerGroup - Reference to 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).
  • 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 - 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
  • shippingMethod - Reference to 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 beta
    The cart will be deleted automatically if it hasn’t been modified for the specified amount of days and it is in the Active CartState. 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 CartClassification is defined, it must be ClassificationShippingRateInput. If CartScore is defined, it must be ScoreShippingRateInput. Otherwise it can not bet set.
  • origin - CartOrigin - Optional
    The default origin is Customer.
  • itemShippingAddresses - Array of Addresses - 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.

LineItem

A line item is a snapshot of a product variant at the time it was added to the cart.

Since a product variant may change at any time, the ProductVariant data is copied into the field variant. The relation to the Product 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.

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 Selection

The product variant to be selected in the LineItemDraft can be specified either by its product ID plus variant ID or by its SKU.
Choose one of the options below:

Selection 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.
Selection by SKU

LineItemDraft

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.

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

CustomLineItemDraft

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.
  • 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 (e.g. the US) where the total tax is a combination of multiple taxes (e.g. state and local taxes).

External TaxRates are never included in the price, therefore includedInPrice will be set to false automatically.

ExternalTaxAmountDraft

TaxedPrice

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

TaxedItemPrice

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

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

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

Examples 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

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. E.g. ($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. E.g. ($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.

LineItem # Quantity Unit Price Line Item Total Net when LineItemLevel Line Item Total Net when UnitPriceLevel Line Item Total Gross
1 1 $1.00 $0.84 $0.84 $1.00
2 10 $1.08 $9.08 $9.10 $10.80
3 10 $108.08 $908.24 $908.20 $1080.80
4 1 $2.00 $1.68 $1.68 $2.00
5 50 $0.01 $0.42 $0.50 $0.50
6 1 $4.90 $4.12 $4.12 $4.90
Cart Net Total when
LineItemLevel
Cart Net Total when UnitPriceLevel Cart Gross Total
$924.38 $924.44 $1100.00

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

DiscountCodeInfo

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

DiscountedLineItemPrice

DiscountedLineItemPortion

ExternalLineItemTotalPrice

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

ShippingRateInput

ClassificationShippingRateInput

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.

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 Cart by ID

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

Get Cart by Customer ID

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.

Endpoint: /{projectKey}/carts/?customerId={id}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: Cart

Query Carts

Endpoint: /{projectKey}/carts
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of Cart
Query Parameters:

Create Cart

Endpoint: /{projectKey}/carts
Method: POST
OAuth2 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.

Update Cart

Endpoint: /{projectKey}/carts/{id}
Method: POST
OAuth2 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 Actions
Please find below the individual update actions provided on this endpoint.


UpdateAction on line item

Add LineItem

Adds a product variant in the given quantity to the cart.

If the cart already contains a line item for the same product variant with the same LineItemMode, custom fields, supply and distribution channel, then only the quantity of the existing LineItem is increased. If shippingDetails are set, they will be merged, meaning 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 will always be added when the externalPrice or the externalTotalPrice is set in this update action.
The LineItem price is set as described in LineItem Price selection.

Remove LineItem

Decreases the quantity of the given LineItem. The LineItem price is updated as described in LineItem Price selection.

  • action - String - "removeLineItem"
  • lineItemId - String - Required
    Id of an existing LineItem in the cart.
  • quantity - Number - Optional If the quantity is absent or the line item quantity drops to less than 1, the line item is removed from the cart.
  • externalPrice - Money - Optional
    Sets the line item price to the given value when decreasing the quantity of a line item with the ExternalPrice LineItemPriceMode priceMode.
  • externalTotalPrice - ExternalLineItemTotalPrice - Optional
    Sets the line item price and totalPrice to the given values when decreasing the quantity of a line item with the ExternalTotal LineItemPriceMode priceMode.
  • shippingDetailsToRemove - ItemShippingDetailsDraft - Optional
    Container for line item specific address(es) that are to be removed.

Change LineItem Quantity

Sets the quantity of the given LineItem.
If quantity is 0, the line item is removed from the cart.
The LineItem price is updated as described in LineItem Price selection.

ChangeLineItemQuantity does not support changing the shipping details when multiple shipping addresses are set for one line item. RemoveLineItem and AddLineItem support this, but not ChangeLineItem. This is the case because it is not possible to deduct how the distribution of sub-quantities should be adapted in accordance with the overall change in the line item quantity. Thus, the shippingDetails field will be kept in its current state in order to avoid data loss. Use SetLineItemShippingDetails in combination with this update action in one cart update command to change the line item quantity and shipping details together.

  • action - String - "changeLineItemQuantity"
  • lineItemId - String - Required
    Id of an existing LineItem in the cart.
  • quantity - Number - Required
  • externalPrice - Money - Optional
    Sets the line item price to the given value when changing the quantity of a line item with the ExternalPrice LineItemPriceMode priceMode.
  • externalTotalPrice - ExternalLineItemTotalPrice - Optional
    Sets the line item price and totalPrice to the given values when changing the quantity of a line item with the ExternalTotal LineItemPriceMode priceMode.

Set LineItem TaxRate

A line item tax rate can be set if the cart has the External TaxMode.

  • action - String - "setLineItemTaxRate"
  • lineItemId - String
  • externalTaxRate - ExternalTaxRateDraft - Optional

Set LineItem TaxAmount

A line item tax amount can be set if the cart has the ExternalAmount TaxMode.

  • action - String - "setLineItemTaxAmount"
  • lineItemId - String
  • externalTaxAmount - ExternalTaxAmountDraft - Optional

Set LineItem TotalPrice

Sets the totalPrice and price of a line item and changes the priceMode of the line item to ExternalTotal LineItemPriceMode. If the price mode of the line item is ExternalTotal and no externalTotalPrice is given, the external price is unset and the priceMode is set to Platform.

Set LineItem Price

Sets the price of a line item and changes the priceMode of the line item to ExternalPrice LineItemPriceMode. If the price mode of the line item is ExternalPrice and no externalPrice is given, the external price is unset and the priceMode is set to Platform.

  • action - String - "setLineItemPrice"
  • lineItemId - String
  • externalPrice - Money - Optional

Set LineItem Custom Type

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

  • action - String - "setLineItemCustomType"
  • type - ResourceIdentifier to 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

This action sets, overwrites or removes any existing custom field for an existing LineItem.

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

Sets the ItemShippingDetails for a line item.

  • action - String - "setLineItemShippingDetails"
  • lineItemId - String
    The ID of the line item that is to be updated.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    The new shipping details for the line item.

UpdateAction on custom line item

Add CustomLineItem

Adds a CustomLineItem to the cart.

If the cart already contains a CustomLineItem with the same slug, name, money, tax category, state, and custom fields, then only the quantity of the existing custom line item is increased. If shippingDetails are set, they will be merged, meaning all addresses will be present afterwards and, for address keys present in both shipping details, the quantity will be 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.

  • action - String - "addCustomLineItem"
  • name - LocalizedString
  • quantity - Number - Optional - Defaults to 1
  • money - Money
  • slug - String
  • taxCategory - Reference to a TaxCategory - Required only for Platform TaxMode
    The given tax category will be used to select a tax rate when a cart has the tax mode 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).

Remove CustomLineItem

Removes the custom CustomLineItem from the cart.

Removing a custom line item does not support specifying a quantity, unlike the removal of line items. Consequently, there is no support to partially remove shippingDetails using this update action. See Change CustomLineItem Quantity for that.

  • action - String - "removeCustomLineItem"
  • customLineItemId - String - Required
    ID of an existing CustomLineItem in the cart.

Change CustomLineItem Quantity

Sets the quantity of the given CustomLineItem.

ChangeCustomLineItemQuantity does not support changing the shipping details when multiple shipping addresses are set for one custom line item. AddCustomLineItem support this. This is the case because it is not possible to deduct how the distribution of sub-quantities should be adapted in accordance with the overall change in the custom line item quantity. Thus, the shippingDetails field will be kept in its current state in order to avoid data loss. Use SetCustomLineItemShippingDetails in combination with this update action in one cart update command to change the custom line item quantity and shipping details together.

  • action - String - "changeCustomLineItemQuantity"
  • customLineItemId - String - Required
    ID of an existing CustomLineItem in the cart.
  • quantity - Number - Required
    The new quantity being a value >= 0. If quantity is 0, the custom line item will be removed from the cart.

Change CustomLineItem Money

Sets the money of the given CustomLineItem.

  • action - String - "changeCustomLineItemMoney"
  • customLineItemId - String - Required
    ID of an existing CustomLineItem in the cart.
  • money - Money - Required
    The new money.

Set CustomLineItem TaxRate

A custom line item tax rate can be set if the cart has the External TaxMode.

  • action - String - "setCustomLineItemTaxRate"
  • customLineItemId - String
  • externalTaxRate - ExternalTaxRateDraft - Optional

Set CustomLineItem TaxAmount

A custom line item tax amount can be set if the cart has the ExternalAmount TaxMode.

  • action - String - "setCustomLineItemTaxAmount"
  • customLineItemId - String
  • externalTaxAmount - ExternalTaxAmountDraft - Optional

Set CustomLineItem Custom Type

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

  • action - String - "setCustomLineItemCustomType"
  • type - ResourceIdentifier to 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.
  • customLineItemId - 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 CustomLineItem CustomField

This action sets, overwrites or removes any existing custom field for an existing CustomLineItem.

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

Sets the ItemShippingDetails for a custom line item.

  • action - String - "setCustomLineItemShippingDetails"
  • customLineItemId - String
    The ID of the custom line item that is to be updated.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    The new shipping details for the custom line item.

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 - Address - Optional

Set Billing Address

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

Set Country

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

  • action - String - "setCountry"
  • country - String - Optional
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .

Set ShippingMethod

Sets the ShippingMethod. Prerequisite: The cart must contain a shipping address. This update action can fail with an InvalidOperation if the referenced shipping method has a predicate which does not match the cart.

Set Custom ShippingMethod

Sets a custom shipping method (independent of the ShippingMethods defined in the project). The custom shipping method can be unset with the setShippingMethod action without the shippingMethod. Prerequisite: The cart must contain a shipping address.

  • action - String - "setCustomShippingMethod"
  • shippingMethodName - String - Required
  • shippingRate - ShippingRate
    The shipping rate used to determine the price.
  • taxCategory - Reference to a TaxCategory - Optional
    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.

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.

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.

Set Customer Group

Sets the customer group of the cart. The LineItem prices will be updated according to the customer group.
This action cannot be used if a customer is assigned to the cart. In that case the platform will automatically select the customer group the respective customer is assigned to.

Add DiscountCode

Adds a DiscountCode to the cart to enable the related CartDiscounts.

  • action - String - "addDiscountCode"
  • code - String - Required
    The code of an existing DiscountCode.

The number of discount codes in a cart is limited to 10.

Remove DiscountCode

Removes a discount code from the cart.

Recalculate

Updates the tax rates, the prices and optionally the line item product data.

If any of the line items are invalid, e.g. due to removed products or prices, those items will be removed from the cart. The recalculation will proceed with the remaining items.

It is recommended to set updateProductData to true. The default is false for backward compatibility.

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

Set Custom Type

This action sets, overwrites or removes any existing custom type and fields for an existing cart.

  • action - String - "setCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • 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 CustomField

This action sets, overwrites or removes any existing custom field for an existing cart.

Add Payment beta

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

Remove Payment beta

This action removes a payment from the PaymentInfo.

Set ShippingMethod TaxRate

A shipping method tax rate can be set if the cart has the External TaxMode.

Set ShippingMethod TaxAmount

A shipping method tax amount can be set if the cart has the ExternalAmount TaxMode.

Change TaxMode

Changes the TaxMode of a cart. When a tax mode is changed from External to Platform or Disabled, all previously set external tax rates will be removed. When changing the tax mode to Platform, line items, custom line items and shipping method require a tax category with a tax rate for the given shipping address.

  • action - String - "changeTaxMode"
  • taxMode - TaxMode

Change Tax RoundingMode

Changes the tax RoundingMode of a cart. When changing the tax rounding mode, the taxes are recalculated.

  • action - String - "changeTaxRoundingMode"
  • taxRoundingMode - RoundingMode

Change TaxCalculationMode

Changes the TaxCalculationMode of a cart. When changing the tax calculation mode, the taxes are recalculated.

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.

Add Shopping List beta

Adds all LineItems of a ShoppingList to the cart.

Set DeleteDaysAfterLastModification beta

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

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

Set ShippingRateInput

The shippingRateInput is used as an input to select a ShippingRatePriceTier. If no matching tier can be found, or the input is not set, the default price is used.

Add ItemShippingAddress

Add an address to the itemShippingAddresses array of the cart.

  • action - String - "addItemShippingAddress"
  • address - Address
    The address must have a key that is unique in this cart

Remove ItemShippingAddress

Removes an address from the itemShippingAddresses array of the cart. An address can only be removed if it is not referenced in any ItemShippingTarget.

  • action - String - "removeItemShippingAddress"
  • addressKey - String
    The key of the address that is to be removed

Update ItemShippingAddress

Updates an address in the itemShippingAddresses array of this cart.

  • action - String - "updateItemShippingAddress"
  • address - Address
    The address which is to replace the address with the key already present in the array

Delete Cart

Removes a Cart. If it was assigned to a Customer, a new cart can be created for this customer.

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

  • version - Number - Required