Carts
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
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 |
|
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 LineItem Price selection. |
anonymousId String | Anonymous session associated with the Cart. |
businessUnit BETA | Reference to a Business Unit the Cart belongs to. |
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 Taxes are included if TaxRate |
taxedPrice |
|
taxedShippingPrice | Sum of the |
taxMode | Indicates how Tax Rates are set. Default:Platform |
taxRoundingMode | Indicates how monetary values are rounded when calculating taxes for HalfEven |
taxCalculationMode | Indicates how taxes are calculated when calculating taxes for LineItemLevel |
inventoryMode | Indicates how stock quantities are tracked for Line Items in the Cart. Default:None |
cartState | Current status of the Cart. Default:Active |
billingAddress | Billing address associated with the Cart. |
shippingAddress | Shipping address associated with the Cart. Determines eligible ShippingMethod rates and Tax Rates of Line Items. |
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 |
shippingInfo | Shipping-related information of a Cart with |
shippingRateInput | Input used to select a ShippingRatePriceTier.
The data type of this field depends on the
|
shippingCustomFields | Custom Fields of the Shipping Method in a Cart with |
shipping Array of Shipping | Shipping-related information of a Cart with |
itemShippingAddresses Array of Address | Additional shipping addresses of the Cart as specified by LineItems using the Eligible Shipping Methods or applicable Tax Rates are determined by the address in |
discountCodes Array of DiscountCodeInfo | Discount Codes applied to the Cart. A Cart that has |
directDiscounts Array of DirectDiscount | Direct Discounts added to the Cart. A Cart that has |
refusedGifts Array of CartDiscountReference | Automatically set when a Line Item with |
paymentInfo | Payment information related to the Cart. |
country | Used for LineItem Price selection. |
locale | Languages of the Cart. Can only contain languages supported by the Project. |
origin | Indicates how the Cart was created. Default:Customer |
deleteDaysAfterLastModification Int | Number of days after which an active Cart is deleted since its last modification. Configured in Project settings. Default:90 |
custom | Custom Fields of the Cart. |
createdAt | Date and time (UTC) the Cart was initially created. |
createdBy BETA | Present on resources created after 1 February 2019 except for events not tracked. |
lastModifiedAt | Date and time (UTC) the Cart was last updated. |
lastModifiedBy BETA | Present on resources updated after 1 February 2019 except for events not tracked. |
CartDraft
key String | User-defined unique identifier for the Cart. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
currency | Currency the Cart uses. |
customerId String |
|
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 LineItem Price selection. It is automatically set if the Customer referenced in |
anonymousId String | Anonymous session associated with the Cart. |
businessUnit BETA | ResourceIdentifier to the Business Unit the Cart should belong to. When the |
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 | Determines how Tax Rates are set. Default:Platform |
externalTaxRateForShippingMethod | External Tax Rate for the |
taxRoundingMode | Determines how monetary values are rounded when calculating taxes for HalfEven |
taxCalculationMode | Determines how taxes are calculated when calculating taxes for LineItemLevel |
inventoryMode | Determines how stock quantities are tracked for Line Items in the Cart. Default:None |
billingAddress | Billing address associated with the Cart. |
shippingAddress | Shipping address associated with the Cart. Determines eligible ShippingMethod rates and Tax Rates of Line Items. |
shippingMethod | Shipping Method for a Cart with |
shippingRateInput | Used as an input to select a ShippingRatePriceTier.
The data type of this field depends on the
|
shippingMode |
Single |
customShipping Array of CustomShippingDraft | Custom Shipping Methods for a Cart with |
shipping Array of ShippingDraft | Shipping Methods for a Cart with |
itemShippingAddresses Array of BaseAddress | Multiple shipping addresses of the Cart. Each address must contain a Eligible Shipping Methods or applicable Tax Rates are determined by the address |
discountCodes Array of String |
|
country | Used for LineItem Price selection.
If used for Create Cart in Store, the provided country must be one of the Store's |
locale | Languages of the Cart. Can only contain languages supported by the Project. |
origin | 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. |
offset Int | Number of elements skipped. |
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 |
results Array of Cart | Carts matching the query. |
CartReference
CartResourceIdentifier
ResourceIdentifier to a Cart.
ReplicaCartDraft
Used for replicating an existing Cart or Order.
LineItemMode
Indicates how a Line Item is added to a Cart.
Standard
The Line Item is added during Cart creation or using the Add LineItem update action. The Line Item quantity can be changed without restriction.
GiftLineItem
The Line Item is added automatically by a Cart Discount with CartDiscountValueGiftLineItem.
The quantity cannot be increased, and it won't be merged when the same Line Item is added to the Cart. If the gift is removed, an entry is added to the
refusedGifts
array 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
externalPrice
field 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. Although a Line Item with this price mode has both
price
andtotalPrice
set externally, onlytotalPrice
is 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 theexternalTotal
field. If theexternalTotal
field 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.
RoundingMode
Determines how monetary values are rounded.
HalfEven
-
Default mode for a new Cart.
HalfUp
HalfDown
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.totalNet
,totalGross
, andtaxPortions
fields are calculated based on thetaxRoundingMode
.External
Tax Rates are set externally per ExternalTaxRateDraft. A Cart can be ordered only if all Line Items, Custom Line Items, and the Shipping Method have an external Tax Rate set.
totalNet
,totalGross
, andtaxPortions
fields are calculated based on thetaxRoundingMode
.ExternalAmount
Tax amounts, Tax Rates, and tax portions are set externally per 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.
Price-specific update actions on Carts require external recalculation of the total gross price. Hence, the
externalTaxAmount
is removed in these cases and must be reset with Set LineItem TaxAmount, Set CustomLineItem TaxAmount, or Set ShippingMethod TaxAmount update actions.Disabled
No taxes are added to the Cart.
Note that this tax mode cannot be set on the My Carts API.
InventoryMode
Indicates how Line Items in a Cart are tracked.
None
Adding 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
availableQuantity
is insufficient (but is still updated) for the ordered Line Item quantity.However, an Order can be created if the InventoryEntry
restockableInDays
is set (including0
).
ShippingMode
Single
Cart can contain only a single Shipping Method. This is the default mode for backwards compatibilty.
Multiple
Cart 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.
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.
Customer
Cart was created by a Customer.
This is the default value.
Merchant
Cart was created by a merchant on behalf of a Customer.
Quote
Cart was created as part of a Quote (BETA).
LineItem
The representation of a Line Item in a Cart.
id String | Unique identifier of the LineItem. |
key String | User-defined unique identifier of the LineItem. |
productId String |
|
productKey String |
This field is only present on:
Present on resources created or updated after 3 December 2021. |
name | Name of the Product. |
productSlug |
|
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 of a Line Item selected from the Product Variant according to the Product |
quantity Int | Number of Line Items of the given Product Variant present in the Cart. Default:1 |
totalPrice | Total price of this Line Item equalling |
discountedPricePerQuantity Array of DiscountedLineItemPriceForQuantity | Discounted price of a single quantity of the Line Item. |
taxedPrice | Automatically set after |
taxedPricePortions Array of MethodTaxedPrice | Taxed price of the Shipping Method that is automatically set after |
state Array of ItemState | State of the Line Item in the Cart. |
taxRate |
|
perMethodTaxRate Array of MethodTaxRate | Tax Rate per Shipping Method for a Cart with |
supplyChannel | Identifies Inventory entries that are reserved. The referenced Channel has the |
distributionChannel | Used to select a Product Price. The referenced Channel has the |
priceMode | Indicates how the Price for the Line Item is set. |
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 |
shippingDetails | Container for Line Item-specific addresses. |
addedAt | Date and time (UTC) the Line Item was added to the Cart. |
custom | Custom Fields of the Line Item. |
lastModifiedAt | 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 |
|
variantId Int |
|
sku String |
|
quantity Int | Quantity of the Product Variant to add to the Cart. Default:1 |
addedAt | 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 If the Cart is bound to a Store with |
supplyChannel | Used to identify Inventory entries that must be reserved.
The referenced Channel must have the |
externalPrice | Sets the LineItem |
externalTotalPrice | Sets the LineItem |
externalTaxRate | External Tax Rate for the Line Item if the Cart has the |
inventoryMode | Inventory mode specific to the Line Item only, and valid for the entire |
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. |
name | Name of the Custom Line Item. |
money | Money value of the Custom Line Item. |
taxedPrice | Automatically set after the |
totalPrice | Total price of the Custom Line Item ( Includes taxes if the TaxRate |
slug String | User-defined identifier used in a deep-link URL for the Custom Line Item.
It matches the pattern |
quantity Int | Number of Custom Line Items in the Cart. Default:1 |
state Array of ItemState | State of the Custom Line Item in the Cart. |
taxCategory | Used to select a Tax Rate when a Cart has the |
taxRate |
|
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 are applied to the Custom Line Item. |
custom | Custom Fields of the Custom Line Item. |
CustomLineItemDraft
name | Name of the Custom Line Item. |
quantity Int | Number of Custom Line Items to add to the Cart. Default:1 |
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 |
taxCategory | |
externalTaxRate | External Tax Rate for the Custom Line Item if the Cart has the |
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 |
TaxedPriceDraft
totalNet | Total net price of the Line Item or Custom Line Item. |
totalGross | Total gross price of the Line Item or Custom Line Item. |
taxPortions Array of TaxPortionDraft | Taxable portions added to the Calculated from the TaxRates. |
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. |
totalTax | Total tax applicable for the Line Item or Custom Line Item.
Automatically calculated as the difference between the |
TaxPortion
name String | Name of the tax portion. |
rate Float | A number in the range 0-1. Maximum:1 |
amount | Money value of the tax portion. |
TaxPortionDraft
Represents the portions that sum up to the totalGross
field of a TaxedPrice.
The portions are calculated from the TaxRates.
If a Tax Rate has SubRates, they are used and can be identified by name.
Tax portions from Line Items with the same rate
and name
will be accumulated to the same tax portion.
name String | Name of the tax portion. |
rate Float | A number in the range 0-1. Maximum:1 |
amount | 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.
1 |
includedInPrice Boolean |
false |
country | Country for which the tax applies. |
state String | State within the specified country. |
subRates BETAArray of SubRate | For countries (such as the US) where the total tax is a combination of multiple taxes (such as state and local taxes). |
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 | Total gross amount ( |
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
MethodTaxRate
shippingMethodKey String | User-defined unique identifier of the Shipping Method in a Cart with |
taxRate | Tax Rate for the Shipping Method. |
MethodTaxedPrice
shippingMethodKey String | User-defined unique identifier of the Shipping Method in a Cart with |
taxedPrice | Taxed price for the Shipping Method. |
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 | 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 | A CartDiscountReference or DirectDiscountReference for the applicable discount on the Line Item. |
discountedAmount | Money value of the discount applicable. |
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 | Part of the Cart that is discounted. Empty when the |
DirectDiscountDraft
Represents a CartDiscount that can only be associated with a single Cart or Order.
Direct Discounts are always active and valid, and have the default Stacking
StackingMode.
They apply in the order in which they are listed in the directDiscounts
array of Carts or Orders, and do not have a sorting order like Cart Discounts.
If a Direct Discount is present, any matching Cart Discounts in the Project are ignored. Additionally, a Cart or Order supports either Discount Codes or Direct Discounts at the same time.
value | Defines the effect the Discount will have. |
target | Defines what part of the Cart will be discounted. If |
{"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 String | "direct-discount" References a DirectDiscount. |
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.
NotActive
The 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
validFrom
andvalidUntil
dates.DoesNotMatchCart
The Discount Code is active and contains at least one active and valid Cart Discount. The DiscountCode
cartPredicate
does 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
cartPredicate
matches the Cart and at least one of the contained active discount's cart predicates matches the Cart.MaxApplicationReached
The
maxApplications
ormaxApplicationsPerCustomer
for a DiscountCode has been reached.ApplicationStoppedByPreviousDiscount
The Discount Code is active and no discounts are applied after a discount with
StopAfterThisDiscount
StackingMode 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 |
shippingRate | Used to determine the price. |
taxedPrice | Automatically set after the |
taxRate | Automatically set in the For the |
taxCategory | Used to select a Tax Rate when a Cart has the |
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 |
shippingMethodName String | Name of the custom Shipping Method. |
shippingAddress | Determines the shipping rate and Tax Rate of the associated Line Items. |
shippingRate | Determines the shipping price. |
shippingRateInput | Input used to select a ShippingRatePriceTier.
The data type of this field depends on the
|
taxCategory | Tax Category used to determine a shipping Tax Rate if the Cart has the |
externalTaxRate | Tax Rate used to tax a shipping expense if the Cart has the |
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 |
shippingInfo | Automatically set when the Shipping Method is added. |
shippingAddress | Determines the shipping rates and Tax Rates of associated Line Items. |
shippingRateInput | Used as an input to select a ShippingRatePriceTier.
The data type of this field depends on the
|
shippingCustomFields | Custom Fields of Shipping with |
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 |
shippingMethod | Shipping Methods added to the Cart with |
shippingAddress | Determines the shipping rate and Tax Rate of the associated Line Items. |
shippingRateInput | Input used to select a ShippingRatePriceTier.
The data type of this field depends on the
|
externalTaxRate | Tax Rate used for taxing a shipping expense if the Cart has the |
deliveries Array of DeliveryDraft | Deliveries to be shipped with the Shipping Method. |
custom | Custom Fields for Shipping. |
ShippingMethodState
Determines whether a ShippingMethod is allowed for a Cart.
DoesNotMatchCart
The ShippingMethod
predicate
does not match the Cart.Ordering this Cart returns an ShippingMethodDoesNotMatchCart error.
MatchesCart
Either the ShippingMethod
predicate
matches the Cart or there is nopredicate
defined.
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 |
quantity Int | Quantity of Line Items or Custom Line Items shipped to the address with the specified If a quantity is updated to |
shippingMethodKey String | User-defined unique identifier of the Shipping Method in a Cart with It connects Line Item quantities with individual shipping addresses. |
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
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
view_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
curl --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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
view_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
curl --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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
Retrieves the recently modified active Cart of a Customer with CartOrigin Customer
. If no active Cart exists, a ResourceNotFound error is returned.
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
view_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
customerId String |
|
expand | The parameter can be passed multiple times. |
curl --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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
The following methods retrieve a Cart from a specific Store. For retrieving Carts accessible globally in the Project, use the Get Cart methods instead.
Get Cart in Store by ID
If the Cart exists in the Project but does not have the store
field, or the store
field references a different Store, a ResourceNotFound error is returned.
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
view_orders:{projectKey},
view_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
curl --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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
If the Cart exists in the Project but does not have the store
field, or the store
field references a different Store, a ResourceNotFound error is returned.
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
view_orders:{projectKey},
view_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
curl --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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
Retrieves the recently modified active Cart of a Customer with CartOrigin Customer
. If no active Cart exists, a ResourceNotFound error is returned.
If the Cart exists in the Project but does not have the store
field, or the store
field references a different Store, a ResourceNotFound error is returned.
To ensure the Cart is up-to-date with current values (such as Prices and Discounts), use the Recalculate update action.
view_orders:{projectKey},
view_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
customerId String |
|
expand | The parameter can be passed multiple times. |
curl --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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
view_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to |
curl --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
view_orders:{projectKey},
view_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to |
curl --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"} ]}
Create Cart
Creating a Cart fails with an InvalidOperation error if the
ShippingMethod referenced in the CartDraft
has a predicate
that does not match the Cart.
manage_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
The store
field in the created Cart is set to the Store specified by the storeKey
path parameter.
Specific Error Codes: CountryNotConfiguredInStore
manage_orders:{projectKey},
manage_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
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
.
manage_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
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
.
manage_orders:{projectKey}:{storeKey},
manage_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
application/json
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
manage_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a 409 Conflict is returned. |
actions Array of CartUpdateAction | Update actions to be performed on the Cart. |
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
manage_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a 409 Conflict is returned. |
actions Array of CartUpdateAction | Update actions to be performed on the Cart. |
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
Updates a Cart in the Store specified by storeKey
.
If the Cart exists in the Project but does not have the store
field, or the store
field references a different Store, a ResourceNotFound error is returned.
manage_orders:{projectKey},
manage_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a 409 Conflict is returned. |
actions Array of CartUpdateAction | Update actions to be performed on the Cart. |
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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
If the Cart exists in the Project but does not have the store
field, or the store
field references a different Store, this method returns a ResourceNotFound error.
manage_orders:{projectKey},
manage_orders:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the Cart on which the changes apply. If the expected version does not match the actual version, a 409 Conflict is returned. |
actions Array of CartUpdateAction | Update actions to be performed on the Cart. |
application/json
curl 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,"versionModifiedAt" : "2023-01-23T13:06:28.569Z","lastMessageSequenceNumber" : 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",