Documentation
BETA

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​
CurrencyCode​

Currency the Cart uses.

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

Email address of the Customer the Cart belongs to.

businessUnit​
BusinessUnitResourceIdentifier​

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

store​
StoreResourceIdentifier​

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​
TaxMode​

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

Default: Platform​
inventoryMode​
InventoryMode​

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

Default: None​
billingAddress​
BaseAddress​

Billing address associated with the Cart.

shippingAddress​
BaseAddress​

Shipping address associated with the Cart. Determines eligible ShippingMethod rates and Tax Rates of Line Items.

shippingMethod​
ShippingMethodResourceIdentifier​

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​
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​
CountryCode​

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

Pattern: ^[A-Z]{2}$​
locale​
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​
CustomFieldsDraft​

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: 2​MaxLength: 256​Pattern: ^[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​
DateTime​

Date and time (UTC) the Product Variant is added to the Cart. If not set, it defaults to the current date and time.

Optional for backwards compatibility reasons.

supplyChannel​
ChannelResourceIdentifier​

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

distributionChannel​
ChannelResourceIdentifier​

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​
ItemShippingDetailsDraft​

Container for Line Item-specific addresses.

custom​
CustomFieldsDraft​

Custom Fields for the Cart.

ReplicaMyCartDraft

reference​
Can be CartReference, or OrderReference​

Reference to a Cart or Order that is replicated.

Get My Cart

Get My Cart by ID

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

Returns a Cart for a given id. Returns a 200 OK status if successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists for a given id.
  • If the Cart exists but does not have a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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 My active Cart

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

Retrieves the Customer's most recently modified active Cart. Returns a 200 OK status if successful.

Carts with Merchant or Quote CartOrigin are ignored.

A ResourceNotFound error is returned in the following scenarios:

  • If no active Cart exists.
  • If an active Cart exists but does not have a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
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 My Cart in Store

Get My Cart in Store by ID

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

Returns a Cart for a given id in a Store. Returns a 200 OK status if the Cart exists.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists in the Store for the given id.
  • If the Cart exists but does not belong to a Store, or the Cart's store field references a different Store.
  • If the Cart exists but does not have either a customerId that matches the customer:{id} scope, or an anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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 My 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 a Store. Returns a 200 OK status if successful.

Carts with Merchant or Quote CartOrigin are ignored.

A ResourceNotFound error is returned in the following scenarios:

  • If no active Cart exists.
  • If an active Cart exists but does not have a store specified, or the store field references a different Store.
  • If an active Cart exists but does not have a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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 My Carts

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

Returns all Carts that match a given Query Predicate and contain either a matching customerId or anonymousId.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

Default: 0​
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.

Default: true​
var.<varName>
​
String
​

Predicate parameter values.

The parameter can be passed multiple times.
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 My Carts in Store

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

Returns all Carts that match a given Query Predicate and contain either a matching customerId or anonymousId in a Store.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

Default: 0​
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.

Default: true​
var.<varName>
​
String
​

Predicate parameter values.

The parameter can be passed multiple times.
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 My Cart exists

Check if My Cart exists by ID

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.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists for a given id.
  • If the Cart exists but does not have a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
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 My 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 successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no active Cart exists.
  • If an active Cart exists but does not have a customerId that matches the customer:{id} scope, or an anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
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 My Cart exists by Query Predicate

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

Checks if a Cart exists that matches a given Query Predicate and contains either a matching customerId or anonymousId. Returns a 200 OK status if the Cart exists, or a ResourceNotFound error otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
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 My Cart exists in Store

Check if My Cart exists in Store by ID

HEAD
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}customer_id:{id}anonymous_id:{id}
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 My 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 in a Store. Returns 200 OK status if successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no active Cart exists in a Store.
  • If an active Cart exists but does not have a store specified, or the store field references a different Store.
  • If an active Cart exists but does not contain a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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 My 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 Store that matches the given Query Predicate, and contains a matching customerId or anonymousId. Returns a 200 OK status if any Carts match these conditions, or a ResourceNotFound error otherwise.

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
QueryPredicate
​
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 My Cart

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

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

Creates a Cart for the Customer or anonymous user. The customerId or anonymousId field on the Cart is automatically set based on the customer:{id} or anonymous_id:{id} scope.

Specific Error Codes:

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
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 My Cart in Store

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

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

Creates a Cart in a Store for the Customer or anonymous user. The customerId or anonymousId field on the Cart is automatically set based on the customer:{id} or anonymous_id:{id} scope.

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

Specific Error Codes:

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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

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

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.

If the Cart or Order to be replicated does not belong to the authenticated Customer, the API returns a ResourceNotFound error

Specific Error Codes:

OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
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 My Cart

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

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

Updates the Cart for a given id. Returns a 200 OK status if successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists for a given id.
  • If the Cart exists but does not have a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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 My Cart in Store

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

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

Updates the Cart for a given id in a Store. Returns a 200 OK status if successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists in the Store for the given id.
  • If the Cart exists but does not belong to a Store, or the Cart's store field references a different Store.
  • If the Cart exists but does not have either a customerId that matches the customer:{id} scope, or an anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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"
businessUnit​
BusinessUnitResourceIdentifier​

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. 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: 2​MaxLength: 256​Pattern: ^[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​
DateTime​

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​
ChannelResourceIdentifier​

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​
ChannelResourceIdentifier​

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

shippingDetails​
ItemShippingDetailsDraft​

Container for Line Item-specific addresses.

custom​
CustomFieldsDraft​

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}}"
  },
  "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​
Money​

Sets the LineItem price to the given value when decreasing the quantity of a Line Item with the ExternalPrice LineItemPriceMode.

externalTotalPrice​
ExternalLineItemTotalPrice​

Sets the LineItem price and totalPrice to the given value when decreasing the quantity of a Line Item with the ExternalTotal LineItemPriceMode.

shippingDetailsToRemove​
ItemShippingDetailsDraft​

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​
DiscountCodeReference​

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​
PaymentResourceIdentifier​

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​
PaymentResourceIdentifier​

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​
TaxMode​

The new TaxMode.

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

Set Billing Address

action​
String​
"setBillingAddress"
address​
BaseAddress​

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​
BaseAddress​

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​
BaseAddress​

Address to append to itemShippingAddresses.

The new address must have a key that is unique across 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​
BaseAddress​

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"
shippingMethod​
ShippingMethodResourceIdentifier​

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​
ExternalTaxRateDraft​

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​
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​
CountryCode​

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

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

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"
type​
TypeResourceIdentifier​

Defines the Type that extends the Cart with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Cart.

fields​
FieldContainer​

Sets the Custom Fields fields for the Cart.

Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

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": "exampleStringField",
  "value": "TextString"
}

Recalculate

This update action does not set any Cart field in particular, but it triggers several Cart updates to bring prices and discounts to the latest state. Those can become stale over time when no Cart updates have been performed for a while and prices on related Products have changed in the meanwhile.

If the priceMode of the Product related to a Line Item is of Embedded ProductPriceMode, the updated price of that LineItem may not correspond to a Price in the variant.prices anymore.

action​
String​
"recalculate"
updateProductData​
Boolean​
  • 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
}

Change LineItems Order

action​
String​
"changeLineItemsOrder"
lineItemOrder​
Array of String​

All existing LineItem ids of the Cart in the desired new order.

Example: json
{
  "action": "changeLineItemsOrder",
  "lineItemOrder": ["{{lineItemId2}}", "{{lineItemId}}"]
}

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​
ChannelResourceIdentifier​
  • 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​
ChannelResourceIdentifier​
  • 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​
ItemShippingDetailsDraft​

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.

type​
TypeResourceIdentifier​

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​
FieldContainer​

Sets the Custom Fields fields for the Line Item.

Example: json
{
  "action": "setLineItemCustomType",
  "lineItemId": "{{lineItemId}}",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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​
CustomFieldValue​

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": "exampleStringField",
  "value": "TextString"
}

Delete My Cart

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

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

Deletes the Cart for a given id. Returns a 200 OK status if successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists for a given id.
  • If the Cart exists but does not have a customerId that matches the customer:{id} scope, or anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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 My Cart in Store

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

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

Deletes the Cart for a given id in a Store. Returns a 200 OK status if successful.

A ResourceNotFound error is returned in the following scenarios:

  • If no Cart exists in the Store for the given id.
  • If the Cart exists in the Project but does not belong to a Store, or the Cart's store field references a different Store.
  • If the Cart exists in the Project but does not have either a customerId that matches the customer:{id} scope, or an anonymousId that matches the anonymous_id:{id} scope.
OAuth 2.0 Scopes:
manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}customer_id:{id}anonymous_id:{id}
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
​
Expansion
​
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": []
}