A Cart is a representation of a shopping cart containing items that a customer intends to purchase.
A maximum of
10 000 000 Carts can be added to a Project. If a Project contains more Carts, the least recently modified resources are automatically deleted. Learn more about this limit.
The number of Discount Codes in a Cart is limited to 10.Representations
Cart-CartDraft-CartPagedQueryResponse-CartReference-CartResourceIdentifier-ReplicaCartDraft-LineItemMode-LineItemPriceMode-CustomLineItemPriceMode-RoundingMode-TaxCalculationMode-TaxMode-InventoryMode-ShippingMode-CartState-CartOrigin
TaxedPrice-TaxedItemPrice-TaxPortion-TaxPortionDraft-ExternalTaxRateDraft-ExternalTaxAmountDraft-ExternalLineItemTotalPrice-MethodExternalTaxRateDraft-MethodTaxRate-MethodTaxedPrice
DiscountedLineItemPriceForQuantity-DiscountedLineItemPrice-DiscountedLineItemPortion-DiscountedLineItemPortionDraft
Cart
id​String​ | Unique identifier of the Cart. |
version​Int​ | Current version of the Cart. |
key​String​ | User-defined unique identifier of the Cart. MinLength:Â2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​ |
customerId​String​ | id of the Customer that the Cart belongs to. |
customerEmail​String​ | Email address of the Customer that the Cart belongs to. |
customerGroup​ | Reference to the Customer Group of the Customer that the Cart belongs to. Used for Line Item price selection. |
anonymousId​String​ | Anonymous session associated with the Cart. |
businessUnit​ | |
store​ | Reference to a Store the Cart belongs to. |
lineItems​Array of LineItem​ | Line Items added to the Cart. |
customLineItems​Array of CustomLineItem​ | Custom Line Items added to the Cart. |
totalLineItemQuantity​Int​ | Sum of all LineItem quantities, excluding CustomLineItems. Only present when the Cart has at least one LineItem. |
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. |
taxedPrice​TaxedPrice​ |
If a discount applies on totalPrice, this field holds the discounted values. |
taxedShippingPrice​TaxedPrice​ | Sum of the taxedPrice field of ShippingInfo across all Shipping Methods. |
discountOnTotalPrice​ | Discounts that apply on the Cart totalPrice. |
taxMode​TaxMode​ | Indicates how Tax Rates are set. Default:ÂPlatform​ |
taxRoundingMode​RoundingMode​ | Indicates how monetary values are rounded when calculating taxes for Default: taxedPrice.HalfEven​ |
taxCalculationMode​ | Indicates how taxes are calculated when calculating taxes for Default: taxedPrice.LineItemLevel​ |
inventoryMode​ | Indicates how stock quantities are tracked for Line Items in the Cart. Default:ÂNone​ |
cartState​CartState​ | Current status of the Cart. Default:ÂActive​ |
billingAddress​Address​ | Billing address associated with the Cart. |
shippingAddress​Address​ | Shipping address for a Cart with Single ShippingMode. Determines eligible ShippingMethod rates and Tax Rates of Line Items. |
shippingMode​ShippingMode​ | Indicates whether the Cart has one or multiple Shipping Methods. Default:ÂSingle​ |
shippingKey​String​ | User-defined unique identifier of the Shipping Method in a Cart with Single ShippingMode. |
shippingInfo​ShippingInfo​ | Shipping-related information of a Cart with Single ShippingMode. Automatically set when a Shipping Method is set. |
shippingRateInput​ | Input used to select a ShippingRatePriceTier.
The data type of this field depends on the
shippingRateInputType.type configured in the Project:
|
shippingCustomFields​CustomFields​ | Custom Fields of the Shipping Method in a Cart with Single ShippingMode. |
shipping​Array of Shipping​ | Shipping-related information of a Cart with Multiple ShippingMode. Updated automatically each time a new Shipping Method is added. |
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. |
discountCodes​Array of DiscountCodeInfo​ | Discount Codes applied to the Cart. A Cart that has MaxItems: directDiscounts cannot have discountCodes.10​ |
directDiscounts​Array of DirectDiscount​ | Direct Discounts added to the Cart. A Cart that has discountCodes cannot have directDiscounts. |
refusedGifts​Array of CartDiscountReference​ | |
paymentInfo​PaymentInfo​ | Payment information related to the Cart. |
country​CountryCode​ | Used for Line Item price selection. |
locale​Locale​ | Languages of the Cart. Can only contain languages supported by the Project. |
origin​CartOrigin​ | Indicates how the Cart was created. Default:ÂCustomer​ |
discountTypeCombination​ | Indicates if a combination of discount types can apply on a Cart. |
deleteDaysAfterLastModification​Int​ | Number of days after which an active Cart is deleted since its last modification. Configured in Project settings. Default: 90​ |
custom​CustomFields​ | Custom Fields of the Cart. |
createdAt​DateTime​ | Date and time (UTC) the Cart was initially created. |
createdBy​BETACreatedBy​ | IDs and references that created the Cart. |
lastModifiedAt​DateTime​ | Date and time (UTC) the Cart was last updated. |
lastModifiedBy​BETA | IDs and references that last modified the Cart. |
CartDraft
key​String​ | User-defined unique identifier for the Cart. MinLength:Â2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​ |
currency​CurrencyCode​ | Currency the Cart uses. |
customerId​String​ | id of the Customer that the Cart belongs to. |
customerEmail​String​ | Email address of the Customer that the Cart belongs to. |
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. |
anonymousId​String​ | Anonymous session associated with the Cart. |
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. |
store​ | ResourceIdentifier to the Store the Cart should belong to. Once set, it cannot be updated. |
lineItems​Array of LineItemDraft​ | Line Items to add to the Cart. |
customLineItems​Array of CustomLineItemDraft​ | Custom Line Items to add to the Cart. |
taxMode​TaxMode​ | Determines how Tax Rates are set. Default:ÂPlatform​ |
externalTaxRateForShippingMethod​ | |
taxRoundingMode​RoundingMode​ | Determines how monetary values are rounded when calculating taxes for Default: taxedPrice.HalfEven​ |
taxCalculationMode​ | Determines how taxes are calculated for Default: taxedPrice.LineItemLevel​ |
inventoryMode​ | Determines how stock quantities are tracked for Line Items in the Cart. Default:ÂNone​ |
billingAddress​BaseAddress​ | Billing address associated with the Cart. |
shippingAddress​BaseAddress​ | 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. |
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. |
shippingRateInput​ | Used as an input to select a ShippingRatePriceTier.
The data type of this field depends on the
shippingRateInputType.type configured in the Project:
|
shippingMode​ShippingMode​ |
Single​ |
customShipping​Array of CustomShippingDraft​ | Custom Shipping Methods for a Cart with Multiple ShippingMode. |
shipping​Array of ShippingDraft​ | Shipping Methods for a Cart with Multiple ShippingMode. |
itemShippingAddresses​Array of BaseAddress​ | 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. |
discountCodes​Array of String​ | code of the existing DiscountCodes to add to the Cart. |
country​CountryCode​ | Used for Line Item price selection.
If used for Create Cart in Store, the provided country must be one of the Store's countries. |
locale​Locale​ | Languages of the Cart. Can only contain languages supported by the Project. |
origin​CartOrigin​ | Indicates how the Cart was created. Default:ÂCustomer​ |
deleteDaysAfterLastModification​Int​ | Number of days after which an active Cart is deleted since its last modification.
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. |
custom​ | Custom Fields for the Cart. |
CartPagedQueryResponse
PagedQueryResult with results containing an array of Cart.
limit​Int​ | Number of results requested. Default: 20​Minimum: 0​Maximum: 500​ |
offset​Int​ | Number of elements skipped. Default: 0​Maximum: 10000​ |
count​Int​ | Actual number of results returned. |
total​Int​ | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false.
When the results are filtered with a Query Predicate, total is subject to a limit. |
results​Array of Cart​ | Carts matching the query. |
CartReference
id​String​ | Unique identifier of the referenced Cart. |
typeId​ | cartType of referenced resource. |
obj​Cart​ | Contains the representation of the expanded Cart. Only present in responses to requests with Reference Expansion for Carts. |
CartResourceIdentifier
ResourceIdentifier to a Cart. Either
id or key is required. If both are set, an InvalidJsonInput error is returned.id​String​ | Unique identifier of the referenced Cart. Required if key is absent. |
key​String​ | User-defined unique identifier of the referenced Cart. Required if id is absent. |
typeId​ | cartType of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
ReplicaCartDraft
Used for replicating an existing Cart or Order.
key​String​ | User-defined unique identifier for the Cart. |
reference​Can be CartReference, or OrderReference​ |
LineItemMode
Indicates how a Line Item was added to a Cart.
Standard- The Line Item was added during Cart creation or the Add LineItem update action. The Line Item quantity can be changed without restriction.
GiftLineItem- One Line Item was added automatically to a Cart by a Cart Discount with CartDiscountValueGiftLineItemDraft.The quantity cannot be increased, and it won't be merged when adding the same Line Item to the Cart. If the gift is removed, an entry is added to the
refusedGiftsarray and the discount won't be applied to the Cart. The price cannot be changed externally.All other updates, such as the ones related to Custom Fields, can be used.
LineItemPriceMode
This mode indicates how the price is set for the Line Item.
Platform- The price is selected from the Product Variant. This is the default mode.
ExternalPrice- The Line Item price is 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
externalPricefield to be given. ExternalTotal- The Line Item price with the total is set externally. Cart Discounts are deactivated for Line Items with this price mode, despite a matching CartDiscountLineItemsTarget or MultiBuyLineItemsTarget. Although a Line Item with this price mode has both
priceandtotalPriceset externally, onlytotalPriceis used to calculate the total price of a Cart. All update actions that change the quantity of a Line Item with this price mode can set the new price with theexternalTotalPricefield. If theexternalTotalPricefield is not given in the update actions, the external price is unset and the price mode is set toPlatform.
CustomLineItemPriceMode
Determines if Cart Discounts can be applied to a Custom Line Item in the Cart.
Standard- Allows application of Cart Discounts for the Custom Line Item.
This is the default mode for backwards compatibility.
External- Deactivates application of Cart Discounts for the Custom Line Item despite a matching CartDiscountCustomLineItemsTarget, MultiBuyCustomLineItemsTarget, or CartDiscountPatternTarget.
RoundingMode
Determines how monetary values are rounded.
HalfEven-
Default mode for a new Cart.
HalfUpHalfDown
The following example shows how decimal values are rounded:
| Value to round | HalfUp | HalfDown | HalfEven |
|---|---|---|---|
| 23.5 | 24 | 23 | 24 |
| 24.5 | 25 | 24 | 24 |
| 25.5 | 26 | 25 | 26 |
TaxCalculationMode
Determines in which Tax calculation mode taxed prices are calculated.
LineItemLevel- Taxes are calculated after the unit price is multiplied by the quantity. This is the default mode.For example,
($1.08 * 3 = $3.24) * 1.19 = $3.8556 -> $3.86 rounded UnitPriceLevel- Taxes are calculated on the unit price before multiplying by the quantity.For example,
($1.08 * 1.19 = $1.2852 -> $1.29 rounded) * 3 = $3.87
The combination of
UnitPriceLevel and ExternalTotal LineItemPriceMode is not supported. Requests using this combination will be rejected with an InvalidOperation error.TaxMode
Indicates how taxes are set on the Cart.
Platform-
Tax Rates are selected automatically from the TaxCategories based on the Cart
shippingAddress. This is the default tax mode for a new Cart. -
The
totalNet,totalGross, andtaxPortionsfields are calculated based on thetaxRoundingMode.
-
External-
Tax Rates are set externally with ExternalTaxRateDraft. A Cart can be ordered only if all Line Items, Custom Line Items, and the Shipping Method have an external Tax Rate set.
-
The
totalNet,totalGross, andtaxPortionsfields are calculated based on thetaxRoundingMode.
-
ExternalAmount-
Tax amounts, Tax Rates, and tax portions are set externally with ExternalTaxAmountDraft. A Cart can be ordered only if the Cart and all Line Items, Custom Line Items, and the Shipping Method have an external tax amount and rate set.
-
The Cart
taxedPricefield must be set using Set Cart Total Tax. The CarttaxedShippingPricefield is always empty in this tax mode. -
Price-affecting update actions on Carts require external recalculation of the total gross price. In these cases,
taxedPriceandtaxRateare removed and must be set again. The order in which the individual update actions are issued is important:-
Issue the price-affecting update action(s).
-
Update the tax amounts using Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount.
-
If the update action changes the Line Item price, for Line Items with
PlatformLineItemPriceMode, you must issue Set LineItem TaxAmount in a separate request. -
If the update action removes the externally set tax amount for the Shipping Method, you must issue Set ShippingMethod TaxAmount in a separate request.
-
-
Update the
taxedPriceon Cart using Set Cart Total Tax.
-
-
Tax-inclusive pricing should be avoided when using TaxMode
ExternalAmountbecausetaxedItemPrice.totalNetis automatically set by the platform to the Line Item'stotalPrice.
-
Disabled- No taxes are added to the Cart.
- This tax mode cannot be set on the My Carts API.
InventoryMode
Indicates how Line Items in a Cart are tracked.
NoneAdding and ordering items from a Cart are independent of the Inventory with no inventory checks or modifications.
This is the default mode.
TrackOnly- Orders are tracked on the Inventory, and ordering a LineItem deducts the available quantity on the respective InventoryEntry.An Order can be created even if the Line Item quantity is zero or negative, but if no matching Inventory Entry exists for the Line Item, an OutOfStock error is returned.
ReserveOnOrder- Line Items in a Cart are only reserved for the duration of the ordering transaction. If a Line Item is not available when creating an Order, an OutOfStock error is returned. This is because the InventoryEntry
availableQuantityis insufficient (but is still updated) for the ordered Line Item quantity.
ShippingMode
SingleCart can contain only a single Shipping Method. This is the default mode for backwards compatibility.
MultipleCart can contain multiple Shipping Methods.
CartState
Indicates the current status of a Cart.
Active- The default state where a Cart can be updated and ordered. A Customer can have more than one active Cart.
Merged- An anonymous Cart was merged into a Customer's Cart on sign-in, and no further operations are allowed on the Cart.
Ordered- A Cart was ordered, and no further operations are allowed on the Cart.
Frozen- A Cart is frozen. Update actions that can change the price of (Custom) Line Items are not allowed.
CartOrigin
Indicates who created the Cart.
CustomerCart was created by a Customer.
This is the default value.
MerchantCart was created by a merchant on behalf of a Customer.
QuoteCart was created as part of a Quote.
LineItem
id​String​ | Unique identifier of the LineItem. |
key​String​ | User-defined unique identifier of the LineItem. |
productId​String​ | id of the Product the Line Item is based on. |
productKey​String​ | key of the Product.This field is only present on:
Present on resources created or updated after 3 December 2021. |
name​ | Name of the Product. |
productSlug​ | 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. |
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​ | 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. |
quantity​Int​ | |
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. |
discountedPricePerQuantity​Array of DiscountedLineItemPriceForQuantity​ | Discounted price of a single quantity of the Line Item. |
taxedPrice​ | Automatically set after taxRate is set. |
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. |
state​Array of ItemState​ | |
taxRate​TaxRate​ |
|
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. |
supplyChannel​ | Identifies Inventory entries that are reserved. The referenced Channel has the InventorySupply ChannelRoleEnum. |
distributionChannel​ | |
priceMode​ | Indicates how the Price for the Line Item is set. |
lineItemMode​LineItemMode​ | Indicates how the Line Item is added to the Cart. Default:ÂStandard​ |
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. |
shippingDetails​ | Container for Line Item-specific addresses. |
addedAt​DateTime​ | Date and time (UTC) the Line Item was added to the Cart. |
custom​CustomFields​ | Custom Fields of the Line Item. |
lastModifiedAt​DateTime​ | Date and time (UTC) the Line Item was last updated. |
LineItemDraft
For Product Variant identification, either the
productId and variantId, or sku must be provided.key​String​ | User-defined unique identifier of the LineItem. MinLength:Â2​MaxLength: 256​Pattern: ^[a-zA-Z0-9_-]​ |
productId​String​ | id of a published Product. |
variantId​Int​ | id of the ProductVariant in the Product.
If not provided, the Master Variant is used. |
sku​String​ | sku of the ProductVariant. |
quantity​Int​ | Quantity of the Product Variant to add to the Cart. Default:Â1​ |
addedAt​DateTime​ | Date and time (UTC) the Product Variant is added to the Cart. If not set, it defaults to the current date and time. Optional for backwards compatibility reasons. |
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. |
supplyChannel​ | Used to identify Inventory entries that must be reserved.
The referenced Channel must have the InventorySupply ChannelRoleEnum. |
externalPrice​Money​ | |
externalTotalPrice​ | Sets the LineItem price and totalPrice values, and the priceMode to ExternalTotal LineItemPriceMode. |
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. |
perMethodExternalTaxRate​Array of MethodExternalTaxRateDraft​ | Sets the external Tax Rates for individual Shipping Methods, if the Cart has the External TaxMode and Multiple ShippingMode. |
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. |
shippingDetails​ | Container for Line Item-specific addresses. |
custom​ | Custom Fields for the Line Item. |
CustomLineItem
A generic item that can be added to the Cart but is not bound to a Product that can be used 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 unique identifier of the Custom Line Item. |
name​ | Name of the Custom Line Item. |
money​TypedMoney​ | Money value of the Custom Line Item. |
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. |
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. |
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​Int​ | |
state​Array of ItemState​ | |
taxCategory​ | Used to select a Tax Rate when a Cart has the Platform TaxMode. |
taxRate​TaxRate​ |
|
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​Array of DiscountedLineItemPriceForQuantity​ | Discounted price of a single quantity of the Custom Line Item. |
shippingDetails​ | Container for Custom Line Item-specific addresses. |
priceMode​ | Indicates whether Cart Discounts with a matching CartDiscountCustomLineItemsTarget, MultiBuyCustomLineItemsTarget, or CartDiscountPatternTarget are applied to the Custom Line Item. |
custom​CustomFields​ | Custom Fields of the Custom Line Item. |
CustomLineItemDraft
key​String​ | User-defined unique identifier of the Custom Line Item. MinLength:Â2​MaxLength: 256​Pattern: ^[a-zA-Z0-9_-]​ |
name​ | Name of the Custom Line Item. |
quantity​Int​ | Number of Custom Line Items to add to the Cart. Default:Â1​ |
money​Money​ | Money value of the Custom Line Item. The value can be negative. |
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​ | |
externalTaxRate​ | External Tax Rate for the Custom Line Item if the Cart has the External TaxMode. |
shippingDetails​ | Container for Custom Line Item-specific addresses. |
priceMode​ |
Standard​ |
custom​ | Custom Fields for the Custom Line Item. |
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. |
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
name​String​ | Name of the tax portion. |
rate​Float​ | A number in the range 0-1. Minimum:Â0​Maximum: 1​ |
amount​ | Money value of the tax portion. |
TaxPortionDraft
Represents the portions that sum up to the
totalGross field of a TaxedPrice.name​String​ | Name of the tax portion. |
rate​Float​ | A number in the range 0-1. Minimum:Â0​Maximum: 1​ |
amount​Money​ | Money value for the tax portion. |
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.
0​Maximum: 1​ |
includedInPrice​Boolean​ |
|
country​CountryCode​ | Country for which the tax applies. |
state​String​ | State within the specified country. |
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. |
ExternalTaxAmountDraft
Cannot be used in LineItemDraft or CustomLineItemDraft.
Can only be set by these update actions:
- Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount on Carts
- Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount on Order Edits
totalGross​Money​ | Total gross amount ( totalNet + taxPortions) of the Line Item or Custom Line Item. |
taxRate​ | Tax Rates and subrates of states and countries. |
Changes on the Cart or OrderEdit that have a financial impact invalidate the previously set total gross price. For example, when a Cart Discount reduces the Line Item price, the previously set total gross price becomes invalid and the recalculated total gross price must be set again with an ExternalTaxAmountDraft by another update action.
ExternalLineItemTotalPrice
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. |
MethodTaxRate
shippingMethodKey​String​ | User-defined unique identifier of the Shipping Method in a Cart with Multiple ShippingMode. |
taxRate​TaxRate​ | Tax Rate for the Shipping Method. |
MethodTaxedPrice
shippingMethodKey​String​ | |
taxedPrice​ | Total taxed price based on the quantity of the Line Item or Custom Line Item assigned to the Shipping Method identified by shippingMethodKey. |
DiscountedLineItemPriceForQuantity
quantity​Int​ | Number of Line Items or Custom Line Items in the Cart. |
discountedPrice​ | Discounted price of the Line Item or Custom Line Item. |
DiscountedLineItemPrice
value​TypedMoney​ | Money value of the discounted Line Item or Custom Line Item. |
includedDiscounts​Array of DiscountedLineItemPortion​ | Discount applicable on the Line Item or Custom Line Item. |
DiscountedLineItemPortion
discount​Reference​ | A CartDiscountReference or DirectDiscountReference of the applicable discount on the Line Item. |
discountedAmount​TypedMoney​ | Money value of the applicable discount. |
DiscountedLineItemPortionDraft
discount​Reference​ | A CartDiscountReference or DirectDiscountReference for the discount applicable on the Line Item. |
discountedAmount​ | Money value for the discount applicable. |
DiscountOnTotalPrice
discountedAmount​TypedMoney​ | Money value of the discount on the total price of the Cart or Order. |
includedDiscounts​Array of DiscountedTotalPricePortion​ | Discounts that impact the total price of the Cart or Order. |
discountedNetAmount​TypedMoney​ | 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​TypedMoney​ | 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​Reference​ | |
discountedAmount​TypedMoney​ | Money value of the discount. |
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. Empty when the value is set to giftLineItem. |
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 in Composable Commerce, 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. |
{
"value": {
"type": "relative",
"permyriad": 1000
},
"target": {
"type": "lineItems",
"predicate": "1=1"
}
}DirectDiscountReference
Reference to a DirectDiscount.
id​String​ | Unique identifier of the referenced DirectDiscount. |
typeId​ | direct-discountType of referenced resource. |
DiscountCodeInfo
discountCode​ | Discount Code associated with the Cart or Order. |
state​ | Indicates the state of the Discount Code applied to the Cart or Order. |
DiscountCodeState
Indicates the state of a Discount Code in a Cart.
If an Order is created from a Cart with a state other than
MatchesCart, a DiscountCodeNonApplicable error is returned.NotActiveThe Discount Code is not active or does not contain any active Cart Discounts.
NotValid- The Discount Code is not valid or does not contain any valid Cart Discounts. Validity is determined by the CartDiscount
validFromandvalidUntildates. DoesNotMatchCart- The Discount Code is active and contains at least one active and valid Cart Discount. The DiscountCode
cartPredicatedoes not match the Cart or the contained active discount's cart predicates do no match the Cart. MatchesCart- The Discount Code is active and contains at least one active and valid Cart Discount. The DiscountCode
cartPredicatematches the Cart and at least one of the contained active discount's cart predicates matches the Cart. MaxApplicationReachedApplicationStoppedByPreviousDiscount- The Discount Code is active and no discounts are applied after a discount with
StopAfterThisDiscountStackingMode is defined.
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​ShippingRate​ | Used to determine the price. |
taxedPrice​ | Automatically set after the taxRate is set. |
taxRate​TaxRate​ | |
taxCategory​ | Used to select a Tax Rate when a Cart has the Platform TaxMode. |
shippingMethod​ | Not set if a custom Shipping Method is used. |
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. |
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​BaseAddress​ | 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. |
Shipping
shippingKey​String​ | User-defined unique identifier of the Shipping in a Cart with Multiple ShippingMode. |
shippingInfo​ShippingInfo​ | Automatically set when the Shipping Method is added. |
shippingAddress​Address​ | 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​CustomFields​ | Custom Fields of Shipping with Multiple ShippingMode. |
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​BaseAddress​ | 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. |
ShippingMethodState
Determines whether the selected ShippingMethod is allowed for the Cart. For more information, see Predicates.
DoesNotMatchCart- The ShippingMethod
predicatedoes not match the Cart.Ordering this Cart returns an ShippingMethodDoesNotMatchCart error. MatchesCart
ShippingRateInput
Generic type for the input used to select a ShippingRatePriceTier.
The specific data type depends on the
shippingRateInputType.type configured in the Project:- If
CartClassification, it is ClassificationShippingRateInput. - If
CartScore, it is ScoreShippingRateInput. - If
CartValue, it cannot be used.
ClassificationShippingRateInput
key​String​ | Key of the value used as a programmatic identifier. |
type​String​ | "Classification" |
label​ | Descriptive localized label of the value. |
ScoreShippingRateInput
type​String​ | "Score" |
score​Int​ | Abstract value for categorizing a Cart. |
ShippingRateInputDraft
Generic draft type for setting the input to select a ShippingRatePriceTier.
The specific data type to use depends on the
shippingRateInputType.type configured in the Project:- If
CartClassification, it must be ClassificationShippingRateInputDraft. - If
CartScore, it must be ScoreShippingRateInputDraft. - If
CartValue, it cannot be set.
ClassificationShippingRateInputDraft
key​String​ | Key of the value used as a programmatic identifier. |
type​String​ | "Classification" |
ScoreShippingRateInputDraft
type​String​ | "Score" |
score​Int​ | Abstract value for categorizing a Cart. |
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​ |
|
ItemShippingDetailsDraft
For order creation and updates, the sum of the
targets must match the quantity of the Line Items or Custom Line Items.targets​Array of ItemShippingTarget​ | Holds information on the quantity of Line Items or Custom Line Items and the address it is shipped. If multiple shipping addresses are present for a Line Item or Custom Line Item, sub-quantities must be specified. |
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​Int​ | 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. |
ItemState
quantity​Int​ | Number of Line Items or Custom Line Items in this State. |
state​ | State of the Line Items or Custom Line Items in a custom workflow. |
DiscountTypeCombination
Indicates if a combination of discount types can apply on a Cart or Order.
BestDeal
Indicates the best deal logic applies to a Cart or Order and indicates the discount type that offers the best deal.
type​String​ | "BestDeal" |
chosenDiscountType​String​ | Discount type that offers the best deal; the value can be product-discount or cart-discount. |
Stacking
Indicates both Product Discounts and Cart Discounts apply to a Cart and Order.
type​String​ | "Stacking" |
Get Cart
The following methods retrieve a Cart accessible globally in the Project. For retrieving Carts available in a Store only, use the Get Cart in Store methods instead.
Get Cart by ID
GET
https://api.{region}.commercetools.com/{projectKey}/carts/{id}
Retrieves a Cart with the provided
id.
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Get Cart by Key
GET
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}
Retrieves a Cart with the provided
key.
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Get Cart by Customer ID
GET
https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId}
Retrieves the most recently modified active Cart of a Customer with CartOrigin
Customer. If no active Cart exists, this method returns a ResourceNotFound error.To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
customerIdString ​ | customerId of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Get Cart in Store
Get Cart in Store by ID
GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}
Retrieves a Cart with the provided
id in a Store.If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
idString ​ | id of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Get Cart in Store by Key
GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}
Retrieves a Cart with the provided
key in a Store.If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
keyString ​ | key of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Get Cart in Store by Customer ID
GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId}
Retrieves the most recently modified active Cart of a Customer with CartOrigin
Customer. If no active Cart exists, this method returns a ResourceNotFound error.If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
customerIdString ​ | customerId of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Query Carts
GET
https://api.{region}.commercetools.com/{projectKey}/carts
Retrieves Carts in the Project.
OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
Query parameters:
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limitInt ​ | Number of results requested. Default: 20​Minimum: 0​Maximum: 500​ |
offsetInt ​ | Number of elements skipped. Default: 0​Maximum: 10000​ |
withTotalBoolean ​ | Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.Default: true​ |
var.<varName>String ​ | Predicate parameter values. The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"type": "Cart",
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2015-09-22T15:36:17.510Z",
"lastModifiedAt": "2015-09-22T15:41:55.816Z",
"lineItems": [
{
"id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name": {
"en": "SAPPHIRE"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "sapphire1421832124423"
},
"variant": {
"id": 1,
"sku": "sku_SAPPHIRE_variant1_1421832124423",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity": 2,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 2,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
},
{
"type": "Cart",
"id": "668e5783-73c8-4f2d-91f4-3c90b872c700",
"version": 3,
"createdAt": "2015-10-07T07:33:05.894Z",
"lastModifiedAt": "2015-10-07T07:33:06.070Z",
"lineItems": [
{
"id": "90dff06c-272e-47fa-b8de-923dce092474",
"productId": "7b1203f4-66c0-438c-9a30-f4fb6be79bdf",
"name": {
"de": "WB ATHLETIC PANZER",
"en": "WB ATHLETIC TANK"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "wb-athletic-tank1421832124574"
},
"variant": {
"id": 1,
"sku": "sku_WB_ATHLETIC_TANK_variant1_1421832124574",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/253265444_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"custom": {
"type": {
"typeId": "type",
"id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
},
"fields": {
"offer_name": "SuperMax"
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"country": "DE",
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
}
]
}Query Carts in Store
GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts
Retrieves Carts in a Store.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
Query parameters:
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limitInt ​ | Number of results requested. Default: 20​Minimum: 0​Maximum: 500​ |
offsetInt ​ | Number of elements skipped. Default: 0​Maximum: 10000​ |
withTotalBoolean ​ | Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.Default: true​ |
var.<varName>String ​ | Predicate parameter values. The parameter can be passed multiple times. |
Response:
200as
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"type": "Cart",
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2015-09-22T15:36:17.510Z",
"lastModifiedAt": "2015-09-22T15:41:55.816Z",
"lineItems": [
{
"id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name": {
"en": "SAPPHIRE"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "sapphire1421832124423"
},
"variant": {
"id": 1,
"sku": "sku_SAPPHIRE_variant1_1421832124423",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 2800
},
"id": "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity": 2,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 2,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 5600
},
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
},
{
"type": "Cart",
"id": "668e5783-73c8-4f2d-91f4-3c90b872c700",
"version": 3,
"createdAt": "2015-10-07T07:33:05.894Z",
"lastModifiedAt": "2015-10-07T07:33:06.070Z",
"lineItems": [
{
"id": "90dff06c-272e-47fa-b8de-923dce092474",
"productId": "7b1203f4-66c0-438c-9a30-f4fb6be79bdf",
"name": {
"de": "WB ATHLETIC PANZER",
"en": "WB ATHLETIC TANK"
},
"productType": {
"typeId": "product-type",
"id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version": 8
},
"productSlug": {
"en": "wb-athletic-tank1421832124574"
},
"variant": {
"id": 1,
"sku": "sku_WB_ATHLETIC_TANK_variant1_1421832124574",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/253265444_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
],
"attributes": [],
"assets": []
},
"price": {
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"id": "37696f7c-8260-4941-a921-68e6aa76b4a3"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"custom": {
"type": {
"typeId": "type",
"id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
},
"fields": {
"offer_name": "SuperMax"
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 8400
},
"country": "DE",
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"shipping": [],
"shippingMode": "Single"
}
]
}Check if Cart exists
Check if Cart exists by ID
HEAD
https://api.{region}.commercetools.com/{projectKey}/carts/{id}
Checks if a Cart exists for the provided
id. Returns a 200 OK status if the Cart exists or Not Found otherwise.OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Cart. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Cart exists by Key
HEAD
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}
Checks if a Cart exists with the provided
key. Returns a 200 OK status if the Cart exists or Not Found otherwise.OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Cart. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Cart exists by Customer ID
HEAD
https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId}
Checks if a Cart exists for a Customer. Returns a
200 OK status if the Cart exists or Not Found otherwise.OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
customerIdString ​ | customerId of the Cart. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/carts/customer-id={customerId} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"Check if Cart exists by Query Predicate
HEAD
https://api.{region}.commercetools.com/{projectKey}/carts
Checks if one or more Carts exist for the provided query predicate. Returns a
200 OK status if any Carts match the query predicate, or Not Found otherwise.OAuth 2.0 Scopes:
view_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
Query parameters:
where | The parameter can be passed multiple times. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Cart exists in Store
Check if Cart exists in Store by ID
HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}
Checks if a Cart exists with the provided
id in a Store. Returns a 200 OK status if the Cart exists or Not Found otherwise.OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
idString ​ | id of the Cart. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Cart exists in Store by Key
HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
keyString ​ | key of the Cart. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Cart exists in Store by Customer ID
HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId}
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
customerIdString ​ | customerId of the Cart. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/customer-id={customerId} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"Check if Cart exists in Store by Query Predicate
HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
Query parameters:
where | The parameter can be passed multiple times. |
Response:
200
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Create Cart
POST
https://api.{region}.commercetools.com/{projectKey}/carts
Creates a Cart in the Project.
If the referenced ShippingMethod in the CartDraft has a predicate that does not match, or if the Shipping Method is not active, an InvalidOperation error is returned.
Specific Error Codes:
OAuth 2.0 Scopes:
manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
Query parameters:
expand | The parameter can be passed multiple times. |
Request Body:CartDraftas
application/jsonResponse:
201as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/carts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"currency" : "EUR"
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Create Cart in Store
POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts
Creates a Cart in a Store.
If the referenced ShippingMethod in the CartDraft has a predicate that does not match, or if the Shipping Method is not active, an InvalidOperation error is returned.
Specific Error Codes:
OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
Query parameters:
expand | The parameter can be passed multiple times. |
Request Body:CartDraftas
application/jsonResponse:
201as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"currency" : "EUR"
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Replicate Cart
POST
https://api.{region}.commercetools.com/{projectKey}/carts/replicate
Creates a new Cart by replicating an existing Cart or Order. Can be useful in cases where a customer wants to cancel a recent order to make some changes or reorder a previous order.
The replicated Cart preserves Customer information, Line Items and Custom Line Items, Custom Fields, Discount Codes, and other settings of the Cart or Order. If the Line Items become invalid, for example, due to removed Products or Prices, they are removed from the new Cart. If the Customer switches to another Customer Group, the new Cart is updated with the new value. It has up-to-date Tax Rates, Prices, and Line Item product data and is in
Active CartState.The new Cart does not contain Payments or Deliveries. The State of Line Items and Custom Line Items is reset to
initial.Specific Error Codes:
OAuth 2.0 Scopes:
manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
Request Body:ReplicaCartDraftas
application/jsonResponse:
201as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/carts/replicate -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"reference" : {
"id" : "74dcac8b-0c67-4f37-b693-3acd33e3c457",
"typeId" : "cart"
}
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Replicate Cart in Store
POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/replicate
Creates a new Cart by replicating an existing Cart or Order. Can be useful in cases where a customer wants to cancel a recent order to make some changes or reorder a previous order.
The replicated Cart preserves Customer information, Line Items and Custom Line Items, Custom Fields, Discount Codes, and other settings of the Cart or Order. If the Line Items become invalid, for example, due to removed Products or Prices, they are removed from the new Cart. If the Customer switches to another Customer Group, the new Cart is updated with the new value. It has up-to-date Tax Rates, Prices, and Line Item product data and is in
Active CartState.The new Cart does not contain payments or deliveries. The State of Line Items and Custom Line Items is reset to
initial.Specific Error Codes:
OAuth 2.0 Scopes:
manage_orders:{projectKey}:{storeKey}manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
Request Body:ReplicaCartDraftas
application/jsonResponse:
201as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/replicate -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"reference" : {
"id" : "74dcac8b-0c67-4f37-b693-3acd33e3c457",
"typeId" : "cart"
}
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Update Cart
The following methods update a Cart accessible globally in the Project. For updating Carts available in a Store only, use the Update Cart in Store methods instead.
Calling these methods might lead to additional Cart updates not explicitly requested by update actions.
Update Cart by ID
POST
https://api.{region}.commercetools.com/{projectKey}/carts/{id}
Updates a Cart in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Request Body:
application/jsonversion​Int​ | Expected version of the Cart on which the changes apply.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions​Array of CartUpdateAction​ | Update actions to be performed on the Cart. |
Response:
200as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/carts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Update Cart by Key
POST
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}
Updates a Cart in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Request Body:
application/jsonversion​Int​ | Expected version of the Cart on which the changes apply.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions​Array of CartUpdateAction​ | Update actions to be performed on the Cart. |
Response:
200as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/carts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Update Cart in Store
The following methods update a Cart from a specific Store. For updating Carts accessible globally in the Project, use the Update Cart methods instead.
Calling these methods might lead to additional Cart updates not explicitly requested by update actions.
Update Cart in Store by ID
POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}
Updates a Cart in a Store using one or more update actions.
If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
idString ​ | id of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Request Body:
application/jsonversion​Int​ | Expected version of the Cart on which the changes apply.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions​Array of CartUpdateAction​ | Update actions to be performed on the Cart. |
Response:
200as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Update Cart in Store by Key
POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}
Updates a Cart in a Store using one or more update actions.
If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
keyString ​ | key of the Cart. |
Query parameters:
expand | The parameter can be passed multiple times. |
Request Body:
application/jsonversion​Int​ | Expected version of the Cart on which the changes apply.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions​Array of CartUpdateAction​ | Update actions to be performed on the Cart. |
Response:
200as
application/jsoncurl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "addLineItem",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"variantId" : 1,
"quantity" : 1
} ]
}
DATA{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Update actions
on Cart-Set Key-Set Customer ID-Set Customer Email-Set Customer Group-Set Anonymous ID-Set Business Unit -Add LineItem-Remove LineItem-Change LineItems Order-Add CustomLineItem-Remove CustomLineItem-Add Shopping List-Set Cart Total Tax-Change TaxMode-Change Tax RoundingMode-Change TaxCalculationMode-Add DiscountCode-Remove DiscountCode-Set DirectDiscounts-Add Payment-Remove Payment-Set Billing Address-Set Shipping Address-Add ItemShippingAddress-Remove ItemShippingAddress-Update ItemShippingAddress-Add ShippingMethod-Remove ShippingMethod-Set ShippingMethod-Add Custom ShippingMethod-Set Custom ShippingMethod-Set ShippingRateInput-Set Locale-Set Country-Set DeleteDaysAfterLastModification-Set Custom Type-Set CustomField-Recalculate-Freeze Cart-Unfreeze Cart
on Line Item-Change LineItem Quantity-Set LineItem TaxRate-Set LineItem TaxAmount-Set LineItem Price-Set LineItem TotalPrice-Set LineItem DistributionChannel-Set LineItem SupplyChannel-Set LineItem ShippingDetails-Apply DeltaToLineItemShippingDetailsTargets-Set LineItem Custom Type-Set LineItem CustomField-Set LineItem InventoryMode
on Custom Line Item-Change CustomLineItem Quantity-Set CustomLineItem TaxRate-Set CustomLineItem TaxAmount-Change CustomLineItem Price Mode-Change CustomLineItem Money-Set CustomLineItem ShippingDetails-Apply DeltaToCustomLineItemShippingDetailsTargets-Set CustomLineItem Custom Type-Set CustomLineItem CustomField
on Cart
Set Key
action​String​ | "setKey" |
key​String​ | Value to set. If empty, any existing key will be removed. MinLength:Â2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​ |
{
"action": "setKey",
"key": "myNewKey"
}Set Customer ID
If the Customer with the specified
id cannot be found, this update action returns a
ReferencedResourceNotFound error.action​String​ | "setCustomerId" |
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 empty, the update action removes the value for both customerId and customerGroup. |
{
"action": "setCustomerId",
"customerId": "{{customer-id}}"
}Set Customer Email
action​String​ | "setCustomerEmail" |
email​String​ | Value to set. If empty, any existing value is removed. |
{
"action": "setCustomerEmail",
"email": "email@example.com"
}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.
action​String​ | "setCustomerGroup" |
customerGroup​ | Value to set. If empty, any existing value is removed. |
{
"action": "setCustomerGroup",
"customerGroup": {
"id": "{{customer-group-id}}",
"typeId": "customer-group"
}
}Set Anonymous ID
If the Cart is already associated with a Customer, an InvalidOperation error is returned.
action​String​ | "setAnonymousId" |
anonymousId​String​ | Value to set. If empty, any existing value is removed. |
{
"action": "setAnonymousId",
"anonymousId": "idString"
}Set Business Unit B2B
Updates the Business Unit on the Cart. The Cart must have an existing Business Unit assigned already.
action​String​ | "setBusinessUnit" |
businessUnit​ | New Business Unit to assign to the Cart, which must have access to the Store that is set on the Cart. |
{
"action": "setBusinessUnit",
"businessUnit": {
"key": "{{business-unit-key}}",
"typeId": "business-unit"
}
}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.If the Line Items are added to a Cart bound to a Store with active Product Selections, the selected Product Variant must be available in that Store, otherwise an InvalidInput error is returned.
action​String​ | "addLineItem" |
key​String​ | User-defined unique identifier of the LineItem. MinLength:Â2​MaxLength: 256​Pattern: ^[a-zA-Z0-9_-]​ |
productId​String​ | id of the published Product.Either the productId and variantId, or sku must be provided. |
variantId​Int​ | id of the ProductVariant in the Product.
If not provided, the Master Variant is used.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​Int​ | Quantity of the Product Variant to add to the Cart. Default:Â1​ |
addedAt​DateTime​ | Date and time (UTC) the Product Variant is added to the Cart. If not set, it defaults to the current date and time. Optional for backwards compatibility reasons. |
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. |
supplyChannel​ | Used to identify Inventory entries that must be reserved.
The Channel must have the InventorySupply ChannelRoleEnum. |
externalPrice​Money​ | |
externalTotalPrice​ | Sets the LineItem price and totalPrice values, and the priceMode to ExternalTotal LineItemPriceMode. |
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. |
perMethodExternalTaxRate​Array of MethodExternalTaxRateDraft​ | Sets the external Tax Rates for individual Shipping Methods, if the Cart has the External TaxMode and Multiple ShippingMode. |
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. |
shippingDetails​ | Container for Line Item-specific addresses. |
custom​ | Custom Fields for the Line Item. |
{
"action": "addLineItem",
"productId": "{{product-id}}",
"variantId": 2,
"quantity": 1,
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
},
"distributionChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
},
"externalTaxRate": {
"name": "StandardExternalTaxRate",
"amount": 0.19,
"country": "DE",
"state": "Bavaria"
},
"shippingDetails": {
"targets": [
{
"addressKey": "AddressKeyStringFromAddress",
"quantity": 2
}
]
}
}Remove LineItem
The LineItem price is updated as described in Line Item price selection.
action​String​ | "removeLineItem" |
lineItemId​String​ | |
lineItemKey​String​ | |
quantity​Int​ | Amount to subtract from the LineItem's Minimum: quantity.
If absent, the LineItem is removed from the Cart.0​ |
externalPrice​Money​ | Sets the LineItem price to the given value when decreasing the quantity of a Line Item with the ExternalPrice LineItemPriceMode. |
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. |
{
"action": "removeLineItem",
"lineItemId": "{{lineItemId}}",
"quantity": 1,
"externalPrice": {
"currencyCode": "EUR",
"centAmount": 4000
},
"shippingDetailsToRemove": {
"targets": [
{
"addressKey": "AddressKeyStringFromAddress",
"quantity": 2
}
]
}
}Change LineItems Order
action​String​ | "changeLineItemsOrder" |
lineItemOrder​Array of String​ | All existing LineItem ids in the desired new order. |
{
"action": "changeLineItemsOrder",
"lineItemOrder": [
"{{lineItemId2}}",
"{{lineItemId}}"
]
}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.
action​String​ | "addCustomLineItem" |
key​String​ | User-defined unique identifier of the Custom Line Item. MinLength:Â2​MaxLength: 256​Pattern: ^[a-zA-Z0-9_-]​ |
money​Money​ | Money value of the Custom Line Item. The value can be negative. |
name​ | Name of the Custom Line Item. |
quantity​Int​ | Number of Custom Line Items to add to the Cart. Default:Â1​ |
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​ | |
externalTaxRate​ | An external Tax Rate can be set if the Cart has External TaxMode. |
shippingDetails​ | Container for Custom Line Item-specific addresses. |
priceMode​ |
Standard​ |
custom​ | Custom Fields for the Custom Line Item. |
{
"action": "addCustomLineItem",
"name": {
"en": "Name EN",
"de": "Name DE"
},
"quantity": 1,
"money": {
"currencyCode": "EUR",
"centAmount": 4200
},
"slug": "mySlug",
"taxCategory": {
"typeId": "tax-category",
"id": "{{tax-category-id}}"
}
}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.action​String​ | "removeCustomLineItem" |
customLineItemId​String​ | |
customLineItemKey​String​ |
{
"action": "removeCustomLineItem",
"customLineItemId": "{{customLineItemId}}"
}Add Shopping List
Adds all LineItems of a ShoppingList to the Cart.
action​String​ | "addShoppingList" |
shoppingList​ | Shopping List that contains the Line Items to be added. |
distributionChannel​ | distributionChannel to set for all LineItems that are added to the Cart.
The Channel must have the ProductDistribution ChannelRoleEnum. |
supplyChannel​ | supplyChannel to set for all LineItems that are added to the Cart.
The Channel must have the InventorySupply ChannelRoleEnum. |
{
"action": "addShoppingList",
"shoppingList": {
"id": "{{shopping-list-id}}",
"typeId": "shopping-list"
},
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
},
"distributionChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}Set Cart Total Tax
Can be used if the Cart has the
ExternalAmount TaxMode. This update action adds the taxedPrice field to the Cart. It sets the totalGross amount, and Composable Commerce calculates the totalNet and totalTax values based on the provided externalTotalGross.
You must use this update action after any price-affecting change occurs within the Cart.action​String​ | "setCartTotalTax" |
externalTotalGross​Money​ | The total gross amount of the Cart, including tax. This value is used to calculate the totalNet and totalTax fields of the Cart's taxedPrice. |
externalTaxPortions​Array of TaxPortionDraft​ | Set if the externalTotalGross price is a sum of portions with different tax rates. |
{
"action": "setCartTotalTax",
"externalTotalGross": {
"currencyCode": "EUR",
"centAmount": 10000
}
}Change TaxMode
- When
ExternalTaxMode is changed toPlatformorDisabled, 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'sshippingAddress.
action​String​ | "changeTaxMode" |
taxMode​TaxMode​ | The new TaxMode. |
{
"action": "changeTaxMode",
"taxMode": "Platform"
}Change Tax RoundingMode
Changing the tax rounding mode leads to recalculation of taxes.
action​String​ | "changeTaxRoundingMode" |
taxRoundingMode​RoundingMode​ | New value to set. |
{
"action": "changeTaxRoundingMode",
"taxRoundingMode": "HalfUp"
}Change TaxCalculationMode
Changing the tax calculation mode leads to recalculation of taxes.
action​String​ | "changeTaxCalculationMode" |
taxCalculationMode​ | New value to set. |
{
"action": "changeTaxCalculationMode",
"taxCalculationMode": "LineItemLevel"
}Add DiscountCode
Adds a DiscountCode to the Cart to activate the related Cart Discounts.
Adding a Discount Code is only possible if no DirectDiscount has been applied to the Cart.
Discount Codes can be added to frozen Carts, but their DiscountCodeState is then
DoesNotMatchCart.The maximum number of Discount Codes in a Cart is restricted by a limit.
Specific Error Code: MatchingPriceNotFound
action​String​ | "addDiscountCode" |
code​String​ | code of a DiscountCode. |
{
"action": "addDiscountCode",
"code": "mydiscountcode"
}Remove DiscountCode
action​String​ | "removeDiscountCode" |
discountCode​ | Discount Code to remove from the Cart. |
{
"action": "removeDiscountCode",
"discountCode": {
"typeId": "discount-code",
"id": "{{discount-code-id}}"
}
}Set DirectDiscounts
Adds a DirectDiscount, but only if no DiscountCode has been added to the Cart.
Either a Discount Code or a Direct Discount can exist on a Cart at the same time.
action​String​ | "setDirectDiscounts" |
discounts​Array of DirectDiscountDraft​ |
|
{
"action": "setDirectDiscounts",
"discounts": [
{
"value": {
"type": "relative",
"permyriad": 1000
},
"target": {
"type": "lineItems",
"predicate": "1=1"
}
}
]
}Add Payment
action​String​ | "addPayment" |
payment​ | Payment to add to the Cart. Must not be assigned to another Order or active Cart already. |
{
"action": "addPayment",
"payment": {
"id": "{{payment-id}}",
"typeId": "payment"
}
}Remove Payment
action​String​ | "removePayment" |
payment​ | Payment to remove from the Cart. |
{
"action": "removePayment",
"payment": {
"id": "{{payment-id}}",
"typeId": "payment"
}
}Set Billing Address
action​String​ | "setBillingAddress" |
address​BaseAddress​ | Value to set. If empty, any existing value is removed. |
{
"action": "setBillingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}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.action​String​ | "setShippingAddress" |
address​BaseAddress​ | Value to set.
If not set, the shipping address is unset, and the taxedPrice and taxRate are unset in all Line Items of the Cart. |
{
"action": "setShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}Add ItemShippingAddress
Adds an address to a Cart when shipping to multiple addresses is desired.
action​String​ | "addItemShippingAddress" |
address​BaseAddress​ | Address to append to
itemShippingAddresses.The new Address must have a key that is unique across this Cart. |
{
"action": "addItemShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}Remove ItemShippingAddress
An address can only be removed if it is not referenced in any ItemShippingTarget of the Cart.
action​String​ | "removeItemShippingAddress" |
addressKey​String​ | key of the Address to remove from itemShippingAddresses. |
{
"action": "removeItemShippingAddress",
"addressKey": "{{addressKey}}"
}Update ItemShippingAddress
Updates an address in
itemShippingAddresses by keeping the Address key.action​String​ | "updateItemShippingAddress" |
address​BaseAddress​ | The new Address with the same key as the Address it will replace. |
{
"action": "updateItemShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}Add ShippingMethod
Adds a Shipping Method for a specified shipping address to a Cart with
Multiple ShippingMode.action​String​ | "addShippingMethod" |
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.
If the referenced Shipping Method has a predicate that does not match the Cart, an InvalidOperation error is returned. |
shippingAddress​BaseAddress​ | 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:
|
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 referenced Shipping Method. |
custom​ | Custom Fields for the Shipping Method. |
{
"action": "addShippingMethod",
"shippingKey": "shippingMethodKey1",
"shippingMethod": {
"id": "{{shipping-method-id}}",
"typeId": "shipping-method"
},
"shippingAddress": {
"key": "exampleKey",
"streetName": "Example Street",
"streetNumber": "4711",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE"
},
"shippingRateInput": {
"type": "Classification",
"key": "shippingRateString"
},
"externalTaxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}Remove ShippingMethod
Removes a Shipping Method from a Cart that has the
Multiple ShippingMode.action​String​ | "removeShippingMethod" |
shippingKey​String​ | User-defined unique identifier of the Shipping Method to remove from the Cart. |
{
"action": "removeShippingMethod",
"shippingKey": "shippingMethodKey1"
}Set ShippingMethod
action​String​ | "setShippingMethod" |
shippingMethod​ | Value to set. If empty, any existing value is removed. If the referenced Shipping Method has a predicate that does not match the Cart, an InvalidOperation error is returned. |
externalTaxRate​ | An external Tax Rate can be set if the Cart has the External TaxMode. |
{
"action": "setShippingMethod",
"shippingMethod": {
"id": "{{shipping-method-id}}",
"typeId": "shipping-method"
}
}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.action​String​ | "addCustomShippingMethod" |
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​BaseAddress​ | 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. |
{
"action": "addCustomShippingMethod",
"shippingKey": "shippingMethodKey1",
"shippingMethodName": "oneOfCustomShippingMethods",
"shippingAddress": {
"key": "exampleKey",
"streetName": "Example Street",
"streetNumber": "4711",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE"
},
"shippingRate": {
"price": {
"currencyCode": "EUR",
"centAmount": 4200
}
},
"taxCategory": {
"id": "{{tax-category-id}}",
"typeId": "tax-category"
},
"deliveries": []
}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.action​String​ | "setCustomShippingMethod" |
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​ | |
custom​ | Custom Fields for the custom Shipping Method. |
{
"action": "setCustomShippingMethod",
"shippingMethodName": "myCustomShippingMethod",
"shippingRate": {
"price": {
"currencyCode": "EUR",
"centAmount": 4200
}
},
"taxCategory": {
"id": "{{tax-category-id}}",
"typeId": "tax-category"
}
}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.
action​String​ | "setShippingRateInput" |
shippingRateInput​ | The data type of this field depends on the
shippingRateInputType.type configured in the Project:
|
{
"action": "setShippingRateInput",
"shippingRateInput": {
"type": "Classification",
"key": "shippingRateString"
}
}Set Locale
Set Country
Setting the country can lead to changes in the LineItem prices.
action​String​ | "setCountry" |
country​CountryCode​ | Value to set. If empty, 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. |
{
"action": "setCountry",
"country": "DE"
}Set DeleteDaysAfterLastModification
Number of days after which a Cart with
Active CartState is deleted since its last modification.If a ChangeSubscription exists for Carts, a ResourceDeletedDeliveryPayload is sent.
action​String​ | "setDeleteDaysAfterLastModification" |
deleteDaysAfterLastModification​Int​ | Value to set.
If not provided, the default value for this field configured in Project settings is assigned. |
{
"action": "setDeleteDaysAfterLastModification",
"deleteDaysAfterLastModification": 90
}Set Custom Type
action​String​ | "setCustomType" |
type​ | Defines the Type that extends the Cart with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the Cart. |
fields​ | Sets the Custom Fields fields for the Cart. |
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}Set CustomField
action​String​ | "setCustomField" |
name​String​ | Name of the Custom Field. |
value​ | 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. |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}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.action​String​ | "recalculate" |
updateProductData​Boolean​ |
|
{
"action": "recalculate",
"updateProductData": true
}Freeze Cart
Changes the CartState from
Active to Frozen. Results in a Frozen Cart.
Fails with InvalidOperation error when the Cart is empty.action- String -"freezeCart"
Unfreeze Cart
This action updates all prices in the Cart according to latest Prices on related Product Variants and Shipping Methods and by applying all discounts currently being active and applicable for the Cart.
action- String -"unfreezeCart"
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.
action​String​ | "changeLineItemQuantity" |
lineItemId​String​ | |
lineItemKey​String​ | |
quantity​Int​ | New value to set. If Minimum: 0, the Line Item is removed from the Cart.0​ |
externalPrice​Money​ | Required when the Line Item uses
ExternalPrice LineItemPriceMode.
Sets the LineItem price to the given value when changing the quantity of a Line Item.The LineItem price is updated as described in Line Item price selection. |
externalTotalPrice​ | Sets the LineItem price and totalPrice to the given value when changing the quantity of a Line Item with the ExternalTotal LineItemPriceMode.
If externalTotalPrice is not given and the priceMode is ExternalTotal, the external price is unset and the priceMode is set to Platform. |
{
"action": "changeLineItemQuantity",
"lineItemId": "{{lineItemId}}",
"quantity": 1
}Set LineItem TaxRate
Can be used if the Cart has the
External TaxMode.action​String​ | "setLineItemTaxRate" |
lineItemId​String​ | |
lineItemKey​String​ | |
externalTaxRate​ | Value to set. If empty, any existing value is removed. |
shippingKey​String​ | key of the ShippingMethod used for this Line Item.
This is required for Carts with Multiple ShippingMode. |
{
"action": "setLineItemTaxRate",
"lineItemId": "{{lineItemId}}",
"externalTaxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}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.action​String​ | "setLineItemTaxAmount" |
lineItemId​String​ | |
lineItemKey​String​ | |
externalTaxAmount​ | Value to set. If empty, any existing value is removed. |
shippingKey​String​ | key of the ShippingMethod used for this Line Item.
This is required for Carts with Multiple ShippingMode. |
{
"action": "setLineItemTaxAmount",
"lineItemId": "{{lineItemId}}",
"externalTaxAmount": {
"totalGross": {
"currencyCode": "EUR",
"centAmount": 100
},
"taxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}
}Set LineItem Price
action​String​ | "setLineItemPrice" |
lineItemId​String​ | |
lineItemKey​String​ | |
externalPrice​Money​ | 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. |
{
"action": "setLineItemPrice",
"lineItemId": "{{lineItemId}}",
"externalPrice": {
"currencyCode": "EUR",
"centAmount": 4000
}
}Set LineItem TotalPrice
Sets the LineItem
totalPrice and price, and changes the priceMode to ExternalTotal LineItemPriceMode.action​String​ | "setLineItemTotalPrice" |
lineItemId​String​ | |
lineItemKey​String​ | |
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. |
{
"action": "setLineItemTotalPrice",
"lineItemId": "{{lineItemId}}",
"externalTotalPrice": {
"price": {
"currencyCode": "EUR",
"centAmount": 4200
},
"totalPrice": {
"currencyCode": "EUR",
"centAmount": 4200
}
}
}Set LineItem DistributionChannel
Setting a distribution channel for a LineItem can lead to an updated
price as described in Line Item price selection.action​String​ | "setLineItemDistributionChannel" |
lineItemId​String​ | |
lineItemKey​String​ | |
distributionChannel​ |
|
{
"action": "setLineItemDistributionChannel",
"lineItemId": "{{lineItemId}}",
"distributionChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}Set LineItem SupplyChannel
Performing this action has no impact on inventory that should be reserved.
action​String​ | "setLineItemSupplyChannel" |
lineItemId​String​ | |
lineItemKey​String​ | |
supplyChannel​ |
|
{
"action": "setLineItemSupplyChannel",
"lineItemId": "{{lineItemId}}",
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}Set LineItem ShippingDetails
action​String​ | "setLineItemShippingDetails" |
lineItemId​String​ | |
lineItemKey​String​ | |
shippingDetails​ | Value to set. If empty, the existing value is removed. |
{
"action": "setLineItemShippingDetails",
"lineItemId": "{{lineItemId}}",
"shippingDetails": {
"targets": [
{
"addressKey": "{{addressKey}}",
"quantity": 1
}
]
}
}Apply DeltaToLineItemShippingDetailsTargets
To override the shipping details, see Set LineItem ShippingDetails.
action​String​ | "applyDeltaToLineItemShippingDetailsTargets" |
lineItemId​String​ | |
lineItemKey​String​ | |
targetsDelta​Array of ItemShippingTarget​ | Using positive or negative quantities increases or decreases the number of items shipped to an address. |
{
"action": "applyDeltaToLineItemShippingDetailsTargets",
"lineItemId": "{{lineItemId}}",
"targetsDelta": [
{
"addressKey": "addressKeyString",
"quantity": 1
}
]
}Set LineItem Custom Type
action​String​ | "setLineItemCustomType" |
lineItemId​String​ | |
lineItemKey​String​ | |
type​ | Defines the Type that extends the Line Item with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the Line Item. |
fields​ | Sets the Custom Fields fields for the Line Item. |
{
"action": "setLineItemCustomType",
"lineItemId": "{{lineItemId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}Set LineItem CustomField
action​String​ | "setLineItemCustomField" |
lineItemId​String​ | |
lineItemKey​String​ | |
name​String​ | Name of the Custom Field. |
value​ | 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. |
{
"action": "setLineItemCustomField",
"lineItemId": "{{lineItemId}}",
"name": "exampleStringField",
"value": "TextString"
}Set LineItem InventoryMode
action​String​ | "setLineItemInventoryMode" |
lineItemId​String​ | |
lineItemKey​String​ | |
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. |
{
"action": "setLineItemInventoryMode",
"lineItemId": "{{lineItemId}}",
"inventoryMode": "TrackOnly"
}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.
action​String​ | "changeCustomLineItemQuantity" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
quantity​Int​ | New value to set. If Minimum: 0, the Custom Line Item is removed from the Cart.0​ |
{
"action": "changeCustomLineItemQuantity",
"customLineItemId": "{{customlineItemId}}",
"quantity": 1
}Set CustomLineItem TaxRate
Can be used if the Cart has the
External TaxMode.action​String​ | "setCustomLineItemTaxRate" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
externalTaxRate​ | Value to set. If empty, 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. |
{
"action": "setCustomLineItemTaxRate",
"customLineItemId": "{{customLineItemId}}",
"externalTaxRate": {
"name": "TaxRateName",
"country": "DE",
"amount": 0.19
}
}Set CustomLineItem TaxAmount
Can be used if the Cart has the
ExternalAmount TaxMode.action​String​ | "setCustomLineItemTaxAmount" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
externalTaxAmount​ | Value to set. If empty, 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. |
{
"action": "setCustomLineItemTaxAmount",
"customLineItemId": "{{customLineItemId}}",
"externalTaxAmount": {
"totalGross": {
"centAmount": 2000000,
"currencyCode": "EUR"
},
"taxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}
}Change CustomLineItem Price Mode
action​String​ | "changeCustomLineItemPriceMode" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
mode​ | New value to set. Must not be empty. |
{
"action": "changeCustomLineItemPriceMode",
"customLineItemId": "{{customLineItemId}}",
"mode": "External"
}Change CustomLineItem Money
action​String​ | "changeCustomLineItemMoney" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
money​Money​ | Value to set. Must not be empty. Can be a negative amount. |
{
"action": "changeCustomLineItemMoney",
"customLineItemId": "{{customLineItemId}}",
"money": {
"currencyCode": "EUR",
"centAmount": 4200
}
}Set CustomLineItem ShippingDetails
action​String​ | "setCustomLineItemShippingDetails" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
shippingDetails​ | Value to set. If empty, any existing value is removed. |
{
"action": "setCustomLineItemShippingDetails",
"customLineItemId": "{{customlineItemId}}",
"shippingDetails": {
"targets": [
{
"addressKey": "{{addressKey}}",
"quantity": 1
}
]
}
}Apply DeltaToCustomLineItemShippingDetailsTargets
action​String​ | "applyDeltaToCustomLineItemShippingDetailsTargets" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
targetsDelta​Array of ItemShippingTarget​ | Using positive or negative quantities increases or decreases the number of items shipped to an address. |
{
"action": "applyDeltaToCustomLineItemShippingDetailsTargets",
"customLineItemId": "{{customlineItemId}}",
"targetsDelta": [
{
"addressKey": "addressKeyString",
"quantity": 1
}
]
}Set CustomLineItem Custom Type
action​String​ | "setCustomLineItemCustomType" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
type​ | Defines the Type that extends the CustomLineItem with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the CustomLineItem. |
fields​ | Sets the Custom Fields fields for the CustomLineItem. |
{
"action": "setCustomLineItemCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
},
"customLineItemId": "{{customLineItemId}}"
}Set CustomLineItem CustomField
action​String​ | "setCustomLineItemCustomField" |
customLineItemId​String​ | |
customLineItemKey​String​ | |
name​String​ | Name of the Custom Field. |
value​ | 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. |
{
"action": "setCustomLineItemCustomField",
"customLineItemId": "{{customLineItemId}}",
"name": "exampleStringField",
"value": "TextString"
}on Billing Address
Set Billing Address Custom Type
action​String​ | "setBillingAddressCustomType" |
type​ | Defines the Type that extends the billingAddress with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the billingAddress. |
fields​ | Sets the Custom Fields fields for the billingAddress. |
{
"action": "setBillingAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}Set Billing Address CustomField
action​String​ | "setBillingAddressCustomField" |
name​String​ | Name of the Custom Field. |
value​ | 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. |
{
"action": "setBillingAddressCustomField",
"name": "exampleStringField",
"value": "TextString"
}on Shipping Address
Set Shipping Address Custom Type
action​String​ | "setShippingAddressCustomType" |
type​ | Defines the Type that extends the shippingAddress with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the shippingAddress. |
fields​ | Sets the Custom Fields fields for the shippingAddress. |
{
"action": "setShippingAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}Set Shipping Address CustomField
action​String​ | "setShippingAddressCustomField" |
name​String​ | Name of the Custom Field. |
value​ | 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. |
{
"action": "setShippingAddressCustomField",
"name": "exampleStringField",
"value": "TextString"
}on ItemShipping Address
Set ItemShipping Address Custom Type
action​String​ | "setItemShippingAddressCustomType" |
addressKey​String​ | |
type​ | Defines the Type that extends the itemShippingAddress with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the itemShippingAddress. |
fields​ | Sets the Custom Fields fields for the itemShippingAddress. |
{
"action": "setItemShippingAddressCustomType",
"addressKey": "{{address-key}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}Set ItemShipping Address CustomField
action​String​ | "setItemShippingAddressCustomField" |
addressKey​String​ | |
name​String​ | Name of the Custom Field. |
value​ | 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. |
{
"action": "setItemShippingAddressCustomField",
"addressKey": "{{address-key}}",
"name": "exampleStringField",
"value": "TextString"
}on Shipping Method
Set ShippingMethod TaxAmount
A Shipping Method tax amount can be set if the Cart has the
ExternalAmount TaxMode.action​String​ | "setShippingMethodTaxAmount" |
shippingKey​String​ | |
externalTaxAmount​ | Value to set. If empty, any existing value is removed. |
{
"action": "setShippingMethodTaxAmount",
"shippingKey": "shipping-method-key",
"externalTaxAmount": {
"totalGross": {
"centAmount": 2000000,
"currencyCode": "EUR"
},
"taxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}
}Set ShippingMethod TaxRate
A Shipping Method Tax Rate can be set if the Cart has the
External TaxMode.action​String​ | "setShippingMethodTaxRate" |
shippingKey​String​ | |
externalTaxRate​ | Value to set. If empty, any existing value is removed. |
{
"action": "setShippingMethodTaxRate",
"shippingKey": "shipping-method-key",
"externalTaxRate": {
"name": "myTaxRate",
"amount": 0.19,
"country": "DE"
}
}on Shipping
Set Shipping Custom Type
This action sets, overwrites, or removes any existing Custom Type and Custom Fields for the Cart's
shippingMethod or shipping.action​String​ | "setShippingCustomType" |
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. |
type​ | Defines the Type that extends the specified ShippingMethod with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the ShippingMethod. |
fields​ | Sets the Custom Fields fields for the shippingMethod. |
{
"action": "setShippingCustomType",
"shippingKey": "shippingMethodKey1",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}Set Shipping CustomField
action​String​ | "setShippingCustomField" |
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​ | 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. |
{
"action": "setShippingCustomField",
"shippingKey": "shippingMethodKey1",
"name": "exampleStringField",
"value": "TextString"
}Delete Cart
The following methods delete a Cart accessible globally in the Project. For deleting Carts available in a Store only, use the Delete Cart in Store methods instead.
Delete Cart by ID
DELETE
https://api.{region}.commercetools.com/{projectKey}/carts/{id}
Deletes a Cart in the Project.
OAuth 2.0 Scopes:
manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Cart. |
Query parameters:
versionInt ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasureBoolean ​ | To erase all related personal data in compliance with GDPR, set to true.Default: false​ |
Response:
200as
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/carts/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Delete Cart by Key
DELETE
https://api.{region}.commercetools.com/{projectKey}/carts/key={key}
Deletes a Cart in the Project.
OAuth 2.0 Scopes:
manage_orders:{projectKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Cart. |
Query parameters:
versionInt ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasureBoolean ​ | To erase all related personal data in compliance with GDPR, set to true.Default: false​ |
Response:
200as
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/carts/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Delete Cart in Store
The following methods delete a Cart from a specific Store. For deleting Carts accessible globally in the Project, use the Delete Cart methods instead.
Delete Cart in Store by ID
DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}
Deletes a Cart in a Store.
If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
idString ​ | id of the Cart. |
Query parameters:
versionInt ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasureBoolean ​ | To erase all related personal data in compliance with GDPR, set to true.Default: false​ |
Response:
200as
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}Delete Cart in Store by Key
DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}
Deletes a Cart in a Store.
If the Cart exists in the Project but does not have a
store specified, or the store field references a different Store, this method returns a ResourceNotFound error.OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_orders:{projectKey}:{storeKey}Path parameters:
regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
storeKeyString ​ | key of the Store. |
keyString ​ | key of the Cart. |
Query parameters:
versionInt ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasureBoolean ​ | To erase all related personal data in compliance with GDPR, set to true.Default: false​ |
Response:
200as
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"type": "Cart",
"id": "27b39077-aa57-48a5-b504-914f68fa44dc",
"version": 1,
"createdAt": "2023-01-23T13:06:28.569Z",
"lastModifiedAt": "2023-01-23T13:06:28.569Z",
"lastModifiedBy": {
"isPlatformClient": false
},
"createdBy": {
"isPlatformClient": false
},
"lineItems": [],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": []
}