My Carts

The My Carts endpoint creates and provides access to carts scoped to a specific user. The endpoint requires an access token from the password flow or anonymous session flow.

The My Carts endpoint 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 commercetools 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.

Representations

All representations are JSON objects submitted or received as payload to API requests or responses. Responses are equal to the responses on the cart endpoint, but requests may differ. Custom line items and custom tax rates can not be set via this endpoint.

MyCartDraft

A CartDraft is the object submitted as payload to a Create Cart method. The customerId is automatically set with a password flow token. The anonymousId is automatically set with a token for an anonymous session.

  • currency - String - Required
    A three-digit currency code as per ↗ ISO 4217 .
  • customerEmail - String - Optional
  • country - String - Optional
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .
  • inventoryMode - InventoryMode - Optional
    Default inventory mode is None.
  • lineItems - Array of MyLineItemDraft - Optional
  • shippingAddress - Address - Optional
  • billingAddress - Address - Optional
  • shippingMethod - ResourceIdentifier to a ShippingMethod - Optional
  • custom - CustomFieldsDraft - Optional The custom fields.
  • locale - String conforming to ↗ IETF language tag - Optional
  • taxMode - TaxMode The TaxMode Disabled can not be set on the My Carts endpoint.
  • deleteDaysAfterLastModification - Number - Optional
    The cart will be deleted automatically if it hasn’t been modified for the specified amount of days and it is in the Active CartState. If a ChangeSubscription for carts exists, a ResourceDeleted notification will be sent.
  • itemShippingAddresses - Array of Address
    Contains addresses for orders with multiple shipping addresses. Each address must contain a key which is unique in this cart.

MyLineItemDraft

Get a Cart

Get Cart by ID

Endpoint: /{projectKey}/me/carts/{id}
Method: GET
OAuth2 Scopes: manage_my_orders:{projectKey}
Response Representation: Cart

Get a Cart in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/me/carts/{id}
Method: GET
OAuth2 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Response Representation: Cart

Returns a cart by its ID from a specific Store. The {storeKey} path parameter maps to a Store’s key.

Get Active Cart

Endpoint: /{projectKey}/me/active-cart
Method: GET
OAuth2 Scopes: manage_my_orders:{projectKey}
Response Representation: Cart

Retrieves the active cart (the cart that has been modified most recently). It does not consider carts with CartOrigin Merchant. If no active cart exists, a 404 Not Found error is returned.

Get Active Cart in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/me/active-cart
Method: GET
OAuth2 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Response Representation: Cart

Retrieves the active cart (the cart that has been modified most recently) from a specific Store. The {storeKey} path parameter maps to a Store’s key.

This endpoint does not consider carts with CartOrigin Merchant. If no active cart exists, a 404 Not Found error is returned.

Query Carts

Query Carts

Endpoint: /{projectKey}/me/carts
Method: GET
OAuth2 Scopes: manage_my_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of Cart
Query Parameters:

Query Carts in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/me/carts
Method: GET
OAuth2 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with the results array of Cart
Query Parameters:

Queries carts in a specific Store. The {storeKey} path parameter maps to a Store’s key.

Create a Cart

Create a Cart

Endpoint: /{projectKey}/me/carts
Method: POST
OAuth2 Scopes: manage_my_orders:{projectKey}
Request Representation: MyCartDraft
Response Representation: Cart

Create a Cart in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/me/carts
Method: POST
OAuth2 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Request Representation: MyCartDraft
Response Representation: Cart

Creates a cart in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store’s key.

When using this endpoint the cart’s store field is always set to the store specified in the path parameter.

Update Cart

Update a Cart

Endpoint: /{projectKey}/me/carts/{id}
Method: POST
OAuth2 Scopes: manage_my_orders:{projectKey}
Response Representation: Cart
Fields:

  • version - Number - Required
    The expected version of the cart on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the cart.

Update a Cart in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/me/carts/{id}
Method: POST
OAuth2 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Response Representation: Cart
Fields:

  • version - Number - Required
    The expected version of the cart on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the cart.

Updates a cart in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store’s key.

If the cart exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Update Actions

Add LineItem

Adds a product variant in the given quantity to the cart. If the cart already contains the product variant for the given supply and distribution channel, then only quantity of LineItem and ItemShippingDetails, if used, are increased.

The price is selected as described here.

Remove LineItem

As described here.

Change LineItem Quantity

As described here.

Set Customer Email

As described here.

Set Shipping Address

As described here.

Set Billing Address

As described here.

Set Country

As described here.

Set ShippingMethod

As described here.

Set Custom ShippingMethod

As described here.

Add DiscountCode

As described here.

Remove DiscountCode

As described here.

Recalculate

As described here.

Set Custom Type

As described here.

Set CustomField

As described here.

Set LineItem Custom Type

As described here.

Set LineItem CustomField

As described here.

Set Locale

As described here.

Add Payment

As described here.

Remove Payment

As described here.

Change TaxMode

As described here, except that the TaxMode Disabled can not be set on the My Carts endpoint.

Set DeleteDaysAfterLastModification

As described here.

Apply DeltaToLineItemShippingDetailsTargets

As described here.

Set LineItemShippingDetails

As described here.

Add ItemShippingAddress

As described here.

Remove ItemShippingAddress

As described here.

Update ItemShippingAddress

As described here.

Delete Cart

Delete a Cart

Endpoint: /{projectKey}/me/carts/{id}
Method: DELETE
OAuth2 Scopes: manage_my_orders:{projectKey}
Response Representation: Cart
Query parameters:

  • version - Number - Required

Removes a Cart.

Delete a Cart in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/me/carts/{id}
Method: DELETE
OAuth2 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Response Representation: Cart
Query parameters:

  • version - Number - Required

Removes a Cart in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store’s key.