Agentic Commerce Protocol (ACP)

The Agentic Commerce Protocol is the spec ChatGPT Instant Checkout and other AI shopping engines speak when they want to actually buy from a shop. Cartwright ships it natively: a JSONL product feed plus stateless checkout sessions that wrap your existing pricing, tax, and inventory rules.

ACP is distinct from A2A. A2A is the negotiation surface (agent ↔ shop bargaining via Anchor-and-Resume). ACP is the purchase surface (agent ↔ shop transacts). A shop can opt into one, both, or neither.

Feature gate

ACP is gated behind brand.features.acp (default false on most templates, true on agent-marketplace). When off, every /api/acp/* route returns 404 — your storefront surface stays clean.

// brand.config.ts
features: {
  acp: true,            // turn the ACP surface on
  a2a: false,           // independent of A2A
  webshop: true,        // a shop can serve humans AND ACP buyers
}

GET /api/acp/feed

A newline-delimited JSON feed of your live catalogue. ChatGPT Instant Checkout reads this directly — no merchant centre upload, no XML schema, no GTIN guesswork.

curl https://example-shop.app/api/acp/feed

Response (one JSON object per line):

{"id":"prod_001","title":"Sunglass Frame Mahogany","price":{"amount":"599.00","currency":"DKK"},"availability":"in_stock","brand":"Atelier","image_link":"https://example-shop.app/img/prod_001.jpg","link":"https://example-shop.app/products/sunglass-frame-mahogany"}
{"id":"prod_002","title":"Lens Pair Polarised","price":{"amount":"299.00","currency":"DKK"},"availability":"in_stock","brand":"Atelier","image_link":"https://example-shop.app/img/prod_002.jpg","link":"https://example-shop.app/products/lens-pair-polarised"}

The feed is regenerated on demand — no cron, no stale snapshots. Field shape follows the ACP product-feed spec; Cartwright maps Product, Category, and ProductVariant rows into the canonical fields.

POST /api/acp/v1/checkout_sessions

Create a checkout session. The buyer agent posts line items + shipping address; Cartwright responds with totals computed by lib/pricing.ts and a session id the agent uses to complete or update.

curl -X POST https://example-shop.app/api/acp/v1/checkout_sessions \
  -H "Authorization: Bearer <api-key>" \
  -H "Idempotency-Key: 7f3e9a1b-4d8c-4e5a-9b2f-1a3c5d7e9f0a" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "product_id": "prod_001", "quantity": 2 }
    ],
    "shipping_address": {
      "name": "Buyer Agent",
      "line1": "Rådhuspladsen 1",
      "city": "Copenhagen",
      "postal_code": "1550",
      "country": "DK"
    }
  }'

Response:

{
  "id": "cs_2NjAaP1eZvKYlo2C0",
  "object": "checkout_session",
  "status": "open",
  "currency": "DKK",
  "line_items": [
    { "product_id": "prod_001", "quantity": 2, "amount_subtotal_minor": 119800 }
  ],
  "totals": {
    "subtotal_minor": 119800,
    "tax_minor": 29950,
    "shipping_minor": 4900,
    "total_minor": 154650
  },
  "expires_at": "2026-05-25T09:00:00Z"
}

Update, cancel, complete

Sessions are stateful (DB-backed) but the protocol is request-idempotent. Send the same Idempotency-Key and the same response replays.

• GET /api/acp/v1/checkout_sessions/{id} — read current state
• POST /api/acp/v1/checkout_sessions/{id}/update — change line items or shipping
• POST /api/acp/v1/checkout_sessions/{id}/cancel — abandon
• POST /api/acp/v1/checkout_sessions/{id}/complete — finalise the session. Gated behind ACP_PAYMENT_COMPLETION=1 (default off). The full flow is now wired: it charges via a Stripe Shared Payment Token (off-session PaymentIntent), builds the order from the session line items (not the cart), replays on the idempotency key, and refunds if order creation fails. It stays inert (501) until external Stripe SPT access + ChatGPT merchant onboarding are connected — so it can never accidentally move money before you go live

curl -X POST https://example-shop.app/api/acp/v1/checkout_sessions/cs_2NjAaP1eZvKYlo2C0/complete \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "shared_payment_token": "spt_…", "idempotency_key": "7f3e9a1b-…" }'

When live, complete returns the completed session plus an order reference; the off-session charge resolves to succeeded or fails cleanly (a card requiring 3DS/SCA can't be resolved off-session, so it's treated as a failed charge with an automatic refund).

UCP: native_commerce capability

Google's Unified Commerce Protocol (UCP) lets agents discover which catalogue products are native-buyable. When acp is on, the Google Merchant feed (/feed/google.xml) emits <g:native_commerce>enabled</g:native_commerce> per item, and /.well-known/ucp advertises a native_commerce capability — gated on acp plus merchantFeed. The gating is deliberate: the shop never advertises a capability it can't honour.

UCP: identity-linking (OAuth 2.0)

UCP also defines dev.ucp.common.identity_linking — how an agentic platform gets delegated, scoped permission to act on a shopper's behalf across merchants. Cartwright ships it as a full OAuth 2.0 Authorization Code + PKCE server behind the ucpIdentityLinking flag (default-off): RFC 8414/9728 discovery metadata, RFC 7591 dynamic registration, /oauth/{authorize,token,revoke} with a consent screen, and a sample protected resource at /api/ucp/orders. See UCP identity-linking for the endpoints, scopes, and setup.

Authentication

All POST endpoints require a Bearer token. API keys are managed at /admin/api-keys and can be scoped to acp:checkout only — restricting what the key can do is enforced before the handler runs.

Relationship to A2A

ACP is the purchase surface. A2A is the negotiation surface. The two sit side by side:

A shop with only features.acp = true ships a "just-buy-it" surface (fixed prices, no haggling). A shop with both acp and a2a lets agents discover, negotiate, then settle via either ACP checkout or A2A escrow.