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 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.
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 - Optionalcountry- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2.inventoryMode- InventoryMode - Optional
Default inventory mode isNone.lineItems- Array of MyLineItemDraft - OptionalshippingAddress- AddressDraft - OptionalbillingAddress- AddressDraft - OptionalshippingMethod- ResourceIdentifier of a ShippingMethod - Optionalcustom- CustomFieldsDraft - Optional The custom fields.locale- String conforming to IETF language tag - OptionaltaxMode- TaxMode TheTaxModeDisabledcan 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. If not set, the default value configured in the Project is used.
If a ChangeSubscription for carts exists, aResourceDeletednotification will be sent.itemShippingAddresses- Array of AddressDraft
Contains addresses for orders with multiple shipping addresses. Each address must contain a key which is unique in this cart.businessUnit- BusinessUnitKeyReference - BETA - Optional
Assigns the new cart to the business unit. The business unit can not be modified.store- KeyReference to a Store - Optional
Assigns the new cart to the store. The store assignment can not be modified.discountCodes- Array of Strings - Optional
Thecodeof existing DiscountCodes.
MyLineItemDraft
- LineItemDraft Product Variant identification - Required
quantity- Number - Optional - Defaults to1supplyChannel- ResourceIdentifier of a Channel - Optional
By providing supply channel information, you can uniquely identify inventory entries that should be reserved. The Channel must have theInventorySupplyChannelRoleEnum. If the cart is bound to a Store withsupplyChannelsset, the channel has to match one of the store's supply channels.distributionChannel- ResourceIdentifier of a Channel - Optional
The channel is used to select a Price. The Channel must have theProductDistributionChannelRoleEnum If the cart is bound to a Store withdistributionChannelsset, the channel has to match one of the store's distribution channels.custom- CustomFieldsDraft - Optional
The custom fields.shippingDetails- ItemShippingDetailsDraft - Optional
Container for line item specific address(es).addedAt- DateTime - Optional
When the line item was added to the cart. Defaults to the current date and time.
ReplicaMyCartDraft
Body to create a new cart by replicating an existing cart or order.
Get a Cart
Get Cart by ID
Endpoint: /{projectKey}/me/carts/{id}
Method: GET
OAuth 2.0 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
OAuth 2.0 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
OAuth 2.0 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 or Quote. 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
OAuth 2.0 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 or Quote. If no active cart exists, a 404 Not Found error is returned.
Query Carts
Query Carts
Endpoint: /{projectKey}/me/carts
Method: GET
OAuth 2.0 Scopes: manage_my_orders:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Cart
Query Parameters:
where- Query Predicate - Optionalsort- Sort - Optionalexpand- Expansion - Optionallimit- Number - Optionaloffset- Number - Optional
Query Carts in a Store
Endpoint: /{projectKey}/in-store/key={storeKey}/me/carts
Method: GET
OAuth 2.0 Scopes: manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with results containing an array of Cart
Query Parameters:
where- Query Predicate - Optionalsort- Sort - Optionalexpand- Expansion - Optionallimit- Number - Optionaloffset- Number - Optional
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
OAuth 2.0 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
OAuth 2.0 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
OAuth 2.0 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
OAuth 2.0 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 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.
action- String -"addLineItem"productId- String - Required
ID of an existing Product.variantId- Number - Required
ID of an existing ProductVariant in the product.quantity- Number - Optional - Defaults to1supplyChannel- ResourceIdentifier of a Channel - Optional
By providing supply channel information, you can uniquely identify inventory entries that should be reserved. The Channel must have theInventorySupplyChannelRoleEnum.distributionChannel- ResourceIdentifier of a Channel - Optional
The channel is used to select a Price. The Channel must have theProductDistributionChannelRoleEnumcustom- CustomFieldsDraft - Optional
The custom fields.shippingDetails- ItemShippingDetailsDraft - Optional
Container for line item specific address(es).addedAt- DateTime - Optional
When the line item was added to the cart. Defaults to the current date and time.
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 LineItem DistributionChannel
As described here.
Set LineItem SupplyChannel
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.
Set Business Unit
As described here. Additionally, the authenticated user must have Buyer access to the Business Unit.
Delete Cart
Delete a Cart
Endpoint: /{projectKey}/me/carts/{id}
Method: DELETE
OAuth 2.0 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
OAuth 2.0 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.
Replicate an existing cart or order to a new cart
Creating a new cart by replicating an existing cart or order can be useful in case a customer wants to cancel a recent order to make some changes, or if a previous order should be ordered again.
The replica will attempt to preserve customer information, line items and custom line items, custom fields, discount codes, as well as other settings of the cart or order. If any of the line items have become invalid, for example due to removed products or prices, those items are removed from the new cart. If the customer has switched to another customer group, the new cart contains the new group.
The replica 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 the initial state.
Replicate My Cart
Endpoint: /{projectKey}/me/carts/replicate
Method: POST
OAuth 2.0 Scopes: manage_my_orders:{projectKey}
Request Representation: ReplicaMyCartDraft
Response Representation: Cart