Agentic commerce: UCP and ACP

Agentic commerce is the signed shopping-agent surface in commerce-api. It is separate from the AI COO MCP catalog in apps/ai-coo-cf.

Public mount

commerce-api mounts public agentic commerce under:

/agentic/

The route family is wrapped with CORS, database backpressure, signature-based scope resolution, and agentic-commerce rate limiting.

Route families

Surface	Route
UCP REST	`/agentic/ucp/{brand_id}/...`
UCP MCP	`POST /agentic/ucp/{brand_id}/mcp`
ACP checkout	`/agentic/acp/{brand_id}/...`

UCP REST exposes catalog, cart, checkout-session, and order-status resources. UCP MCP exposes protocol-specific MCP-style tools for the same commerce boundary. ACP checkout exposes checkout-session operations for ACP clients.

UCP REST resources

Source routes in ucprest/handler.go:

Method	Path
`GET`	`/agentic/ucp/{brand_id}/catalog/offers`
`GET`	`/agentic/ucp/{brand_id}/catalog/offers/{offer_id}`
`POST`	`/agentic/ucp/{brand_id}/carts`
`GET`	`/agentic/ucp/{brand_id}/carts/{cart_id}`
`POST`	`/agentic/ucp/{brand_id}/carts/{cart_id}/items`
`POST`	`/agentic/ucp/{brand_id}/carts/{cart_id}/items/{item_id}`
`DELETE`	`/agentic/ucp/{brand_id}/carts/{cart_id}/items/{item_id}`
`POST`	`/agentic/ucp/{brand_id}/checkout-sessions`
`GET`	`/agentic/ucp/{brand_id}/checkout-sessions/{checkout_session_id}`
`POST`	`/agentic/ucp/{brand_id}/checkout-sessions/{checkout_session_id}`
`POST`	`/agentic/ucp/{brand_id}/checkout-sessions/{checkout_session_id}/complete`
`POST`	`/agentic/ucp/{brand_id}/checkout-sessions/{checkout_session_id}/cancel`
`GET`	`/agentic/ucp/{brand_id}/orders/{order_id}`

Auth and scope

Agentic commerce requests are signed. The verifier package implements RFC 9421-style signature validation, Content-Digest verification, freshness checks, replay protection, and tenant/brand/domain scope derivation from trusted key metadata.

The resolved scope includes tenant, brand, domain, API key, protocol, protocol version, and agent identity. The route path brand must match the resolved scope.

Rate limits

The agentic commerce limiter has tier windows:

Tier	Per minute	Per hour
Core	100	1000
Growth	300	5000
Scale, Enterprise, Practice	1000	20000

Requests are keyed by tenant, API-key prefix, and time window.

UCP profile generation

The internal UCP profile helper is not public customer traffic. It is mounted under:

POST /internal/agentic-commerce/ucp/profile
POST /internal/agentic-commerce/ucp/profile/health-check

It generates and checks .well-known/ucp profile documents from tenant, brand, domain, capability base URL, protocol versions, payment handlers, and signing keys. The internal mount requires service authentication.

Boundary with AI COO MCP

Do not document these commerce protocol routes as AI COO MCP tools. They are commerce-agent protocol endpoints for shopping/storefront agents. AI COO back-office tools remain in apps/ai-coo-cf/src/tools/catalog.ts.