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

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.

Prices precision:

CartDraft

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

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:

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

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.

CartState

InventoryMode

Values of the InventoryMode enumeration:

TaxMode

Values of the TaxMode enumeration:

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:

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:

LineItemMode

Values of the LineItemMode enumeration:

ShippingInfo

DiscountCodeInfo

DiscountCodeState

Values of the DiscountCodeState enumeration:

ShippingMethodState

Values of the ShippingMethodState enumeration:

DiscountedLineItemPriceForQuantity

DiscountedLineItemPrice

DiscountedLineItemPortion

ExternalLineItemTotalPrice

ShippingRateInput

ClassificationShippingRateInput

ScoreShippingRateInput

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

ScoreShippingRateInput

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

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

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.

Set LineItem TaxRate

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

Set LineItem TaxAmount

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

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.

Set LineItem Custom Type

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

Set LineItem CustomField

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

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 the cart already contains a custom line item with the same slug that is otherwise not identical, an InvalidOperation error is returned.

Remove CustomLineItem

Removes the custom CustomLineItem from the cart.

Change CustomLineItem Quantity

Sets the quantity of the given CustomLineItem.

Change CustomLineItem Money

Sets the money of the given CustomLineItem.

Set CustomLineItem TaxRate

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

Set CustomLineItem TaxAmount

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

Set CustomLineItem Custom Type

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

Set CustomLineItem CustomField

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

Set Customer Email

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.

Set Billing Address

Set Country

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

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.

Set Customer ID

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

Set Anonymous ID

Sets the anonymous ID of the cart.

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.

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.

Set Custom Type

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

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.

Change Tax RoundingMode

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

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.

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.

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.

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: