Cart

The Cart capability lets AI agents on Google surfaces build and manage a shopping cart in your commercetools Project before the buyer starts checkout.

The Cart capability implements the UCP cart capability (dev.ucp.shopping.cart). An agent can add items, change quantities, and read back pricing across several conversation turns, and then hand the cart over to Checkout when the buyer is ready to pay or bring user to merchant website for completing checkout.

The Cart capability is part of the Checkout component. It is enabled by default and requires no additional configuration.

Core capabilities

Cart lifecycle: supports the full UCP cart lifecycle. Each operation maps to a commercetools Cart in the Store configured for the Checkout component.

Operation	Endpoint	Description
Create cart	`POST /ucp/v1/carts`	Creates a Cart with the requested Line Items and buyer information.
Get cart	`GET /ucp/v1/carts/{id}`	Returns the current state of the Cart, including Line Items, prices, and totals.
Update cart	`PUT /ucp/v1/carts/{id}`	Replaces the Line Items and buyer information of the Cart, and recalculates prices and totals.
Cancel cart	`POST /ucp/v1/carts/{id}/cancel`	Deletes the Cart and returns its final state.

Discovery: the cart capability is advertised in the UCP discovery profile served at /.well-known/ucp, so Google detects support automatically.

Store scoping: all Carts are created in the configured Store and priced with its currency, country, distribution Channel, and supply Channel. A Cart created through UCP cannot be read or modified through another Store.

Shopper ownership: when a request carries a linked identity, the Cart is linked to that shopper, and only that shopper can read, update, or cancel it. Requests without a linked identity create anonymous Carts, and can only reach anonymous Carts.

Functional considerations

Product availability

Before a Cart is created or updated, the component checks that every requested SKU is sold in the Store. A SKU must be:

Included in a Product Selection assigned to the Store.
Priced for the Store's currency, country, and distribution Channel.
Available in the Store's supply Channel, when one is configured.

If any SKU does not meet these conditions, the whole request is refused and no Cart is created or changed.

All-or-nothing updates

Cart writes are atomic. The Cart returned by a create or update request contains everything the request asked for. If commercetools rejects any Line Item, for example because it is out of stock or its quantity exceeds a limit, the whole request is refused and the Cart stays unchanged.

Updates replace the full set of Line Items and buyer information. Agents must send the complete Cart content on every update, not only the changed items. To empty a Cart, send an update with an empty list of Line Items.

The Cart currency, language, and country come from the Store configuration, so agents don't need to send them. A create request that names a different currency, language, or country than the Store is refused. The Cart currency is set at creation and cannot be changed. An update request with a different currency is applied without the currency change, and the response contains a message that explains this.

API Extensions

If an API Extension in your Project refuses a Cart write, the whole request is refused and the message from your extension is returned to the agent. For more information, see Checkout extensibility.

Error handling

Business errors are returned as UCP error responses with a message for each affected Line Item. Each message names the item and tells the agent what to do next.

commercetools error	Message returned to the agent
`OutOfStock`	It is out of stock. Ask for fewer of it, or leave it out of the cart.
`PriceChanged`	Its price changed. Read the cart again and send the request again.
`LineItemQuantityAboveLimit`	The quantity asked for is above the maximum the store allows. Ask for fewer.
`LineItemQuantityBelowLimit`	The quantity asked for is below the minimum the store allows. Ask for more.
`ReferencedResourceNotFound`	The catalog has no item with that id. Search the catalog again and use an id it returns.
`MatchingPriceNotFound`	The store has no price for it. Leave it out of the cart, or search the catalog again.

A request for a Cart that does not exist, or that belongs to another shopper, returns a not-found error.

Localization

Line Item names are returned in the language of the request. If the product has no name in that language, the Store's default language is used. Get and cancel requests use the language the Cart was created with.

Tax and pricing

Prices, discounts, and taxes are calculated using the same configuration as Checkout. For details, see Tax configuration.

Limitations

Cancelling a Cart permanently deletes it from your commercetools Project.
Carts that are not modified are deleted automatically after the number of days set in your Project's Cart configuration, and the response reports the expiry date when one applies.
Shipping Methods and payment are not part of the Cart capability. They are handled during Checkout.

Core capabilities.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Functional considerations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product availability.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

All-or-nothing updates.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

API Extensions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Error handling.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Localization.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Tax and pricing.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Limitations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}