Queries and mutations for managing Carts in the platform.

To access Carts as an Associate of a Business Unit, see AsAssociateArgument.

Queries

Query Carts

QUERYcarts
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Cart

QUERYcart
Arguments
id​
String​
Output:Cart

Get active Cart

QUERYcustomerActiveCart
Arguments
customerId​
String​
Output:Cart

Mutations

Create Cart

MUTATIONcreateCart
Arguments
draft​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

asAssociate​

Create/modify entity as an associate in business-unit.

Output:Cart

Update Cart

MUTATIONupdateCart
Arguments
version​
Long​
actions​
Array of CartUpdateAction​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

asAssociate​

Create/modify entity as an associate in business-unit.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Cart

Delete Cart

MUTATIONdeleteCart
Arguments
version​
Long​
personalDataErasure​
Boolean​
Default: false​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

asAssociate​

Create/modify entity as an associate in business-unit.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Cart

Output types

Cart

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

customerId​
String​
id of the Customer that the Cart belongs to.
customer​
customerEmail​
String​

Email address of the Customer that the Cart belongs to.

anonymousId​
String​
Anonymous session associated with the Cart.
lineItems​
Array of LineItem​
Line Items added to the Cart.
customLineItems​
Array of CustomLineItem​
Custom Line Items added to the Cart.
totalPrice​
Sum of the totalPrice field of all LineItems and CustomLineItems, and if available, the price field of ShippingInfo. If a discount applies on totalPrice, this field holds the discounted value.
Taxes are included if TaxRate includedInPrice is true for each price.
taxedPrice​
  • For a Cart with Platform TaxMode, it is automatically set when a shipping address is set. For Carts with Multiple ShippingMode, all Line Items and Custom Line Items must be fully distributed between the Shipping Methods (via shippingDetails), otherwise taxedPrice is not automatically set.
  • For a Cart with External TaxMode, it is automatically set when shippingAddress and external Tax Rates for all Line Items, Custom Line Items, and Shipping Methods in the Cart are set. For Carts with Multiple ShippingMode, all allocations must have their respective tax rates present in perMethodTaxRate, otherwise taxedPrice is not automatically set.
If a discount applies on totalPrice, this field holds the proportionally discounted value.
discountOnTotalPrice​
Discounts that apply on the Cart totalPrice.
shippingAddress​
Shipping address for a Cart with Single ShippingMode. Determines eligible ShippingMethod rates. For a Cart with Platform TaxMode, it also determines Tax Rates of Line Items.
billingAddress​

Billing address associated with the Cart.

inventoryMode​

Indicates how stock quantities are tracked for Line Items in the Cart.

Can be None, TrackOnly, ReserveOnOrder, or ReserveOnCart​
taxMode​

Indicates how Tax Rates are set.

Can be Disabled, External, ExternalAmount, or Platform​
priceRoundingMode​
Indicates how the total prices on LineItems and CustomLineItems are rounded when calculated. Configured in Project settings.
Can be HalfDown, HalfEven, or HalfUp​
taxRoundingMode​
Indicates how monetary values are rounded when calculating taxes for taxedPrice. Configured in Project settings.
Can be HalfDown, HalfEven, or HalfUp​
taxCalculationMode​
Indicates how taxes are calculated when calculating taxes for taxedPrice.
Can be LineItemLevel, or UnitPriceLevel​
customerGroup​
Reference to the Customer Group of the Customer that the Cart belongs to. Used for Line Item price selection.
customerGroupRef​
Reference to the Customer Group of the Customer that the Cart belongs to. Used for Line Item price selection.
country​
shippingKey​
String​
User-defined unique identifier of the Shipping Method in a Cart with Single ShippingMode.
shippingInfo​
Shipping-related information of a Cart with Single ShippingMode. Automatically set when a Shipping Method is set.
discountCodes​
Array of DiscountCodeInfo​

Discount Codes applied to the Cart.

If directDiscountsIgnoreCartDiscounts is true, a Cart that has directDiscounts cannot have discountCodes.
directDiscounts​
Array of DirectDiscount​

Direct Discounts added to the Cart.

If directDiscountsIgnoreCartDiscounts is true, a Cart that has discountCodes cannot have directDiscounts.
refusedGifts​
Array of CartDiscount​
Automatically set when a Line Item with GiftLineItem LineItemMode is removed from the Cart.
refusedGiftsRefs​
Array of Reference​
Automatically set when a Line Item with GiftLineItem LineItemMode is removed from the Cart.
paymentInfo​

Payment information related to the Cart.

locale​
Language of the Cart. Must be one of the languages supported by the Project.
shippingRateInput​
Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
origin​

Indicates how the Cart was created.

Can be Customer, Merchant, Quote, or RecurringOrder​
storeRef​
Reference to a Store the Cart belongs to.
store​
Reference to a Store the Cart belongs to.
itemShippingAddresses​
Array of Address​
Additional shipping addresses of the Cart as specified by LineItems using the shippingDetails field.
For Carts with Single ShippingMode: eligible Shipping Methods or applicable Tax Rates are determined by the address in shippingAddress, and not itemShippingAddresses.
businessUnit​
Reference to a Business Unit the Cart belongs to. Only available for B2B-enabled Projects.
businessUnitRef​
Reference to a Business Unit the Cart belongs to. Only available for B2B-enabled Projects.
shipping​
Array of Shipping​
Shipping-related information of a Cart with Multiple ShippingMode. Updated automatically each time a new Shipping Method is added.
taxedShippingPrice​
Sum of the taxedPrice field of ShippingInfo across all Shipping Methods.
If a discount applies on totalPrice, this field holds the proportionally discounted value.
shippingMode​

Indicates whether the Cart has one or multiple Shipping Methods.

Can be Multiple, or Single​
shippingCustomFields​
Custom Fields of the Shipping Method in a Cart with Single ShippingMode.
placement​
Can be InStore, or Online​
discountTypeCombination​

Indicates if a combination of discount types can apply on a Cart.

cartState​

Current status of the Cart.

Can be Active, Frozen, Merged, or Ordered​
key​
String​

User-defined unique identifier of the Cart.

purchaseOrderNumber​
String​

User-defined identifier of a purchase order.

It is typically set by the Buyer or Merchant to track the purchase order during the quote and order flow.
directDiscountsIgnoreCartDiscounts​
Boolean​
  • If true, only Direct Discounts apply to the Cart. Matching Cart Discounts are ignored, and Discount Codes cannot be added.
  • If false, Cart Discounts, Discount Codes, and Direct Discounts apply to the Cart.
lock​
Indicates whether the Cart has been locked, preventing edits.
custom​

Custom Fields of the Cart.

deleteDaysAfterLastModification​
Int​
Number of days after the last modification before a Cart is deleted. Configured in Project settings.
totalLineItemQuantity​
Long​
Sum of all LineItem quantities, excluding CustomLineItems. Only present when the Cart has at least one LineItem.
recurringPaymentConfiguration​
Determines how the Orders generated by a RecurringOrder based on this Cart are paid for. Only evaluated on Carts with the RecurringOrder CartOrigin.
freezeStrategy​
Determines freezing behavior when cartState is Frozen.
Can be HardFreeze, or SoftFreeze​
warnings​
Array of TypedWarning​

Warnings from the latest cart mutation. Not persisted and only available in mutation responses.

id​
String​

Unique identifier of the Cart.

version​
Long​

Current version of the Cart.

createdAt​

Date and time (UTC) the Cart was initially created.

lastModifiedAt​

Date and time (UTC) the Cart was last updated.

createdBy​

IDs and references that created the Cart.

lastModifiedBy​

IDs and references that last modified the Cart.

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.

id​
String​

Unique identifier of the LineItem.

key​
String​

User-defined identifier of the LineItem. Unique among LineItems in the Cart or Order.

productId​
String​
id of the Product the Line Item is based on.
productKey​
String​
key of the Product.

This field is only present on:

  • Line Items in a Cart when the key is available on that specific Product at the time the LineItem was created or updated on the Cart.
  • Line Items in an Order when the key is available on the specific Product at the time the Order was created from the Cart.

Present on resources created or updated after 3 December 2021.

name​
String​

Name of the Product.

nameAllLocales​
Array of LocalizedString​

Name of the Product.

productSlug​
String​
slug of the current version of the Product. Updated automatically if the slug changes. Empty if the Product has been deleted. The productSlug field of LineItem is not expanded when using Reference Expansion.
productSlugAllLocales​
Array of LocalizedString​
slug of the current version of the Product. Updated automatically if the slug changes. Empty if the Product has been deleted. The productSlug field of LineItem is not expanded when using Reference Expansion.
productType​

Product Type of the Product.

productTypeRef​
Reference to the product type of the line item, carrying the snapshot version captured when the line item was added.
variant​

Holds the data of the Product Variant added to the Cart.

The data is saved at the time the Product Variant is added to the Cart and is not updated automatically when Product Variant data changes. Must be updated using the Recalculate update action.
price​
Price of a Line Item selected from the Product Variant according to the Product priceMode. If the priceMode is Embedded ProductPriceMode and the variant field hasn't been updated, the price may not correspond to a price in variant.prices.
taxedPrice​
Automatically set after taxRate is set.
totalPrice​
Total price of this Line Item equalling price multiplied by quantity. If the Line Item is discounted, the total price is the discountedPricePerQuantity multiplied by quantity. Includes taxes if the TaxRate includedInPrice is true.
If ExternalPrice LineItemPriceMode is used with high-precision money, then the total price is rounded by using the HalfEven rounding mode.
quantity​
Long​
Quantity of the Product Variant present in the Cart or Order.
addedAt​

Date and time (UTC) the Line Item was added to the Cart.

lastModifiedAt​

Date and time (UTC) the Line Item was last updated.

state​
Array of ItemState​
Tracks specific quantities of the Line Item within a given State. When a Line Item is added to a Cart, its full quantity is set to the built-in "Initial" state. State transitions for Line Items are managed on the Order.
taxRate​
  • For a Cart with Platform TaxMode, the taxRate of Line Items is set automatically once a shipping address is set. The rate is based on the TaxCategory that applies for the shipping address.
  • For a Cart with External TaxMode, the taxRate of Line Items can be set using ExternalTaxRateDraft.
supplyChannel​
Identifies Inventory entries that are reserved. The referenced Channel has the InventorySupply ChannelRoleEnum.
supplyChannelRef​
Identifies Inventory entries that are reserved. The referenced Channel has the InventorySupply ChannelRoleEnum.
distributionChannel​
Used to select a Product Price. The referenced Channel has the ProductDistribution ChannelRoleEnum.
distributionChannelRef​
Used to select a Product Price. The referenced Channel has the ProductDistribution ChannelRoleEnum.
discountedPricePerQuantity​

Discounted price of a single quantity of the Line Item.

lineItemMode​

Indicates how the Line Item is added to the Cart.

Can be GiftLineItem, or Standard​
priceMode​

Indicates how the Price for the Line Item is set.

Can be ExternalPrice, ExternalTotal, or Platform​
custom​

Custom Fields of the Line Item.

inventoryMode​
Inventory mode specific to this Line Item only, and valid for the entire quantity of the Line Item. Only present if the inventory mode is different from the inventoryMode specified on the Cart.
Can be None, TrackOnly, ReserveOnOrder, or ReserveOnCart​
reservation​
Reference to the successful Reservation associated with this Line Item. This field is only populated when using the ReserveOnCart mode.
reservationRef​
Reference to the successful Reservation associated with this Line Item. This field is only populated when using the ReserveOnCart mode.
shippingDetails​

Container for Line Item-specific addresses.

perMethodTaxRate​
Array of MethodTaxRate​
Tax Rate per Shipping Method for a Cart with Multiple ShippingMode. For a Cart with Platform TaxMode it is automatically set after the Shipping Method is added. For a Cart with External TaxMode, the Tax Rate must be set with ExternalTaxRateDraft.
taxedPricePortions​
Array of MethodTaxedPrice​
Total taxed prices based on the quantity of Line Item assigned to each Shipping Method. Only applicable for Carts with Multiple ShippingMode. Automatically set after perMethodTaxRate is set.
recurrenceInfo​

Recurring Order and frequency data.

VersionedReference

typeId​
String​
id​
String​
version​
Long​

ProductVariant

Represents a Product Variant embedded in a Product.
Only available for Projects with the ProductCatalogModel Classic. When the Project has the Modular catalog model, use the Variants API instead.
id​
Int​

A unique, sequential identifier of the Product Variant within the Product.

key​
String​

User-defined identifier of the ProductVariant. Unique among ProductVariants in the same Product.

This is different from Product key.
sku​
String​

User-defined SKU of the Product Variant. Unique across all ProductVariants in a Project.

prices​
Array of ProductPrice​
If the Product is projected by Store, this field only contains Embedded Prices that are valid for that Store.
Cannot contain two Embedded Prices with the same scopes (currency, country, Customer Group, Channel, validFrom and validUntil).
price​

Returns a single price based on the price selection rules.

allRecurrencePrices​
Array of ProductPrice​

Returns all recurrence prices based on the price selection rules.

images​
Array of Image​

Images of the Product Variant.

assets​
Array of Asset​

Media assets of the Product Variant.

availability​
Set if the Product Variant is tracked by Inventory. Can be used as an optimization to reduce calls to the Inventory service. May not contain the latest Inventory State (it is eventually consistent).
attributesRaw​

This field contains raw attributes data

ProductPrice

id​
String​
value​
key​
String​
country​
customerGroup​
customerGroupRef​
channel​
channelRef​
validFrom​
validUntil​
discounted​
tiers​
Array of ProductPriceTier​
custom​
recurrencePolicy​
recurrencePolicyRef​

DiscountedProductPriceValue

value​
discountRef​
discount​

ProductPriceTier

minimumQuantity​
Int​
value​

ProductVariantAvailabilityWithChannels

noChannel​
channels​

ProductVariantAvailability

Product variant availability

isOnStock​
Boolean​
Whether the Product Variant is in stock, based on an InventoryEntry that has no assigned supply Channel. This value reflects global or default availability; it does not aggregate the channel-specific availabilities found in the channels field.
restockableInDays​
Int​

Number of days to restock a Product Variant once it is out of stock.

availableQuantity​
Long​

Number of items of the Product Variant that are in stock.

version​
Long​
Current version of the InventoryEntry.
id​
String​
Unique identifier of the InventoryEntry.

ProductVariantAvailabilitiesResult

Product variant availabilities

limit​
Int​
offset​
Int​
total​
Int​
results​

ProductVariantAvailabilityWithChannel

channelRef​
channel​
availability​

RawProductAttribute

attributeDefinition​
name​
String​
value​
Json​
attributesRaw​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
referencedResource​
referencedResourceSet​

AttributeDefinition

type​

Describes the Type of the Attribute.

name​
String​
User-defined name of the Attribute that is unique within the Project.
label​
String​

Human-readable label for the Attribute.

isRequired​
Boolean​
Whether the Attribute must have a value on a ProductVariant.
attributeConstraint​

Specifies how Attributes are validated across all variants of a Product.

Can be None, Unique, CombinationUnique, or SameForAll​
level​

Specifies whether the Attribute is defined at the Product or Variant level.

Can be Variant, or Product​
inputTip​
String​

Provides additional Attribute information to aid content managers configure Product details.

inputHint​
Provides a visual representation directive for values of this Attribute (only relevant for AttributeTextType and AttributeLocalizableTextType).
Can be SingleLine, or MultiLine​
isSearchable​
Boolean​
Whether the Attribute's values are available in the Product Search or the Product Projection Search API for use in full-text search queries, filters, and facets. However, if an Attribute's level is set as Product, then Product Projection Search does not support the Attribute. To use the Attribute in search, filters, or facets, set isSearchable to true for all AttributeDefinitions with the same name across different ProductTypes. If the isSearchable values are different, the Attribute isn't available for search, filters, or facets.
The exact features that are available with this flag depend on the specific AttributeType. The maximum size of a searchable field is restricted by the Field content size limit. This constraint is enforced at both Product creation and Product update. If the length of the input exceeds the maximum size, an InvalidField error is returned.
savedToLineItem​
Boolean​
Whether the Attribute value is copied onto the LineItem when the Product is added to a Cart. When false, the Attribute value is excluded from the Line Item variant. Line Items already in a Cart are not immediately affected by a change to this value. Existing Line Items are updated the next time their Product data is refreshed, such as when a Recalculate update action is performed with updateProductData set to true, or on a Cart update that triggers an API Extension. Replicating a Cart creates a new Cart that contains the current Product data; it does not update the original Cart.
When savedToLineItem is false, LineItem predicates that reference this Attribute, such as those in Cart Discounts and Shipping Methods, evaluate as if the Attribute is not set.
labelAllLocales​
Array of LocalizedString​

Human-readable label for the Attribute.

inputTipAllLocales​
Array of LocalizedString​

Provides additional Attribute information to aid content managers configure Product details.

AttributeDefinitionType

AttributeConstraint

None
No constraints are applied to the attribute
Unique
Attribute value should be different in each variant
CombinationUnique
A set of attributes, that have this constraint, should have different combinations in each variant
SameForAll
Attribute value should be the same in all variants

Level

Variant
The attribute can be used on the variant level
Product
The attribute can be used on the product level

TaxedItemPrice

totalNet​

Total net amount of the Line Item or Custom Line Item.

totalGross​

Total gross amount of the Line Item or Custom Line Item.

taxPortions​
Array of TaxPortion​

Taxable portions added to the total net price.

Calculated from the TaxRates.
totalTax​
Total tax applicable for the Line Item or Custom Line Item. Automatically calculated as the difference between the totalGross and totalNet values.

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.

rate​
Float​

A number in the range 0-1.

amount​

Money value of the tax portion.

name​
String​

Name of the tax portion.

ItemState

quantity​
Long​

Quantity of Line Items or Custom Line Items in this State.

stateRef​

State of the Line Items or Custom Line Items in a custom workflow.

state​

State of the Line Items or Custom Line Items in a custom workflow.

TaxRate

name​
String​

Name of the TaxRate.

amount​
Float​
Tax rate. If subrates are used, the amount is the sum of all rates in subRates.
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress.
A TaxRate whose state is omitted does not act as a wildcard: it only matches a Cart whose shippingAddress also has no state value. To apply the same rate across states, either define an individual TaxRate for each state, or use the region field or a Custom Field on the shipping address as described in Address matching.
id​
String​
Present if the TaxRate is part of a TaxCategory. Absent for external TaxRates in LineItem, CustomLineItem, and ShippingInfo.
key​
String​
User-defined identifier of the TaxRate. Unique within the TaxCategory containing it. Present when set using TaxRateDraft. Not available for external TaxRates created using ExternalTaxRateDraft.
subRates​
Array of SubRate​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
taxRoundingTarget​
Determines which of the net price and the tax amount the taxRoundingMode of the Cart or Order is applied to, when this TaxRate is included in the price. Ignored if includedInPrice is false.
Always returned by the API. Can be omitted when a TaxRate is supplied as input, such as in OrderImportDraft, and then defaults to Net.
Can be Net, or Tax​

SubRate

It is used to calculate the taxPortions field in a Cart or Order.
name​
String​

Name of the SubRate.

amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

DiscountedLineItemPriceForQuantity

quantity​
Long​

Quantity of Line Items or Custom Line Items in the Cart.

discountedPrice​

Discounted price of the Line Item or Custom Line Item.

When multiple Cart Discounts apply to the same Line Item, the discounts are applied sequentially in the order determined by their sortOrder values (higher values are applied first). The price rounding mode specified by the Cart's priceRoundingMode field is applied after each individual discount is calculated, not after all discounts have been applied cumulatively. This means that rounding occurs at each step of the discount calculation process.

DiscountedLineItemPrice

value​

Money value of the discounted Line Item or Custom Line Item.

When multiple discounts from includedDiscounts apply, they are applied sequentially based on the sortOrder of their associated Cart Discounts (discounts with higher sortOrder values are applied first). The Cart's priceRoundingMode field (RoundingMode) is applied after each discount calculation, so rounding occurs after each discount step rather than only once on the final cumulative amount.
includedDiscounts​

Discount applicable on the Line Item or Custom Line Item.

DiscountedLineItemPortion

discount​
A CartDiscountReference or DirectDiscountReference of the applicable discount on the Line Item.
discountRef​
A CartDiscountReference or DirectDiscountReference of the applicable discount on the Line Item.
discountedAmount​

Money value of the applicable discount.

When a Cart Discount with CartDiscountPatternTarget is used:
  • The value is zero for a (Custom) Line Item matching the triggerPattern, indicating it participated in the discount as a trigger.
  • The value is the actual discount amount for a (Custom) Line Item matching the targetPattern.

LineItemMode

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.
Standard
The line item was added during cart creation or with the update action addLineItem. Its quantity can be changed without restrictions.

LineItemPriceMode

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.
Platform
The price is selected form the product variant. This is the default mode.

InventoryMode

None
No inventory checks or modifications when adding items or ordering. Default for a new cart.
TrackOnly
Orders decrement the available quantity on the matching inventory entry; ordering fails only when no inventory entry exists for a line item.
ReserveOnOrder
Line items are reserved only for the duration of the ordering transaction; creating an order fails when an unavailable line item exists.
ReserveOnCart
Items are reserved when added to the cart. Not supported by this service.

ItemShippingDetails

targets​
Array of ItemShippingTarget​

Holds information on the quantity of Line Items or Custom Line Items and the address it is shipped.

valid​
Boolean​
Whether the quantity of Line Items or Custom Line Items is equal to the sum of sub-quantities defined in targets. Ordering a Cart when the value is false returns an InvalidItemShippingDetails error.

ItemShippingTarget

Determines the address (as a reference to an address in itemShippingAddresses) and the quantity shipped to the address.

If multiple shipping addresses are present for a Line Item or Custom Line Item, sub-quantities must be specified. An array of addresses and sub-quantities is stored per Line Item or Custom Line Item.

addressKey​
String​
Key of the address in the Cart itemShippingAddresses. Duplicate address keys are not allowed.
quantity​
Long​
Quantity of Line Items or Custom Line Items shipped to the address with the specified addressKey.
If a quantity is updated to 0 when defining ItemShippingDetailsDraft, the targets are removed from a Line Item or Custom Line Item in the resulting ItemShippingDetails.
shippingMethodKey​
String​
User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.

It connects Line Item or Custom Line Item quantities with individual Shipping Methods.

Required when the Cart has Multiple ShippingMode. Omitting this field in that case returns an InvalidOperation error.

MethodTaxRate

shippingMethodKey​
String​
User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.
taxRate​

Tax Rate for the Shipping Method.

MethodTaxedPrice

shippingMethodKey​
String​
User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.
taxedPrice​
Total taxed price based on the quantity of the Line Item or Custom Line Item assigned to the Shipping Method identified by shippingMethodKey.

LineItemRecurrenceInfo

The RecurrenceInfo returned in a LineItem

recurrencePolicy​
recurrencePolicyRef​
expiresAt​
priceSelectionMode​
Can be Dynamic, or Fixed​

RecurrencePolicyRef

typeId​
String​
id​
String​

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​

Unique identifier of the Custom Line Item.

key​
String​

User-defined identifier of the Custom Line Item. Unique among Custom Line Items in the Cart or Order.

name​
String​

Name of the Custom Line Item.

nameAllLocales​
Array of LocalizedString​

Name of the Custom Line Item.

money​

Money value of the Custom Line Item.

totalPrice​
Total price of the Custom Line Item (money multiplied by quantity). If the Custom Line Item is discounted, the total price is discountedPricePerQuantity multiplied by quantity.
Includes taxes if the TaxRate includedInPrice is true.
slug​
String​
User-defined identifier used in a deep-link URL for the Custom Line Item. It matches the pattern [a-zA-Z0-9_-]{2,256}.
quantity​
Long​
Number of Custom Line Items in the Cart or Order.
state​
Array of ItemState​
Tracks specific quantities of the Custom Line Item within a given State. When a Custom Line Item is added to a Cart, its full quantity is set to the built-in "Initial" state. State transitions for Custom Line Items are managed on the Order.
taxCategory​
Used to select a Tax Rate when a Cart has the Platform TaxMode.
taxCategoryRef​
Used to select a Tax Rate when a Cart has the Platform TaxMode.
taxRate​
  • For a Cart with Platform TaxMode, the taxRate of Custom Line Items is set automatically once a shipping address is set. The rate is based on the TaxCategory that applies for the shipping address.
  • For a Cart with External TaxMode, the taxRate of Custom Line Items can be set using ExternalTaxRateDraft.
taxedPrice​
Automatically set after the taxRate is set.
taxedPricePortions​
Array of MethodTaxedPrice​
Total taxed prices based on the quantity of the Custom Line Item assigned to each Shipping Method. Only applicable for Carts with Multiple ShippingMode. Automatically set after perMethodTaxRate is set.
perMethodTaxRate​
Array of MethodTaxRate​
Tax Rate per Shipping Method for a Cart with Multiple ShippingMode. For a Cart with Platform TaxMode it is automatically set after the Shipping Method is added. For a Cart with External TaxMode, the Tax Rate must be set with ExternalTaxRateDraft.
discountedPricePerQuantity​

Discounted price of a single quantity of the Custom Line Item.

custom​

Custom Fields of the Custom Line Item.

shippingDetails​

Container for Custom Line Item-specific addresses.

Indicates whether Cart Discounts with a matching CartDiscountCustomLineItemsTarget, MultiBuyCustomLineItemsTarget, or CartDiscountPatternTarget are applied to the Custom Line Item.
Can be External, or Standard​
recurrenceInfo​

Recurring Order and frequency data.

CustomLineItemPriceMode

External
Cart discounts are deactivated for the custom line items with this price mode.
Standard
This is the default mode.

CustomLineItemRecurrenceInfo

The RecurrenceInfo returned in a CustomLineItem

recurrencePolicy​
recurrencePolicyRef​
expiresAt​

TaxedPrice

totalNet​

Total net price of the Cart or Order.

totalGross​

Total gross price of the Cart or Order.

taxPortions​
Array of TaxPortion​

Taxable portions added to the total net price.

Calculated from the TaxRates.
totalTax​

Total tax applicable for the Cart or Order.

Automatically calculated as the difference between the totalGross and totalNet values.

DiscountOnTotalPrice

discountedAmount​

Money value of the discount on the total price of the Cart or Order.

includedDiscounts​

Discounts that impact the total price of the Cart or Order.

discountedNetAmount​

Money value of the discount on the total net price of the Cart or Order.

The same percentage of discount applies as on the discountedAmount. Present only when taxedPrice of the Cart or Order exists.
discountedGrossAmount​

Money value of the discount on the total gross price of the Cart or Order.

The same percentage of discount applies as on the discountedAmount. Present only when taxedPrice of the Cart or Order exists.

DiscountedTotalPricePortion

discount​
A CartDiscountReference or DirectDiscountReference to the discount applied on the Cart totalPrice.
discountRef​
A CartDiscountReference or DirectDiscountReference to the discount applied on the Cart totalPrice.
discountedAmount​

Money value of the discount.

TaxMode

Disabled
No taxes are added to the cart.
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 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
Platform
The tax rates are selected from the TaxCategories based on the cart shipping address. The totalNet and totalGross as well as the taxPortions fields are calculated according to the taxRoundingMode.

RoundingMode

HalfDown
[Round half down](https://en.wikipedia.org/wiki/Rounding#Round_half_down)
HalfEven
[Round half to even](https://en.wikipedia.org/wiki/Rounding#Round_half_to_even). Default rounding mode as used in IEEE 754 computing functions and operators.
HalfUp
[Round half up](https://en.wikipedia.org/wiki/Rounding#Round_half_up)

TaxCalculationMode

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`

ShippingInfo

shippingMethodName​
String​

Name of the Shipping Method.

price​
Determined based on the ShippingRate and its tiered prices, and either the sum of LineItem prices or the shippingRateInput field.
shippingRate​

Used to determine the price.

taxRate​
Automatically set in the Platform TaxMode after the shipping address is set.
For the External TaxMode the Tax Rate must be set explicitly with the ExternalTaxRateDraft.
deliveries​
Array of Delivery​

Information on how items are delivered to customers.

discountedPrice​

Discounted price of the Shipping Method.

shippingMethodState​
Indicates whether the ShippingMethod referenced in this ShippingInfo is allowed for the Cart.
Can be DoesNotMatchCart, or MatchesCart​
estimatedDelivery​
Estimated time window during which the shipment is expected to be delivered. This value is removed if the Cart's shippingAddress changes.
message​
String​
shippingMethod​

Not set if a custom Shipping Method is used.

shippingMethodRef​

Not set if a custom Shipping Method is used.

taxCategory​
Used to select a Tax Rate when a Cart has the Platform TaxMode.
taxCategoryRef​
Used to select a Tax Rate when a Cart has the Platform TaxMode.
taxedPrice​
Automatically set after the taxRate is set.

Delivery

Contains information on how items are shipped to Customers, for example, a delivery note.

id​
String​

Unique identifier of the Delivery.

key​
String​

User-defined identifier of the Delivery. Unique among Deliveries in the Order.

createdAt​

Date and time (UTC) the Delivery was created.

items​
Array of DeliveryItem​

Line Items or Custom Line Items that are delivered.

parcels​
Array of Parcel​

Information regarding the appearance, content, and shipment of a Parcel.

address​

Address to which Parcels are delivered.

custom​

Custom Fields of the Delivery.

DeliveryItem

id​
String​
id of the LineItem or CustomLineItem delivered.
quantity​
Long​

Quantity of Line Items or Custom Line Items delivered.

Parcel

Information regarding the appearance, content, and shipment of a Parcel.

id​
String​

Unique identifier of the Parcel.

key​
String​

User-defined unique identifier of the Parcel.

createdAt​

Date and time (UTC) the Parcel was created.

measurements​

Information about the dimensions of the Parcel.

trackingData​

Shipment tracking information of the Parcel.

items​
Array of DeliveryItem​

Line Items or Custom Line Items delivered in this Parcel.

custom​

Custom Fields of the Parcel.

ParcelMeasurements

heightInMillimeter​
Int​

Height of the Parcel.

lengthInMillimeter​
Int​

Length of the Parcel.

widthInMillimeter​
Int​

Width of the Parcel.

weightInGram​
Int​

Weight of the Parcel.

TrackingData

Information that helps track a Parcel.

trackingId​
String​

Identifier to track the Parcel.

carrier​
String​

Name of the carrier that delivers the Parcel.

provider​
String​

Name of the provider that serves as facade to several carriers.

providerTransaction​
String​
Transaction identifier with the provider.
isReturn​
Boolean​
Whether the Parcel is being returned. If false, the Parcel is being delivered to the customer.

ShippingMethodState

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

EstimatedDelivery

Estimated time window during which a shipment is expected to be delivered. The window is anchored to the selected Shipping Method and the shipping destination.

from​

Date and time (UTC) of the earliest expected delivery.

until​
Date and time (UTC) of the latest expected delivery. When both from and until are set, until must be equal to or later than from.

DiscountCodeInfo

discountCodeRef​

Discount Code associated with the Cart or Order.

Indicates the state of the Discount Code applied to the Cart or Order.

Can be ApplicationStoppedByGroupBestDeal, ApplicationStoppedByPreviousDiscount, DoesNotMatchCart, MatchesCart, MaxApplicationReached, NotActive, or NotValid​
discountCode​

Discount Code associated with the Cart or Order.

DiscountCodeState

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

DirectDiscount

Represents a CartDiscount that is only associated with a single Cart or Order.
id​
String​

Unique identifier of the Direct Discount.

value​

Effect of the Discount on the Cart.

target​

Segment of the Cart that is discounted.

Absent if the value is giftLineItem.
participateInBestDealSelection​
Boolean​
  • If true, Direct Discounts compete against Product Discounts to apply the best deal.
  • If false, Direct Discounts are ignored when calculating the best deal comparison, and are applied on top of the discount type that offers the best deal.
This applies only when the DiscountCombinationMode for the Project is BestDeal.

CartDiscountValue

type​
String​

CartDiscountTarget

type​
String​

PaymentInfo

payments​
Array of Payment​
paymentRefs​
Array of Reference​

ShippingRateInput

type​
String​

CartOrigin

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
Quote
The cart was created by our platform and belongs to a Quote.
RecurringOrder
The cart was created by the merchant as a recurring order.

Shipping

shippingKey​
String​
User-defined unique identifier of the Shipping in a Cart with Multiple ShippingMode.
shippingInfo​
Automatically set when the Shipping Method is added.
shippingAddress​

Determines the shipping rates and Tax Rates of associated Line Items.

shippingRateInput​
Used as an input to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
shippingCustomFields​
Custom Fields of Shipping with Multiple ShippingMode.

ShippingMode

Multiple
Allows multiple shipping methods for the cart with their respective shipping addresses
Single
Allows only one shipping method and shipping address for the cart

Placement

InStore
The Order or Cart is placed in-store.
Online
The Order or Cart is placed online.

DiscountTypeCombination

type​
String​

CartState

Active
The cart can be updated and ordered. It is the default state.
Frozen
The cart is frozen. The cart is ready for checkout and a few update actions are not allowed.
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.

CartLock

Prevents edits on a Cart unless the caller has the manage_locked_carts OAuth scope.
createdAt​

Date and time (UTC) the Cart was locked.

clientId​
String​
id of the API Client that locked the Cart.

RecurringPaymentConfiguration

Determines how the Orders generated by a RecurringOrder are paid for. It is only evaluated on recurring Carts, that is Carts with the RecurringOrder CartOrigin.
paymentStrategy​
Checkout
paymentAllocations​

Payment Methods charged for the Orders generated by the RecurringOrder, and the share of the Order total charged to each of them.

PaymentStrategy

Checkout

RecurringPaymentAllocation

Assigns a share of the Order total to a specific PaymentMethod.
id​
String​
Unique identifier of the RecurringPaymentAllocation within the RecurringPaymentConfiguration. Use it to remove the allocation with the Remove RecurringPaymentAllocation update action.
paymentMethodRef​

Payment Method charged for this share of the Order total.

paymentMethod​

Payment Method charged for this share of the Order total.

allocation​
Share of the Order total charged to the paymentMethod.

AllocationInterface

type​
String​

FreezeStrategy

HardFreeze
Stricter version of a Cart freeze (See [Freeze a Cart](https://docs.commercetools.com/api/carts-orders-overview#freeze-a-cart) for details).
SoftFreeze
More lenient version of a Cart freeze (See [Freeze a Cart](https://docs.commercetools.com/api/carts-orders-overview#freeze-a-cart) for details).

TypedWarning

A non-fatal warning that occurred during a mutation.

Can be CannotChangeReservationExpiry, CannotCreateReservation, CannotUpdateReservation, DefaultVariantDeleted, General, ImageProcessingOngoing, or StoreSettingOngoing​
message​
String​

TypedWarningCode

CannotChangeReservationExpiry
CannotCreateReservation
CannotUpdateReservation
DefaultVariantDeleted
General
ImageProcessingOngoing
StoreSettingOngoing

Cart Query Result

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of Cart​

Input types

CartDraft

currency​

Currency the Cart uses.

country​
Used for Line Item price selection. If used for Create Cart in Store, the provided country must be one of the Store's countries.
inventoryMode​

Determines how stock quantities are tracked for Line Items in the Cart.

Can be None, TrackOnly, ReserveOnOrder, or ReserveOnCart​Default: None​
custom​

Custom Fields for the Cart.

customerEmail​
String​

Email address of the Customer that the Cart belongs to.

shippingAddress​
Shipping address for a Cart with Single ShippingMode. Determines eligible ShippingMethod rates and Tax Rates of Line Items. Must be one of the itemShippingAddresses when that field is also provided.
billingAddress​

Billing address associated with the Cart.

shippingMethod​
Shipping Method for a Cart with Single ShippingMode. If the referenced ShippingMethod has a predicate that does not match the Cart, an InvalidOperation error is returned when creating a Cart.
taxMode​

Determines how Tax Rates are set.

Can be Disabled, External, ExternalAmount, or Platform​Default: Platform​
locale​
Language of the Cart. Must be one of the languages supported by the Project.
deleteDaysAfterLastModification​
Int​
Number of days after the last modification before a Cart is deleted. If not provided, the default value for this field configured in Project settings is assigned.
Create a ChangeSubscription for Carts to receive a ResourceDeletedDeliveryPayload upon deletion of the Cart.
itemShippingAddresses​
Array of AddressInput​
Multiple shipping addresses of the Cart. Each address must contain a key that is unique in this Cart. The keys are used by LineItems to reference these addresses under their shippingDetails.
For Carts with Single ShippingMode: eligible Shipping Methods or applicable Tax Rates are determined by the address shippingAddress, and not itemShippingAddresses.
Default: []​
discountCodes​
Array of String​
code of the existing DiscountCodes to add to the Cart.
Default: []​
ResourceIdentifier to the Store the Cart should belong to. Once set, it cannot be updated.
businessUnit​
ResourceIdentifier to the Business Unit the Cart should belong to. When the customerId of the Cart is also set, the Customer must be an Associate of the Business Unit. Only available for B2B-enabled Projects.
purchaseOrderNumber​
String​

User-defined identifier of a purchase order.

It is typically set by the Buyer or Merchant to track the purchase order during the quote and order flow.
shippingMode​
  • If set to Single, only a single Shipping Method can be added to the Cart.
  • If set to Multiple, multiple Shipping Methods can be added to the Cart.
Can be Multiple, or Single​Default: Single​
customShipping​
Custom Shipping Methods for a Cart with Multiple ShippingMode.
Default: []​
shipping​
Array of ShippingDraft​
Shipping Methods for a Cart with Multiple ShippingMode.
Default: []​
key​
String​

User-defined unique identifier for the Cart.

lineItems​
Array of LineItemDraft​
Line Items to add to the Cart.
Default: []​
customLineItems​
Custom Line Items to add to the Cart.
Default: []​
customerId​
String​
id of the Customer that the Cart belongs to.
externalTaxRateForShippingMethod​
External Tax Rate for the shippingMethod if the Cart has External TaxMode.
anonymousId​
String​
Anonymous session associated with the Cart.
priceRoundingMode​
Determines how the total prices on LineItems and CustomLineItems are rounded when calculated. If not set, the default value configured in the Project is used.
Can be HalfDown, HalfEven, or HalfUp​Default: HalfEven​
taxRoundingMode​
Determines how monetary values are rounded when calculating taxes for taxedPrice. If not set, the default value configured in the Project is used.
Can be HalfDown, HalfEven, or HalfUp​Default: HalfEven​
taxCalculationMode​
Determines how taxes are calculated for taxedPrice.
Can be LineItemLevel, or UnitPriceLevel​Default: LineItemLevel​
customerGroup​
ResourceIdentifier to the Customer Group of the Customer that the Cart belongs to. Used for Line Item price selection.
You can set either a customerId or a customerGroup. If the Customer referenced in customerId belongs to a Customer Group then customerGroup is set automatically.
shippingRateInput​
Used as an input to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
origin​

Indicates how the Cart was created.

Can be Customer, Merchant, Quote, or RecurringOrder​Default: Customer​
directDiscountsIgnoreCartDiscounts​
Boolean​
  • If set to true, only Direct Discounts apply to the Cart. Matching Cart Discounts are ignored, and Discount Codes cannot be added.
  • If set to false, Cart Discounts, Discount Codes, and Direct Discounts apply to the Cart.

InventoryMode

None
No inventory checks or modifications when adding items or ordering. Default for a new cart.
TrackOnly
Orders decrement the available quantity on the matching inventory entry; ordering fails only when no inventory entry exists for a line item.
ReserveOnOrder
Line items are reserved only for the duration of the ordering transaction; creating an order fails when an unavailable line item exists.
ReserveOnCart
Items are reserved when added to the cart. Not supported by this service.

TaxMode

Disabled
No taxes are added to the cart.
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 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
Platform
The tax rates are selected from the TaxCategories based on the cart shipping address. The totalNet and totalGross as well as the taxPortions fields are calculated according to the taxRoundingMode.

ShippingMode

Multiple
Allows multiple shipping methods for the cart with their respective shipping addresses
Single
Allows only one shipping method and shipping address for the cart

CustomShippingDraft

key​
String​
User-defined unique identifier of the custom Shipping Method in the Cart with Multiple ShippingMode.
shippingMethodName​
String​

Name of the custom Shipping Method.

shippingAddress​

Determines the shipping rate and Tax Rate of the associated Line Items.

shippingRate​

Determines the shipping price.

shippingRateInput​
Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
taxCategory​
Tax Category used to determine a shipping Tax Rate if the Cart has the Platform TaxMode.
externalTaxRate​
Tax Rate used to tax a shipping expense if the Cart has the External TaxMode.
deliveries​
Array of DeliveryDraft​

Deliveries to be shipped with the custom Shipping Method.

custom​

Custom Fields for the custom Shipping Method.

ShippingRateInputDraft

Classification​
Score​

ClassificationShippingRateInputDraft

key​
String​

Key of the value used as a programmatic identifier.

ScoreShippingRateInputDraft

score​
Int​

Abstract value for categorizing a Cart.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

DeliveryDraft

key​
String​

User-defined identifier of the Delivery. Must be unique among Deliveries in the Order.

items​
Line Items or Custom Line Items to deliver. It can also be specified individually for each Parcel.
parcels​
Array of ParcelDraft​

Information regarding the appearance, content, and shipment of a parcel.

address​

Address to which the Parcels are delivered.

custom​

Custom Fields for the Delivery.

DeliveryItemDraftType

id​
String​
quantity​
Long​

ParcelDraft

id​
String​
key​
String​
createdAt​
measurements​
trackingData​
items​
Default: []​
custom​

ParcelMeasurementsDraftType

heightInMillimeter​
Int​
lengthInMillimeter​
Int​
widthInMillimeter​
Int​
weightInGram​
Int​

TrackingDataDraftType

trackingId​
String​
carrier​
String​
provider​
String​
providerTransaction​
String​
isReturn​
Boolean​
Default: false​

ShippingDraft

Wraps all shipping-related information (such as address, rate, deliveries) per Shipping Method for Carts with multiple Shipping Methods.

key​
String​
User-defined unique identifier for the Shipping in a Cart with Multiple ShippingMode.
shippingMethod​
Shipping Methods added to the Cart with Multiple ShippingMode.
shippingAddress​

Determines the shipping rate and Tax Rate of the associated Line Items.

shippingRateInput​
Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
externalTaxRate​
Tax Rate used for taxing a shipping expense if the Cart has the External TaxMode.
deliveries​
Array of DeliveryDraft​

Deliveries to be shipped with the Shipping Method.

custom​

Custom Fields for Shipping.

LineItemDraft

For Product Variant identification, either the productId and variantId, or sku must be provided. Product Attributes are merged with Variant Attributes to ensure the full Attribute context of the Product Variant.
key​
String​

User-defined identifier of the LineItem. Must be unique among LineItems in the Cart.

productId​
String​
id of a published Product.
sku​
String​
sku of the ProductVariant.
quantity​
Long​

Quantity of the Product Variant to add to the Cart.

variantId​
Int​
id of the ProductVariant in the Product. If not provided, the Master Variant is used.
supplyChannel​
Used to identify Inventory entries that must be reserved. The referenced Channel must have the InventorySupply ChannelRoleEnum.
distributionChannel​
Used to select a Product Price. The referenced Channel must have the ProductDistribution ChannelRoleEnum.
If the Cart is bound to a Store with distributionChannels set, the Channel must match one of the Store's distribution channels.
custom​

Custom Fields for the Line Item.

shippingDetails​

Container for Line Item-specific addresses.

addedAt​

Date and time (UTC) the Line Item was added to the Cart. If not set, it defaults to the current date and time.

Optional for backwards compatibility reasons.

recurrenceInfo​

Recurring Order and frequency data.

externalTaxRate​
Sets the external Tax Rate for the Line Item, if the Cart has the External TaxMode and Single ShippingMode. If the Cart has Multiple ShippingMode, the Tax Rate is accepted but ignored.
externalPrice​
Sets the LineItem price value, and the priceMode to ExternalPrice LineItemPriceMode.
To set the money value in high precision, use HighPrecisionMoneyDraft.
externalTotalPrice​
Sets the LineItem price and totalPrice values, and the priceMode to ExternalTotal LineItemPriceMode.
perMethodExternalTaxRate​
Sets the external Tax Rates for individual Shipping Methods, if the Cart has the External TaxMode and Multiple ShippingMode.
Default: []​
inventoryMode​
Inventory mode specific to the Line Item only, and valid for the entire quantity of the Line Item. Set only if the inventory mode should be different from the inventoryMode specified on the Cart.
Can be None, TrackOnly, ReserveOnOrder, or ReserveOnCart​

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

LineItemRecurrenceInfoInputDraft

recurrencePolicy​
expiresAt​
priceSelectionMode​
Can be Dynamic, or Fixed​

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

ExternalLineItemTotalPriceDraft

price​
totalPrice​

MethodExternalTaxRateDraft

shippingMethodKey​
String​
User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.
taxRate​
External Tax Rate for the Shipping Method, if the Cart has External TaxMode.

CustomLineItemDraft

name​

Name of the Custom Line Item.

key​
String​

User-defined identifier of the Custom Line Item. Must be unique among Custom Line Items in the Cart.

money​

Money value of the Custom Line Item. The value can be negative.

To set the money value in high precision, use HighPrecisionMoneyDraft.
slug​
String​
User-defined identifier used in a deep-link URL for the Custom Line Item. It must match the pattern [a-zA-Z0-9_-]{2,256}.
taxCategory​
Used to select a Tax Rate when a Cart has the Platform TaxMode. This field is required for Platform TaxMode.
externalTaxRate​
External Tax Rate for the Custom Line Item if the Cart has the External TaxMode.
quantity​
Long​

Number of Custom Line Items to add to the Cart.

custom​

Custom Fields for the Custom Line Item.

shippingDetails​

Container for Custom Line Item-specific addresses.

Can be External, or Standard​
recurrenceInfo​

Recurring Order and frequency data.

CustomLineItemPriceMode

External
Cart discounts are deactivated for the custom line items with this price mode.
Standard
This is the default mode.

CustomLineItemRecurrenceInfoInputDraft

recurrencePolicy​
expiresAt​

RoundingMode

HalfDown
[Round half down](https://en.wikipedia.org/wiki/Rounding#Round_half_down)
HalfEven
[Round half to even](https://en.wikipedia.org/wiki/Rounding#Round_half_to_even). Default rounding mode as used in IEEE 754 computing functions and operators.
HalfUp
[Round half up](https://en.wikipedia.org/wiki/Rounding#Round_half_up)

TaxCalculationMode

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`

CartOrigin

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
Quote
The cart was created by our platform and belongs to a Quote.
RecurringOrder
The cart was created by the merchant as a recurring order.

CartUpdateAction

addCustomShippingMethod​
addDiscountCode​
addItemShippingAddress​
addPayment​
addShippingMethod​
addShoppingList​
changeCustomLineItemMoney​
changeCustomLineItemPriceMode​
changeCustomLineItemQuantity​
changeLineItemsOrder​
changePriceRoundingMode​
changeTaxCalculationMode​
changeTaxMode​
changeTaxRoundingMode​
recalculate​
removeCustomLineItem​
removeDiscountCode​
removeItemShippingAddress​
removeLineItem​
removePayment​
removeShippingMethod​
setAnonymousId​
setBillingAddress​
setBillingAddressCustomField​
setBillingAddressCustomType​
setBusinessUnit​
setKey​
setCartTotalTax​
setCountry​
setCustomField​
setCustomLineItemCustomField​
setCustomLineItemCustomType​
setCustomLineItemShippingDetails​
setCustomLineItemTaxAmount​
setCustomLineItemTaxRate​
setCustomShippingMethod​
setCustomType​
setCustomerEmail​
setCustomerGroup​
setCustomerId​
setDeleteDaysAfterLastModification​
setDirectDiscounts​
setDirectDiscountsIgnoreCartDiscounts​
setEstimatedDelivery​
setItemShippingAddressCustomField​
setItemShippingAddressCustomType​
setLineItemCustomField​
setLineItemCustomType​
setLineItemDistributionChannel​
setLineItemInventoryMode​
setLineItemPrice​
setLineItemShippingDetails​
setLineItemSupplyChannel​
setLineItemTaxAmount​
setLineItemTaxRate​
setLineItemTotalPrice​
setLocale​
setPurchaseOrderNumber​
setShippingAddress​
setShippingAddressCustomField​
setShippingAddressCustomType​
setShippingCustomField​
setShippingCustomType​
setShippingMethod​
setShippingMethodTaxAmount​
setShippingMethodTaxRate​
setShippingRateInput​
updateItemShippingAddress​
freezeCart​
unfreezeCart​
lockCart​
unlockCart​
applyDeltaToLineItemShippingDetailsTargets​
applyDeltaToCustomLineItemShippingDetailsTargets​
addLineItem​
addCustomLineItem​
setLineItemRecurrenceInfo​
setCustomLineItemRecurrenceInfo​
setReservationExpirationInMinutes​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
changeLineItemQuantity​
setRecurringPaymentConfiguration​
setRecurringPaymentStrategy​
addRecurringPaymentAllocation​
removeRecurringPaymentAllocation​

Update actions

on Cart

Set Key

key​
String​

Value to set. If omitted, any existing key is removed.

Set Customer ID

Setting the Cart's customerId can lead to updates on all its LineItem prices.
If the Customer with the specified id cannot be found, this update action returns a ReferencedResourceNotFound error.
customerId​
String​
id of an existing Customer. If the Customer is assigned to a CustomerGroup, this update action also sets the value for the customerGroup field. If omitted, the update action removes the value for both customerId and customerGroup.

Set Customer Email

email​
String​

Value to set. If omitted, any existing value is removed.

Set Customer Group

This update action can only be used if a Customer is not assigned to the Cart. If a Customer is already assigned, the Cart uses the Customer Group of the assigned Customer.

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

Value to set. If omitted, any existing value is removed.

Set Anonymous ID

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

Value to set. If omitted, any existing value is removed.

Set Purchase Order Number

Updates the purchaseOrderNumber field and produces the CartPurchaseOrderNumberSet Message.
purchaseOrderNumber​
String​

Value to set. If omitted, any existing value is removed.

Set Business Unit B2B B2X

Updates the Business Unit on the Cart. The Cart must have an existing Business Unit assigned already.

businessUnit​
New Business Unit to assign to the Cart, which must have access to the Store that is set on the Cart.

Add LineItem

If the Cart contains a LineItem for a Product Variant with the same LineItemMode, Custom Fields, supply and distribution channel, then only the quantity of the existing Line Item is increased. If LineItem shippingDetails is set, it is merged. All addresses will be present afterwards and, for address keys present in both shipping details, the quantity will be summed up. A new Line Item is added when the externalPrice or externalTotalPrice is set in this update action. The LineItem price is set as described in Line Item price selection.
If the Tax Rate is not set, a MissingTaxRateForCountry error is returned.
If the Line Items do not have a Price according to the Product priceMode value for a selected currency and/or country, Customer Group, or Channel, a MatchingPriceNotFound error is returned.
The Product Variant that is to be added as a Line Item must be available in a Store, otherwise an InvalidInput error is returned.
key​
String​

User-defined identifier of the LineItem. Must be unique among LineItems in the Cart.

productId​
String​
id of the published Product.
Either the productId and variantId, or sku must be provided.
sku​
String​
SKU of the ProductVariant.
Either the productId and variantId, or sku must be provided.
quantity​
Long​

Quantity of the Product Variant to add to the Cart.

variantId​
Int​
id of the ProductVariant in the Product. If omitted, the Master Variant is used.
Either the productId and variantId, or sku must be provided.
supplyChannel​
Used to identify Inventory entries that must be reserved. The Channel must have the InventorySupply ChannelRoleEnum.
distributionChannel​
Used to select a Product Price. The Channel must have the ProductDistribution ChannelRoleEnum. If the Cart is bound to a Store with distributionChannels set, the Channel must match one of the Store's distribution channels.
custom​

Custom Fields for the Line Item.

shippingDetails​

Container for Line Item-specific addresses.

addedAt​

Date and time (UTC) the Line Item was added to the Cart. If not set, it defaults to the current date and time.

Optional for backwards compatibility reasons.

recurrenceInfo​

Recurring Order and frequency data.

externalTaxRate​
Sets the external Tax Rate for the Line Item, if the Cart has the External TaxMode and Single ShippingMode. If the Cart has Multiple ShippingMode, the Tax Rate is accepted but ignored.
externalPrice​
Sets the LineItem price value, and the priceMode to ExternalPrice LineItemPriceMode.
To set the money value in high precision, use HighPrecisionMoneyDraft.
externalTotalPrice​
Sets the LineItem price and totalPrice values, and the priceMode to ExternalTotal LineItemPriceMode.
perMethodExternalTaxRate​
Sets the external Tax Rates for individual Shipping Methods, if the Cart has the External TaxMode and Multiple ShippingMode.
Default: []​
inventoryMode​
Inventory mode specific to the Line Item only, and valid for the entire quantity of the Line Item. Set only if the inventory mode should be different from the inventoryMode specified on the Cart.
Can be None, TrackOnly, ReserveOnOrder, or ReserveOnCart​

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

LineItemRecurrenceInfoInputDraft

recurrencePolicy​
expiresAt​
priceSelectionMode​
Can be Dynamic, or Fixed​

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

ExternalLineItemTotalPriceDraft

price​
totalPrice​

MethodExternalTaxRateDraft

shippingMethodKey​
String​
User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode.
taxRate​
External Tax Rate for the Shipping Method, if the Cart has External TaxMode.

InventoryMode

None
No inventory checks or modifications when adding items or ordering. Default for a new cart.
TrackOnly
Orders decrement the available quantity on the matching inventory entry; ordering fails only when no inventory entry exists for a line item.
ReserveOnOrder
Line items are reserved only for the duration of the ordering transaction; creating an order fails when an unavailable line item exists.
ReserveOnCart
Items are reserved when added to the cart. Not supported by this service.

Remove LineItem

The LineItem price is updated as described in Line Item price selection.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
quantity​
Long​

Amount to subtract from the LineItem quantity. If omitted, the LineItem is removed from the Cart.

lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.
externalPrice​
Sets the LineItem price to the given value when decreasing the quantity of a Line Item with the ExternalPrice LineItemPriceMode.
To set the money value in high precision, use HighPrecisionMoneyDraft.
externalTotalPrice​
Sets the LineItem price and totalPrice to the given value when decreasing the quantity of a Line Item with the ExternalTotal LineItemPriceMode.
shippingDetailsToRemove​

Container for Line Item-specific addresses to remove.

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

ExternalLineItemTotalPriceDraft

price​
totalPrice​

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

Change LineItems Order

lineItemOrder​
Array of String​
All existing LineItem ids in the desired new order.

Add CustomLineItem

If the Cart already contains a CustomLineItem with the same slug, name, money, taxCategory, state, and Custom Fields, then only the quantity of the existing Custom Line Item is increased. If CustomLineItem shippingDetails are set, they are merged with the targets that already exist on the ItemShippingDetails of the Custom Line Item. In case of overlapping address keys the ItemShippingTarget quantity is summed up.
If the Cart already contains a Custom Line Item with the same slug that is otherwise not identical, an InvalidOperation error is returned.
If the Tax Rate is not set, a MissingTaxRateForCountry error is returned.
name​

Name of the Custom Line Item.

key​
String​

User-defined identifier of the Custom Line Item. Must be unique among Custom Line Items in the Cart.

money​

Money value of the Custom Line Item. The value can be negative.

To set the money value in high precision, use HighPrecisionMoneyDraft.
slug​
String​
User-defined identifier used in a deep-link URL for the Custom Line Item. It must match the pattern [a-zA-Z0-9_-]{2,256}.
taxCategory​
Used to select a Tax Rate when a Cart has the Platform TaxMode.
If TaxMode is Platform, this field must not be empty.
externalTaxRate​
An external Tax Rate can be set if the Cart has External TaxMode.
quantity​
Long​

Number of Custom Line Items to add to the Cart.

custom​

Custom Fields for the Custom Line Item.

shippingDetails​

Container for Custom Line Item-specific addresses.

Can be External, or Standard​
recurrenceInfo​

Recurring Order and frequency data.

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

CustomLineItemPriceMode

External
Cart discounts are deactivated for the custom line items with this price mode.
Standard
This is the default mode.

CustomLineItemRecurrenceInfoInputDraft

recurrencePolicy​
expiresAt​

Remove CustomLineItem

This update action does not support specifying quantities, unlike the Remove LineItem update action.
If shippingDetails must be partially removed, use the Change CustomLineItem Quantity update action.
customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

Add Shopping List

Adds all LineItems of a ShoppingList to the Cart.
shoppingList​

Shopping List that contains the Line Items to be added.

supplyChannel​
supplyChannel to set for all LineItems that are added to the Cart. The Channel must have the InventorySupply ChannelRoleEnum.
distributionChannel​
distributionChannel to set for all LineItems that are added to the Cart. The Channel must have the ProductDistribution ChannelRoleEnum.

Set Cart Total Tax

externalTotalGross​
externalTaxPortions​
Array of TaxPortionDraft​
Default: []​

MoneyInput

currencyCode​
centAmount​
Long​

TaxPortionDraft

Represents the portions that sum up to the totalGross field of a TaxedPrice.
The portions are calculated from the TaxRates. If a Tax Rate has SubRates, they are used and can be identified by name. Tax portions from Line Items with the same rate and name will be accumulated to the same tax portion.
name​
String​

Name of the tax portion.

rate​
Float​

A number in the range 0-1.

amount​

Money value for the tax portion.

Change TaxMode

  • When External TaxMode is changed to Platform or Disabled, all previously set external Tax Rates are removed.
  • When set to Platform, Line Items, Custom Line Items, and Shipping Method require a Tax Category with a Tax Rate for the Cart's shippingAddress.
taxMode​

The new TaxMode.

Can be Disabled, External, ExternalAmount, or Platform​

TaxMode

Disabled
No taxes are added to the cart.
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 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
Platform
The tax rates are selected from the TaxCategories based on the cart shipping address. The totalNet and totalGross as well as the taxPortions fields are calculated according to the taxRoundingMode.

Change Price RoundingMode

Changing the price rounding mode leads to recalculation of taxes.
priceRoundingMode​

New value to set.

Can be HalfDown, HalfEven, or HalfUp​

RoundingMode

HalfDown
[Round half down](https://en.wikipedia.org/wiki/Rounding#Round_half_down)
HalfEven
[Round half to even](https://en.wikipedia.org/wiki/Rounding#Round_half_to_even). Default rounding mode as used in IEEE 754 computing functions and operators.
HalfUp
[Round half up](https://en.wikipedia.org/wiki/Rounding#Round_half_up)

Change Tax RoundingMode

Changing the tax rounding mode leads to recalculation of taxes.
taxRoundingMode​

New value to set.

Can be HalfDown, HalfEven, or HalfUp​

RoundingMode

HalfDown
[Round half down](https://en.wikipedia.org/wiki/Rounding#Round_half_down)
HalfEven
[Round half to even](https://en.wikipedia.org/wiki/Rounding#Round_half_to_even). Default rounding mode as used in IEEE 754 computing functions and operators.
HalfUp
[Round half up](https://en.wikipedia.org/wiki/Rounding#Round_half_up)

Change TaxCalculationMode

Changing the tax calculation mode leads to recalculation of taxes.
taxCalculationMode​

New value to set.

Can be LineItemLevel, or UnitPriceLevel​

TaxCalculationMode

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`

Add DiscountCode

code​
String​
validateDuplicates​
Boolean​
Default: false​

Remove DiscountCode

discountCode​

Discount Code to remove from the Cart.

Set DirectDiscounts

Adds a DirectDiscount to the Cart.
If Cart directDiscountsIgnoreCartDiscounts is true, Direct Discounts can only be added when no DiscountCode has been added to the Cart.
discounts​
  • If set, all existing Direct Discounts are replaced. The discounts apply in the order they are added to the list.
  • If set to an empty array, all existing Direct Discounts are removed and all affected prices on the Cart or Order are recalculated.

DirectDiscountDraft

Represents a CartDiscount that can only be associated with a single Cart or Order.
For an introduction to Direct Discounts and to understand how they work, see the Direct Discounts overview.
value​

Defines the effect the Discount will have.

target​

Defines what segment of the Cart will be discounted.

If value is set to giftLineItem, this must not be set.
participateInBestDealSelection​
Boolean​
  • If set to true, Direct Discounts compete against Product Discounts to apply the best deal.
  • If set to false, Direct Discounts are ignored when calculating the best deal comparison, and are applied on top of the discount type that offers the best deal.
This applies only when the DiscountCombinationMode for the Project is BestDeal.

CartDiscountValueInput

relative​
relativeCart​
absolute​
absoluteCart​
fixed​
fixedCart​
giftLineItem​

RelativeDiscountValueInput

permyriad​
Int​

RelativeCartDiscountValueInput

permyriad​
Int​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

DiscountApplicationMode

ProportionateDistribution
EvenDistribution
IndividualApplication

AbsoluteDiscountValueInput

money​
Array of MoneyInput​

MoneyInput

currencyCode​
centAmount​
Long​

AbsoluteCartDiscountValueInput

money​
Array of MoneyInput​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

FixedPriceDiscountValueInput

money​

CartDiscountValueBaseMoneyInput

centPrecision​
highPrecision​
currencyCode​
CurrencyCode and centAmount are deprecated. Please use Money(centPrecision) or HighPrecisionMoney(highPrecision).
centAmount​
Long​
CurrencyCode and centAmount are deprecated. Please use Money(centPrecision) or HighPrecisionMoney(highPrecision).

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

FixedPriceCartDiscountValueInput

money​
applicationMode​
Can be ProportionateDistribution, EvenDistribution, or IndividualApplication​

GiftLineItemValueInput

variantId​
Int​
distributionChannel​
supplyChannel​

CartDiscountTargetInput

lineItems​
customLineItems​
shipping​
multiBuyLineItems​
multiBuyCustomLineItems​
totalPrice​
pattern​

LineItemsTargetInput

predicate​
String​

CustomLineItemsTargetInput

predicate​
String​

ShippingTargetInput

dummy​
String​

MultiBuyLineItemsTargetInput

predicate​
String​
triggerQuantity​
Long​
discountedQuantity​
Long​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

SelectionMode

Cheapest
MostExpensive

MultiBuyCustomLineItemsTargetInput

predicate​
String​
triggerQuantity​
Long​
discountedQuantity​
Long​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

CartDiscountTotalPriceTargetInput

dummy​
String​

CartDiscountPatternTargetInput

triggerPattern​
targetPattern​
maxOccurrence​
Int​
selectionMode​
Can be Cheapest, or MostExpensive​

PatternComponentInput

CountOnLineItemUnits​
CountOnCustomLineItemUnits​

CountOnLineItemUnitsInput

predicate​
String​
minCount​
Int​
Default: 1​
maxCount​
Int​
excludeCount​
Int​

CountOnCustomLineItemUnitsInput

predicate​
String​
minCount​
Int​
Default: 1​
maxCount​
Int​
excludeCount​DEPRECATED
Int​

Please use 'triggerPattern' to exclude.

Set DirectDiscountsIgnoreCartDiscounts

Determines whether the Direct Discounts on the Cart replace the Cart Discounts of the Project, or apply alongside them.
directDiscountsIgnoreCartDiscounts​
Boolean​
The value can be set to true only if the Cart does not have both discountCodes and directDiscounts.
  • If false, Cart Discounts, Discount Codes, and Direct Discounts apply to the Cart.

Add Payment

Payment to add to the Cart. Must not be assigned to another Order or active Cart already.

Remove Payment

Payment to remove from the Cart.

Set Billing Address

address​
Value to set. It replaces the entire address, including Custom Fields if custom is not included. To preserve Custom Fields, include the custom object in the request.

If omitted, any existing value is removed.

Set Shipping Address

Setting the shipping address also sets the TaxRate of Line Items and calculates the TaxedPrice.
If a matching price cannot be found for the given shipping address during Line Item price selection, a MissingTaxRateForCountry error is returned.
If you want to allow shipping to states inside a country that are not explicitly covered by a TaxRate, set the countryTaxRateFallbackEnabled field to true in the CartsConfiguration by using the Change CountryTaxRateFallbackEnabled update action.
address​
Value to set. It replaces the entire address, including Custom Fields if custom is not included. To preserve Custom Fields, include the custom object in the request.
If not set, the shipping address is unset, and the taxedPrice and taxRate are unset in all Line Items of the Cart.

Add ItemShippingAddress

Adds an address to the itemShippingAddresses of a Cart. Use this action when shipping is defined per item. For example, when shipping items to multiple addresses or when using different Shipping Methods, even if all items share the same address.
address​
Address to append to itemShippingAddresses.
The new Address must have a key that is unique across this Cart.

Remove ItemShippingAddress

An address can only be removed if it is not referenced in any ItemShippingTarget of the Cart.
addressKey​
String​
key of the Address to remove from itemShippingAddresses.

Update ItemShippingAddress

Updates an address in itemShippingAddresses by keeping the Address key.
address​
The new Address with the same key as the Address it will replace.

Add ShippingMethod

Adds a Shipping Method for a specified shipping address to a Cart with Multiple ShippingMode.
shippingKey​
String​
User-defined identifier for the Shipping that must be unique across the Cart with Multiple ShippingMode.
shippingMethod​
ResourceIdentifier to a ShippingMethod to add to the Cart with Multiple ShippingMode. InvalidOperation error is returned in one of the following cases:
  1. If the referenced Shipping Method has a predicate that does not match the Cart.
  2. If the referenced Shipping Method is not active.
  3. If the referenced Shipping Method is associated with a Store that is different from the Cart's Store.
  4. If the referenced Shipping Method is associated with a Store and the Cart is not associated with any Store.
externalTaxRate​
Tax Rate used to tax a shipping expense if the Cart has the External TaxMode.
shippingAddress​

Determines the shipping rate and Tax Rate of the Line Items.

shippingRateInput​
Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
custom​

Custom Fields for the Shipping Method.

deliveries​
Array of DeliveryDraft​

Deliveries to be shipped with the referenced Shipping Method.

Default: []​
estimatedDelivery​

Estimated time window during which this shipment is expected to be delivered.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

ShippingRateInputDraft

Classification​
Score​

ClassificationShippingRateInputDraft

key​
String​

Key of the value used as a programmatic identifier.

ScoreShippingRateInputDraft

score​
Int​

Abstract value for categorizing a Cart.

DeliveryDraft

key​
String​

User-defined identifier of the Delivery. Must be unique among Deliveries in the Order.

items​
Line Items or Custom Line Items to deliver. It can also be specified individually for each Parcel.
parcels​
Array of ParcelDraft​

Information regarding the appearance, content, and shipment of a parcel.

address​

Address to which the Parcels are delivered.

custom​

Custom Fields for the Delivery.

DeliveryItemDraftType

id​
String​
quantity​
Long​

ParcelDraft

id​
String​
key​
String​
createdAt​
measurements​
trackingData​
items​
Default: []​
custom​

ParcelMeasurementsDraftType

heightInMillimeter​
Int​
lengthInMillimeter​
Int​
widthInMillimeter​
Int​
weightInGram​
Int​

TrackingDataDraftType

trackingId​
String​
carrier​
String​
provider​
String​
providerTransaction​
String​
isReturn​
Boolean​
Default: false​

EstimatedDeliveryDraft

from​
until​

Remove ShippingMethod

Removes a Shipping Method from a Cart that has the Multiple ShippingMode.
shippingKey​
String​

User-defined unique identifier of the Shipping Method to remove from the Cart.

Set ShippingMethod

To set the Cart's Shipping Method the Cart must have the Single ShippingMode and a shippingAddress.
This update is not allowed when the Cart is frozen with the HardFreeze FreezeStrategy.
shippingMethod​

Value to set. If omitted, any existing value is removed.

InvalidOperation error is returned in one of the following cases:
  1. If the referenced Shipping Method has a predicate that does not match the Cart.
  2. If the referenced Shipping Method is not active.
  3. If the referenced Shipping Method is associated with a Store that is different from the Cart's Store.
  4. If the referenced Shipping Method is associated with a Store and the Cart is not associated with any Store.
externalTaxRate​
An external Tax Rate can be set if the Cart has the External TaxMode.
estimatedDelivery​
Estimated time window during which the shipment is expected to be delivered. If not set, any existing estimate on the Cart's ShippingInfo is cleared.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

EstimatedDeliveryDraft

from​
until​

Add Custom ShippingMethod

To add a custom Shipping Method (independent of the ShippingMethods managed through the Shipping Methods API) to the Cart, it must have the Multiple ShippingMode.
shippingKey​
String​
User-defined identifier for the custom Shipping Method that must be unique across the Cart with Multiple ShippingMode.
shippingMethodName​
String​

Name of the custom Shipping Method.

shippingAddress​

Determines the shipping rate and Tax Rate of the associated Line Items.

shippingRate​

Determines the shipping price.

shippingRateInput​
Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:
taxCategory​
Tax Category used to determine a shipping Tax Rate if the Cart has the Platform TaxMode.
externalTaxRate​
Tax Rate used to tax a shipping expense if the Cart has the External TaxMode.
custom​

Custom Fields for the custom Shipping Method.

deliveries​
Array of DeliveryDraft​

Deliveries to be shipped with the custom Shipping Method.

Default: []​

ShippingRateInputDraft

Classification​
Score​

ClassificationShippingRateInputDraft

key​
String​

Key of the value used as a programmatic identifier.

ScoreShippingRateInputDraft

score​
Int​

Abstract value for categorizing a Cart.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

DeliveryDraft

key​
String​

User-defined identifier of the Delivery. Must be unique among Deliveries in the Order.

items​
Line Items or Custom Line Items to deliver. It can also be specified individually for each Parcel.
parcels​
Array of ParcelDraft​

Information regarding the appearance, content, and shipment of a parcel.

address​

Address to which the Parcels are delivered.

custom​

Custom Fields for the Delivery.

DeliveryItemDraftType

id​
String​
quantity​
Long​

ParcelDraft

id​
String​
key​
String​
createdAt​
measurements​
trackingData​
items​
Default: []​
custom​

ParcelMeasurementsDraftType

heightInMillimeter​
Int​
lengthInMillimeter​
Int​
widthInMillimeter​
Int​
weightInGram​
Int​

TrackingDataDraftType

trackingId​
String​
carrier​
String​
provider​
String​
providerTransaction​
String​
isReturn​
Boolean​
Default: false​

Set Custom ShippingMethod

To set the Cart's custom Shipping Method (independent of the ShippingMethods managed through the Shipping Methods API) the Cart must have the Single ShippingMode and a shippingAddress.
To unset a custom Shipping Method on a Cart, use the Set ShippingMethod update action without the shippingMethod field instead.
This update is not allowed when the Cart is frozen with the HardFreeze FreezeStrategy.
shippingMethodName​
String​

Name of the custom Shipping Method.

shippingRate​

Determines the shipping price.

taxCategory​
Tax Category used to determine the Tax Rate when the Cart has the Platform TaxMode.
externalTaxRate​
External Tax Rate for the shippingRate to be set if the Cart has the External TaxMode.
custom​

Custom Fields for the custom Shipping Method.

estimatedDelivery​
Estimated time window during which the shipment is expected to be delivered. If not set, any existing estimate on the Cart's ShippingInfo is cleared.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

EstimatedDeliveryDraft

from​
until​

Set Estimated Delivery

Sets the estimated delivery window on the Cart's ShippingInfo.
This update action produces the CartEstimatedDeliverySet Message.
estimatedDelivery​

Value to set. If empty, any existing value is removed.

shippingKey​
String​
key of the Shipping to update. This is required and valid only for Carts with Multiple ShippingMode. An InvalidOperation error is returned if shippingKey is provided for Carts with Single ShippingMode, or omitted for Carts with Multiple ShippingMode.

EstimatedDeliveryDraft

from​
until​

Set ShippingRateInput

Input used to select a ShippingRatePriceTier. If no matching tier can be found, or the input is not set, the default price for the shipping rate is used.
shippingRateInput​
The data type of this field depends on the shippingRateInputType.type configured in the Project:

ShippingRateInputDraft

Classification​
Score​

ClassificationShippingRateInputDraft

key​
String​

Key of the value used as a programmatic identifier.

ScoreShippingRateInputDraft

score​
Int​

Abstract value for categorizing a Cart.

Set Locale

locale​
Value to set. Must be one of the Project's languages. If omitted, any existing value is removed.

Set Country

Setting the country can lead to changes in the LineItem prices.
country​

Value to set. If omitted, any existing value is removed.

If the Cart is bound to a store, the provided value must be included in the Store's countries. Otherwise a CountryNotConfiguredInStore error is returned.

Set DeleteDaysAfterLastModification

Number of days after the last modification before a Cart is deleted.

Carts with CartOrigin RecurringOrder are not affected by this update action.
If a ChangeSubscription exists for Carts, a ResourceDeletedDeliveryPayload is sent.
deleteDaysAfterLastModification​
Int​
Value to set. If omitted, the default value for this field configured in Project settings is assigned.

Set Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set CustomField

name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Set Reservation Expiration in Minutes BETA

BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
reservationExpirationInMinutes​
Int​

Value to set. Must be a positive integer.

Recalculate

This update action does not set any Cart field in particular, but it triggers several Cart updates to bring prices and discounts to the latest state. Those can become stale over time when no Cart updates have been performed for a while and prices on related Products have changed in the meanwhile.
If the priceMode of the Product related to a Line Item is of Embedded ProductPriceMode, the updated price of that LineItem may not correspond to a Price in the variant.prices anymore.
updateProductData​
Boolean​
  • Leave empty or set as false to update only the Prices and TaxRates of the Line Items. Prices inside the variant are only updated if updateProductData is true.
  • Set as true to update the Product data (such as name, variant, productType, and Product Attributes) of the Line Items.
Default: false​

Freeze Cart

dummy​
String​
strategy​
Can be HardFreeze, or SoftFreeze​

FreezeStrategy

HardFreeze
Stricter version of a Cart freeze (See [Freeze a Cart](https://docs.commercetools.com/api/carts-orders-overview#freeze-a-cart) for details).
SoftFreeze
More lenient version of a Cart freeze (See [Freeze a Cart](https://docs.commercetools.com/api/carts-orders-overview#freeze-a-cart) for details).

Unfreeze Cart

dummy​
String​

Lock Cart

dummy​
String​

Unlock Cart

dummy​
String​

Set RecurringPaymentConfiguration

recurringPaymentConfiguration​

RecurringPaymentConfigurationDraft

Draft type that stores the data to create a RecurringPaymentConfiguration.
paymentStrategy​
Checkout
paymentAllocations​

Payment Methods charged for the Orders generated by the Recurring Order, and the share of the Order total charged to each of them.

PaymentStrategy

Checkout

PaymentAllocationDraft

Draft type that stores the data to create a RecurringPaymentAllocation.
id​
String​
Unique identifier of the resulting RecurringPaymentAllocation within the RecurringPaymentConfiguration.
paymentMethod​

Payment Method charged for this share of the Order total.

allocation​
Share of the Order total charged to the paymentMethod.

AllocationInputDraft

Absolute​
Relative​

AbsoluteInputDraft

amount​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

RelativeInputDraft

percentage​
Int​

Set RecurringPaymentStrategy

paymentStrategy​
Checkout

PaymentStrategy

Checkout

Add RecurringPaymentAllocation

id​
String​
paymentMethod​
allocation​

AllocationInputDraft

Absolute​
Relative​

AbsoluteInputDraft

amount​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

RelativeInputDraft

percentage​
Int​

Remove RecurringPaymentAllocation

id​
String​

on Line Item

Change LineItem Quantity

When multiple shipping addresses are set for a Line Item, use the Remove LineItem and Add LineItem update action to change the shipping details. Since it is not possible for the API to infer how the overall change in the Line Item quantity should be distributed over the sub-quantities, the shippingDetails field is kept in its current state to avoid data loss.
To change the Line Item quantity and shipping details together, use this update action in combination with the Set LineItem ShippingDetails update action in a single Cart update command.
The LineItem price is set as described in Line Item price selection.
This action is subject to InventoryEntry min/max restrictions when applicable. For more information, see Quantity limits.
If using InventoryMode ReserveOnCart:
  • If the requested quantity cannot be reserved, the Line Item quantity does not change and a CannotUpdateReservationWarning is returned in the Cart response.
  • Changing the quantity of a reserved Line Item also updates the reservation expiration time. To synchronize the expiration across the rest of the Line Items in the Cart, you must call the Set Cart Reservation Expiration in Minutes update action after any Line Item changes.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.
quantity​
Long​

New value to set.

If 0, the Line Item is removed from the Cart.
externalPrice​

Only valid for the general Carts API. Ignored for the My Carts API.

externalTotalPrice​

Only valid for the general Carts API. Ignored for the My Carts API.

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

ExternalLineItemTotalPriceDraft

price​
totalPrice​

Set LineItem TaxRate

Can be used if the Cart has the External TaxMode.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
externalTaxRate​

Value to set. If omitted, any existing value is removed.

shippingKey​
String​
key of the ShippingMethod used for this Line Item. This is required for Carts with Multiple ShippingMode.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Set LineItem TaxAmount

Can be used if the Cart has the ExternalAmount TaxMode. This update action sets the taxedPrice and taxRate on a Line Item and must be used after any price-affecting change occurs.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
externalTaxAmount​

Value to set. If omitted, any existing value is removed.

shippingKey​
String​
key of the ShippingMethod used for this Line Item. This is required for Carts with Multiple ShippingMode.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

ExternalTaxAmountDraft

totalGross​
Total gross amount (totalNet + taxPortions) of the Line Item or Custom Line Item.
taxRate​

Tax Rates and subrates of states and countries.

MoneyInput

currencyCode​
centAmount​
Long​

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Set LineItem Price

Sets the LineItem price and changes the priceMode to ExternalPrice LineItemPriceMode.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
externalPrice​
Value to set. If externalPrice is not given and the priceMode is ExternalPrice, the external price is unset and the priceMode is set to Platform.
To set the money value in high precision, use HighPrecisionMoneyDraft.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

Set LineItem TotalPrice

Sets the LineItem totalPrice and price, and changes the priceMode to ExternalTotal LineItemPriceMode. Cannot be used on Gift Line Items (see LineItemMode).
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
externalTotalPrice​
Value to set. If externalTotalPrice is not given and the priceMode is ExternalTotal, the external price is unset and the priceMode is set to Platform.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

ExternalLineItemTotalPriceDraft

price​
totalPrice​

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

Set LineItem DistributionChannel

Setting a distribution channel for a LineItem can lead to an updated price as described in Line Item price selection.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
distributionChannel​
  • If present, a Reference to the Channel is set for the LineItem specified by lineItemId.
  • If not present, the current Reference to a distribution channel is removed from the LineItem specified by lineItemId. The Channel must have the ProductDistribution ChannelRoleEnum.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

Set LineItem SupplyChannel

Performing this action does not reserve stock. Stock is only reserved at Order creation if the InventoryMode of the Cart is TrackOnly or ReserveOnOrder.
This action is subject to InventoryEntry min/max restrictions when applicable. For more information, see Quantity limits.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
supplyChannel​
  • If present, a Reference to the Channel is set for the LineItem specified by lineItemId.
  • If not present, the current Reference to a supply channel will be removed from the LineItem specified by lineItemId. The Channel must have the InventorySupply ChannelRoleEnum.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

Set LineItem ShippingDetails

lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
shippingDetails​

Value to set. If omitted, the existing value is removed.

lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

Apply DeltaToLineItemShippingDetailsTargets

lineItemId​
String​
lineItemKey​
String​
targetsDeltaDraft​
targetsDelta​

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

Set LineItemRecurrenceInfo

lineItemId​
String​
recurrenceInfo​

LineItemRecurrenceInfoInputDraft

recurrencePolicy​
expiresAt​
priceSelectionMode​
Can be Dynamic, or Fixed​

Set LineItem Custom Type

lineItemId​
String​
fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​
lineItemKey​
String​

Set LineItem CustomField

lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

Set LineItem InventoryMode

Sets the inventory mode for a specific Line Item in the Cart. When changing a Line Item's inventory mode to ReserveOnCart, a reservation is automatically created if sufficient stock is available. When changing from ReserveOnCart to another mode, the reservation is released.
lineItemId​
String​
id of the LineItem to update. Either lineItemId or lineItemKey is required.
inventoryMode​
Inventory mode specific to the Line Item only, and valid for the entire quantity of the Line Item. Set only if the inventory mode should be different from the inventoryMode specified on the Cart.
Can be None, TrackOnly, ReserveOnOrder, or ReserveOnCart​
lineItemKey​
String​
key of the LineItem to update. Either lineItemId or lineItemKey is required.

InventoryMode

None
No inventory checks or modifications when adding items or ordering. Default for a new cart.
TrackOnly
Orders decrement the available quantity on the matching inventory entry; ordering fails only when no inventory entry exists for a line item.
ReserveOnOrder
Line items are reserved only for the duration of the ordering transaction; creating an order fails when an unavailable line item exists.
ReserveOnCart
Items are reserved when added to the cart. Not supported by this service.

on Custom Line Item

Change CustomLineItem Quantity

When multiple shipping addresses are set for a Custom Line Item, use the Add CustomLineItem update action to change the shipping details. Since it is not possible for the API to infer how the overall change in the Custom Line Item quantity should be distributed over the sub-quantities, the shippingDetails field is kept in its current state to avoid data loss.
To change the Custom Line Item quantity and shipping details together, use this update action in combination with the Set CustomLineItem ShippingDetails update action in a single Cart update command.
customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
quantity​
Long​

New value to set.

If 0, the Custom Line Item is removed from the Cart.

Set CustomLineItem TaxRate

Can be used if the Cart has the External TaxMode.
customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
externalTaxRate​

Value to set. If omitted, an existing value is removed.

shippingKey​
String​
key of the ShippingMethod used for this Custom Line Item. This is required for Carts with Multiple ShippingMode.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Set CustomLineItem TaxAmount

Can be used if the Cart has the ExternalAmount TaxMode.
customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
externalTaxAmount​

Value to set. If omitted, any existing value is removed.

shippingKey​
String​
key of the ShippingMethod used for this Custom Line Item. This is required for Carts with Multiple ShippingMode.

ExternalTaxAmountDraft

totalGross​
Total gross amount (totalNet + taxPortions) of the Line Item or Custom Line Item.
taxRate​

Tax Rates and subrates of states and countries.

MoneyInput

currencyCode​
centAmount​
Long​

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Change CustomLineItem Price Mode

customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

New value to set. Must not be empty.

Can be External, or Standard​

CustomLineItemPriceMode

External
Cart discounts are deactivated for the custom line items with this price mode.
Standard
This is the default mode.

Change CustomLineItem Money

customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
money​

Value to set. Must not be empty. Can be a negative amount.

To set the money value in high precision, use HighPrecisionMoneyDraft.

BaseMoneyInput

centPrecision​
highPrecision​

MoneyInput

currencyCode​
centAmount​
Long​

HighPrecisionMoneyInput

currencyCode​
preciseAmount​
Long​
fractionDigits​
Int​
centAmount​
Long​

Set CustomLineItem ShippingDetails

customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
shippingDetails​

Value to set. If omitted, any existing value is removed.

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

Apply DeltaToCustomLineItemShippingDetailsTargets

customLineItemId​
String​
customLineItemKey​
String​
targetsDeltaDraft​
targetsDelta​

ItemShippingDetailsDraft

targets​
Default: []​
shippingTargets​
Default: []​
itemShippingAddressTargets​
Default: []​

ShippingTargetDraft

addressKey​
String​
quantity​
Long​
shippingMethodKey​
String​

ShippingMethodTargetDraft

shippingMethodKey​
String​
quantity​
Long​

ItemShippingAddressTargetDraft

addressKey​
String​
quantity​
Long​

Set CustomLineItemRecurrenceInfo

customLineItemId​
String​
customLineItemKey​
String​
recurrenceInfo​

CustomLineItemRecurrenceInfoInputDraft

recurrencePolicy​
expiresAt​

Set CustomLineItem Custom Type

customLineItemId​
String​
customLineItemKey​
String​
fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set CustomLineItem CustomField

customLineItemId​
String​
id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
customLineItemKey​
String​
key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

on Billing Address

Set Billing Address Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Billing Address CustomField

name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

on Shipping Address

Set Shipping Address Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Shipping Address CustomField

name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

on ItemShipping Address

Set ItemShipping Address Custom Type

addressKey​
String​
fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set ItemShipping Address CustomField

addressKey​
String​
key of the Address in itemShippingAddress.
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

on Shipping Method

Set ShippingMethod TaxAmount

A Shipping Method tax amount can be set if the Cart has the ExternalAmount TaxMode.
externalTaxAmount​

Value to set. If omitted, any existing value is removed.

shippingKey​
String​
key of the ShippingMethod to update. This is required and valid only for Carts with Multiple ShippingMode. An InvalidOperation error is returned if shippingKey is provided for Carts with Single ShippingMode, or omitted for Carts with Multiple ShippingMode.

ExternalTaxAmountDraft

totalGross​
Total gross amount (totalNet + taxPortions) of the Line Item or Custom Line Item.
taxRate​

Tax Rates and subrates of states and countries.

MoneyInput

currencyCode​
centAmount​
Long​

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Set ShippingMethod TaxRate

A Shipping Method Tax Rate can be set if the Cart has the External TaxMode.
externalTaxRate​

Value to set. If omitted, any existing value is removed.

shippingKey​
String​
key of the ShippingMethod to update. This is required and valid only for Carts with Multiple ShippingMode. An InvalidOperation error is returned if shippingKey is provided for Carts with Single ShippingMode, or omitted for Carts with Multiple ShippingMode.

ExternalTaxRateDraft

Controls calculation of taxed prices for Line Items, Custom Line Items, and Shipping Methods as explained in Cart tax calculation.
name​
String​

Name of the Tax Rate.

amount​
Float​

Percentage in the range of 0-1.

  • If no subRates are specified, a value must be defined.
  • If subRates are specified, this can be omitted or its value must be the sum of all subRates amounts.
country​

Country for which the tax applies.

state​
String​

State within the specified country.

subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
includedInPrice​
Boolean​
  • If set to false, the related price is considered the net price and the provided amount is applied to calculate the gross price.
  • If set to true, the related price is considered the gross price, and the provided amount is applied to calculate the net price.
Default: false​
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when includedInPrice is true. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

on Shipping

Set Shipping Custom Type

shippingKey​
String​
fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Shipping CustomField

shippingKey​
String​
The shippingKey of the Shipping to customize. Used to specify which Shipping Method to customize on a Cart with Multiple ShippingMode. Leave this empty to customize the one and only ShippingMethod on a Single ShippingMode Cart.
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.