Universal Cart
How a platform hands a shopper's basket to a Storeware shop over UCP, and what the shop does with it.
A shopper fills a basket on another platform, such as Google's AI Mode or Gemini, and chooses to finish on the shop's own site. The platform sends the lines to the shop's UCP cart endpoint and sends the shopper to the address in the answer. Every Storeware shop with UCP open serves this, and nothing is built per shop.
The calls
The shop's profile at https://<shop>/.well-known/ucp declares dev.ucp.shopping.cart and names the REST endpoint. The cart routes are on the API, under https://api.storeware.ai/api/ucp/v1:
| Call | Route |
|---|---|
| Create Cart | POST /carts |
| Get Cart | GET /carts/{id} |
| Update Cart | PUT /carts/{id} |
| Cancel Cart | POST /carts/{id}/cancel |
Each takes the agent key the merchant issued to the platform, as Authorization: Bearer or as X-API-Key, and the platform's profile in UCP-Agent. See UCP and ACP.
What the shop does
- Create opens a basket marked as an agent's, under the key that asked, so the merchant sees it beside every other agent basket and a sale from it counts as that key's. Each line is checked for stock and priced in one step.
- A line that cannot be supplied comes back as a warning,
out_of_stockoritem_unavailable, on a cart that holds everything else. When nothing can be supplied, no cart is made and the answer is an error,out_of_stockonly when every line was refused for stock. - A quantity in a unit the shop does not sell by is refused with a message naming the field. Storeware shops sell whole items.
continue_urlis the shop's own/checkout/<id>. It puts the basket in the shopper's browser and opens the cart page with the lines in it. If the key that made it was linked to a shopper, the basket opens only for that shopper, so a visitor who is not signed in is asked to sign in first.- Cancel answers with the cart as it was. Afterwards Get Cart answers
not_found, while the checkout surface reads the same basket ascanceled.
Where a cart narrows the spec
- The cart id is the checkout id: they are one basket. When cart was negotiated, a Create Checkout that names
cart_idkeeps the cart's lines, context and buyer. - Totals are estimates, and their labels say so, because tax and delivery need an address a cart usually lacks.
- A cart expires with its basket, a week after its last change.
- The request's
attributionobject is not used: the key the merchant issued already attributes the sale.
Releases
A platform built against an earlier UCP release than the shop's current one is answered at its own, when the shop lists that release under supported_versions in its profile. Read the profile to see which releases a shop answers.
For the merchant
Turning the transfer on at the platform's side is the merchant's job, in their own account there. On Storeware they issue the platform an agent key on the AI shoppers screen, one for each of the platform's environments, labelled so either can be revoked without the other. The product ids in a Storeware product feed are already the variant ids a cart takes.