My Carts

The My Carts API creates and provides access to Carts scoped to a specific Customer. The endpoints require an access token from the password flow or anonymous session flow.

The My Carts API intentionally provides write access only to a limited subset of the fields on a Cart. This provides extra security in scenarios when a mobile or browser application communicates directly with the Composable Commerce API on behalf of a customer. For example, the mobile application can not set external line item prices. If you need to modify a protected field available on the full Cart resource, do it from a trusted, server-side application. Use an API Extension to make the modification during the API call.

Custom Line Items and custom Tax Rates cannot be set via this API.

Representations

Find below the representations for the request payloads that are specific for My Carts, the response representations are equal to the ones for the general Carts documented there.

MyCartDraft

The customerId is determined by a password flow token and automatically set on the resulting Cart. The anonymousId is determined by a token for an anonymous session and automatically set on the resulting Cart.

currency

Currency the Cart uses.

Pattern: ^[A-Z]{3}$
customerEmail
String

Email address of the Customer the Cart belongs to.

ResourceIdentifier to the Business Unit the Cart should belong to. The Customer must be an Associate of the Business Unit.

ResourceIdentifier to the Store the Cart should belong to. Once set, it cannot be updated.

lineItems
Array of MyLineItemDraft

Line Items to add to the Cart.

taxMode

Determines how Tax Rates are set. The Disabled TaxMode cannot be set.

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

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

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.

Eligible Shipping Methods or applicable Tax Rates are determined by the Cart shippingAddress, and not itemShippingAddresses.

shippingMode
  • If set to Single, only a single Shipping Method can be added to the Cart.
  • If set to Multiple, multiple Shipping Methods can be added to the Cart.
Default: Single
discountCodes
Array of String

code of the existing DiscountCodes to add to the Cart.

country

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

Pattern: ^[A-Z]{2}$
locale

Languages of the Cart. Can only contain languages supported by the Project.

deleteDaysAfterLastModification
Int

Number of days after which a Cart with Active CartState 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.

MyLineItemDraft

For Product Variant identification, either the productId and variantId, or sku must be provided.

key
String

User-defined unique identifier of the LineItem.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
productId
String

id of the 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

Number of Product Variants 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.

supplyChannel

Used to identify Inventory entries that must be reserved. The Channel must have the InventorySupply ChannelRoleEnum.

distributionChannel

Used to select a Product Price. The Channel must have the ProductDistribution ChannelRoleEnum.

If the Cart is bound to a Store with distributionChannels set, the Channel must match one of the Store's distribution channels.

shippingDetails

Container for Line Item-specific addresses.

custom

Custom Fields for the Cart.

ReplicaMyCartDraft

reference
Union

Reference to a Cart or Order that is replicated.

Get Cart

Get Cart

GET
https://api.{region}.commercetools.com/{projectKey}/me/carts/{id}
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"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
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id}
OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"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 active Cart

GET
https://api.{region}.commercetools.com/{projectKey}/me/active-cart

Retrieves the Customer's most recently modified active Cart. Carts with Merchant or Quote CartOrigin are ignored.

If no active Cart exists, this method returns a ResourceNotFound error.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/active-cart -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get active Cart in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/active-cart

Retrieves the Customer's most recently modified active Cart in the Store specified by the storeKey path parameter.

Carts with Merchant or Quote CartOrigin are ignored.

If no active Cart exists, this method returns a ResourceNotFound error.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/active-cart -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"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

Query Carts

GET
https://api.{region}.commercetools.com/{projectKey}/me/carts
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
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
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200CartPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CartPagedQueryResponsejson
{
"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}/me/carts
OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
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
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200CartPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CartPagedQueryResponsejson
{
"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

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/carts/{id}

Checks if a Cart exists for a given id. Returns a 200 OK status if the Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists in Store

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id}

Checks ifa My Cart exists for a given id. Returns a 200 OK status if the My Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if active Cart exists

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/active-cart

Checks if an active Cart exists. Returns a 200 OK status if an active Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/active-cart -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if active Cart exists in Store

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/active-cart

Checks if an active Cart exists. Returns a 200 OK status if an active Cart exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/active-cart -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Cart exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/carts

Checks if a Cart exists for a given Query Predicate. Returns a 200 OK status if any Carts match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/carts -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}/me/carts

Checks if a Cart exists for a given Query Predicate. Returns a 200 OK status if any Carts match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Cart

When creating B2B Carts, the Customer must have the CreateMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.

Create Cart

POST
https://api.{region}.commercetools.com/{projectKey}/me/carts
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:MyCartDraftasapplication/json
Response:
201Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/me/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"currency" : "EUR"
}
DATA
201 Response Example: Cartjson
{
"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}/me/carts

The store field in the created Cart is set to the Store specified by the storeKey path parameter.

Specific Error Codes: CountryNotConfiguredInStore

OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:MyCartDraftasapplication/json
Response:
201Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"currency" : "EUR"
}
DATA
201 Response Example: Cartjson
{
"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 My Cart

POST
https://api.{region}.commercetools.com/{projectKey}/me/carts/replicate

Creates a new Cart by replicating an existing Cart or Order of the authenticated Customer. This 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.

In case the Cart or Order to be replicated does not belong to the authenticaed Customer, the API returns a ResourceNotFound error

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Request Body:ReplicaMyCartDraftasapplication/json
Response:
201Cartasapplication/json
201 Response Example: Cartjson
{
"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

When updating B2B Carts, the Customer must have the UpdateMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.

Update Cart

POST
https://api.{region}.commercetools.com/{projectKey}/me/carts/{id}
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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 ConcurrentModification error will be returned.

actions
Array of MyCartUpdateAction

Update actions to be performed on the Cart.

Response:
200Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/me/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
200 Response Example: Cartjson
{
"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

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id}

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.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Cart.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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 ConcurrentModification error will be returned.

actions
Array of MyCartUpdateAction

Update actions to be performed on the Cart.

Response:
200Cartasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/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
200 Response Example: Cartjson
{
"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 Customer Email

action
String
"setCustomerEmail"
email
String

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

Set Business Unit

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

action
String
"setBusinessUnit"

New Business Unit to assign to the Cart, which must have access to the Store that is set on the Cart. Additionally, the authenticated user must be an Associate in the 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.

action
String
"addLineItem"
key
String

User-defined unique identifier of the LineItem.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
productId
String

id of the Product.

Either the productId and variantId, or sku must be provided.

variantId
Int

id of the ProductVariant in the Product.

If not given, 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

Number of Line Items to add to the Cart.

Default: 1
addedAt

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

Optional for backwards compatibility reasons.

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.

shippingDetails

Container for Line Item-specific addresses.

custom

Custom Fields for the Line Item.

Example: json
{
"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

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

lineItemKey
String

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

quantity
Int

Amount to subtract from the LineItem's quantity. If absent, the LineItem is removed from the Cart.

externalPrice

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.

Example: json
{
"action": "removeLineItem",
"lineItemId": "{{lineItemId}}",
"quantity": 1,
"externalPrice": {
"currencyCode": "EUR",
"centAmount": 4000
},
"shippingDetailsToRemove": {
"targets": [
{
"addressKey": "AddressKeyStringFromAddress",
"quantity": 2
}
]
}
}

Add DiscountCode

Adds a DiscountCode to the Cart to activate the related CartDiscounts. 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.

Example: json
{
"action": "addDiscountCode",
"code": "mydiscountcode"
}

Remove DiscountCode

action
String
"removeDiscountCode"
discountCode

Discount Code to remove from the Cart.

Example: json
{
"action": "removeDiscountCode",
"discountCode": {
"typeId": "discount-code",
"id": "{{discount-code-id}}"
}
}

Add Payment

action
String
"addPayment"

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

Example: json
{
"action": "addPayment",
"payment": {
"id": "{{payment-id}}",
"typeId": "payment"
}
}

Remove Payment

action
String
"removePayment"

Payment to remove from the Cart.

Example: json
{
"action": "removePayment",
"payment": {
"id": "{{payment-id}}",
"typeId": "payment"
}
}

Change TaxMode

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

The new TaxMode.

Example: json
{
"action": "changeTaxMode",
"taxMode": "Platform"
}

Set Billing Address

action
String
"setBillingAddress"
address

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

Example: json
{
"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

Value to set. If not set, the shipping address is unset, and the taxedPrice and taxRate are unset in all Line Items.

Example: json
{
"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

Address to append to itemShippingAddresses.

The new address must have a key that is unique accross this Cart.

Example: json
{
"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.

Example: json
{
"action": "removeItemShippingAddress",
"addressKey": "{{addressKey}}"
}

Update ItemShippingAddress

Updates an address in itemShippingAddresses by keeping the Address key.

action
String
"updateItemShippingAddress"
address

The new Address with the same key as the Address it will replace.

Example: json
{
"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"
}
}

Set ShippingMethod

To set the Cart's Shipping Method the Cart must have the Single ShippingMode and a shippingAddress.

action
String
"setShippingMethod"

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.

Example: json
{
"action": "setShippingMethod",
"shippingMethod": {
"id": "{{shipping-method-id}}",
"typeId": "shipping-method"
}
}

Set Locale

action
String
"setLocale"
locale

Value to set. Must be one of the Project's languages. If empty, any existing value will be removed.

Example: json
{
"action": "setLocale",
"locale": "de-DE"
}

Set Country

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

action
String
"setCountry"
country

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.

Pattern: ^[A-Z]{2}$
Example: json
{
"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.

Example: json
{
"action": "setDeleteDaysAfterLastModification",
"deleteDaysAfterLastModification": 90
}

Set Custom Type

action
String
"setCustomType"

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.

Example: json
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "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.

Example: json
{
"action": "setCustomField",
"name": "ExampleStringTypeField",
"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
  • Leave empty or set to false to only update the Prices and TaxRates of the Line Items.
  • Set to true to update the Line Items' product data (like name, variant and productType) also.
Default: false
Example: json
{
"action": "recalculate",
"updateProductData": true
}

on LineItem

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.

When the action applies to LineItems with ExternalTotal LineItemPriceMode, it will be changed to ExternalPrice and the existing externalPrice value, i.e. LineItem.price, will be retained. The LineItem total will be calculated by the system instead, so that the externalTotalPrice will be dropped.

action
String
"changeLineItemQuantity"
lineItemId
String

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

lineItemKey
String

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

quantity
Int

New value to set.

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

Example: json
{
"action": "changeLineItemQuantity",
"lineItemId": "{{lineItemId}}",
"quantity": 1
}

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

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

lineItemKey
String

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

distributionChannel
  • If present, a Reference to the Channel is set for the LineItem specified by lineItemId.
  • If not present, the current Reference to a distribution channel is removed from the LineItem specified by lineItemId. The Channel must have the ProductDistribution ChannelRoleEnum.
Example: json
{
"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

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

lineItemKey
String

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

supplyChannel
  • If present, a Reference to the Channel is set for the LineItem specified by lineItemId.
  • If not present, the current Reference to a supply channel will be removed from the LineItem specified by lineItemId. The Channel must have the InventorySupply ChannelRoleEnum.
Example: json
{
"action": "setLineItemSupplyChannel",
"lineItemId": "{{lineItemId}}",
"supplyChannel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}

Set LineItem ShippingDetails

action
String
"setLineItemShippingDetails"
lineItemId
String

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

lineItemKey
String

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

shippingDetails

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

Example: json
{
"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

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

lineItemKey
String

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

targetsDelta
Array of ItemShippingTarget

Using positive or negative quantities increases or decreases the number of items shipped to an address.

Example: json
{
"action": "applyDeltaToLineItemShippingDetailsTargets",
"lineItemId": "{{lineItemId}}",
"targetsDelta": [
{
"addressKey": "addressKeyString",
"quantity": 1
}
]
}

Set LineItem Custom Type

action
String
"setLineItemCustomType"
lineItemId
String

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

lineItemKey
String

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

Defines the Type that extends the LineItem 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.

Example: json
{
"action": "setLineItemCustomType",
"lineItemId": "{{lineItemId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set LineItem CustomField

action
String
"setLineItemCustomField"
lineItemId
String

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

lineItemKey
String

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

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.

Example: json
{
"action": "setLineItemCustomField",
"lineItemId": "{{lineItemId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Delete Cart

When deleting B2B Carts, the Customer must have the DeleteMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.

Delete Cart

DELETE
https://api.{region}.commercetools.com/{projectKey}/me/carts/{id}
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Cart.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/me/carts/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"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

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id}
OAuth 2.0 Scopes:
manage_my_orders:{projectKey} , manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Cart.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
200Cartasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/me/carts/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Cartjson
{
"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": []
}