Agentic commerce
The readiness status, signing key, feed files and agent sessions behind the Agentic commerce screen.
The admin side of Agentic commerce: whether the store is ready for UCP, the signing key, the product feed files and the sessions agents have open. The public storefront MCP tools are not admin routes; they are on Storefront MCP.
Agentic commerce status
/api/v1/kahunacart/agentic/status
Whether this store is ready for AI shopping agents. Answers ready and problems, everything standing between the store and a working UCP profile at /.well-known/ucp, each with a code and a sentence; which of the three switches (product feeds, storefront MCP, UCP) are on; the profile, REST and MCP endpoint URLs; the current signing key's kid and dates (never the key itself) and any retired key still published; the feed files with their URLs and build times; and how many agent sessions are open now.
Rotate the UCP signing key
/api/v1/kahunacart/agentic/keys/rotate
Make a new ES256 signing key and retire the current one. The retired key stays in the published profile for seven days, so platforms can still verify webhooks it signed. Answers the new kid and every stored key's dates. Also the way to make the first key when there is none. No private key is ever returned.
List agent sessions
/api/v1/kahunacart/agentic/sessions
UCP checkout and cart sessions and MCP carts, newest first: the kind, the status, the protocol, the platform it belongs to, the cart or order it points at (with the order number once the order is placed) and its dates. The session id is shortened, because the full id is the agent's capability to that cart. Also answers open, the number of sessions open now. Filter with status; page with page and per_page.
Parameters
| Name | Type | Description |
|---|---|---|
| status optional | string |
One of:
incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled |
| sort optional | string |
A column to sort the whole list by before it is paged; leave out for newest first
One of:
session, status, platform, order, started |
| dir optional | string |
One of:
asc, descDefault:
asc |
| q optional | string | Words to search for in the session id, its kind, the platform and the order number; every word has to be there, in any order. Applied before the sort and the page, and total counts what it found |
| page optional | integer |
At least 1.
Default:
1 |
| per_page optional | integer |
At least 1, at most 100.
Default:
25 |
List product feeds
/api/v1/kahunacart/feeds
The Google Merchant Center and OpenAI product feed files, one per language (and, on a store that sells in more than one currency, one per currency, each row naming its currency): whether each is switched on, the URL to register it at, whether that URL needs ?key= (the key itself is not returned), when it was last built, how many rows it has and whether it is older than feeds.max_age.
Rebuild the product feeds
/api/v1/kahunacart/feeds/rebuild
Queue a build of every enabled feed for every language, due now. The job worker builds it. A build already waiting is kept rather than doubled, and its job id is answered. Answers 409 while the feeds are switched off.
Mark a shipment delivered
/api/v1/kahunacart/orders/{id}/shipments/{sid}/delivered
Record that a parcel arrived. Sets the shipment's delivered date once; a second call on a delivered shipment changes nothing. Fires onKahunaCartShipmentDelivered, which tells the UCP platform an agent order came from. Read list_shipments for the shipment ids.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Order id |
| sid required | integer | Shipment id, from list_shipments |
The status never returns a private key, and the feed list never returns feeds.access_key, only whether a URL needs it. A session comes back with a shortened reference rather than its id, because the full id is the agent's access to that cart. rebuild_feeds answers 409 while feeds.enabled is off, and keeps a build already waiting rather than booking a second one. Rotating the key and rebuilding the feeds are writes, so a demo store refuses both.