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.

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.

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

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.

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

A rounding mode specifies how the platform should round monetary values.
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

LineItemPriceMode

Values of the LineItemPriceMode enumeration:

ShippingInfo

DiscountCodeInfo

DiscountCodeState

Values of the DiscountCodeState enumeration:

DiscountedLineItemPriceForQuantity

DiscountedLineItemPrice

DiscountedLineItemPortion

ExternalLineItemTotalPrice

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

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 custom fields, supply and distribution channel, then only the quantity of the existing LineItem is increased.
The LineItem price is set as described in LineItem Price selection.

Remove LineItem

Decreases the quantity of the given LineItem.
If the quantity is absent or the updated quantity is less than 1, the line item is removed from the cart.
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 TotalPrice

Sets the totalPrice and price of the line item and changes the priceMode of the line item to ExternalTotal. If the external total price of the line item was already set and the externalTotalPrice field of this update action is not given, the external price is unset and the line item price mode is set back to Platform. Although both price and totalPrice are set with this update action, only totalPrice will be used to calculate the total price of the cart.

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.

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

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.

Add DiscountCode

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

Remove DiscountCode

Removes a discount code from the cart.

Recalculate

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

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.

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.

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.

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: