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

MyLineItemDraft

ReplicaMyCartDraft

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.

(oneOf): CartReference,OrderReference

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:

200

Cart

asapplication/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:

200

Cart

asapplication/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:

200

Cart

asapplication/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:

200

Cart

asapplication/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:

200

CartPagedQueryResponse

asapplication/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:

200

CartPagedQueryResponse

asapplication/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:

201

Cart

asapplication/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:

201

Cart

asapplication/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:

201

Cart

asapplication/json

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:

200

Cart

asapplication/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:

200

Cart

asapplication/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": []
}

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. Minimum: `0`
`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.

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. Minimum: `0`

Example: json

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

Change LineItems Order

`action` String	`"changeLineItemsOrder"`
`lineItemOrder` Array of String	All existing LineItem `id`s 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:

200

Cart

asapplication/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:

200

Cart

asapplication/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": []
}

My Carts

Representations

MyCartDraft

MyLineItemDraft

ReplicaMyCartDraft

Get My Cart

Get My Cart by ID

Get My active Cart

Get My Cart in Store

Get My Cart in Store by ID

Get My active Cart in Store

Query My Carts

Query My Carts in Store

Check if My Cart exists

Check if My Cart exists by ID

Check if My active Cart exists

Check if My Cart exists by Query Predicate

Check if My Cart exists in Store

Check if My Cart exists in Store by ID

Check if My active Cart exists in Store

Check if My Cart exists in Store by Query Predicate

Create My Cart

Create My Cart in Store

Replicate My Cart

Update My Cart

Update My Cart in Store

Update actions

on Cart

Set Customer Email

Set Business Unit

Add LineItem

Remove LineItem

Add DiscountCode

Remove DiscountCode

Add Payment

Remove Payment

Change TaxMode

Set Billing Address

Set Shipping Address

Add ItemShippingAddress

Remove ItemShippingAddress

Update ItemShippingAddress

Set ShippingMethod

Set Locale

Set Country

Set DeleteDaysAfterLastModification

Set Custom Type

Set CustomField

Recalculate

on LineItem

Change LineItem Quantity

Change LineItems Order

Set LineItem DistributionChannel

Set LineItem SupplyChannel

Set LineItem ShippingDetails

Apply DeltaToLineItemShippingDetailsTargets

Set LineItem Custom Type

Set LineItem CustomField

Delete My Cart

Delete My Cart in Store