ProtocolsACP

ACP — Agentic Commerce Protocol

ACP (Agentic Commerce Protocol) comes from the OpenAI and Stripe agentic-commerce work. It models a purchase as a checkout session that the agent drives through a lifecycle, with the resulting order delivered and updated out-of-band via webhooks.

Checkout-session lifecycle

AcpClient exposes the full session lifecycle:

const acp = new AcpClient({ baseUrl: 'https://merchant.example.com' });
 
const session = await acp.createSession({ items: [{ id: 'sku_123', quantity: 1 }] });
const fetched = await acp.getSession(session.id);
const updated = await acp.updateSession(session.id, { items: [/* … */] });
const completed = await acp.completeSession(session.id, { payment: /* … */ });
await acp.cancelSession(session.id);
  • createSession — open a session with line items.
  • getSession — fetch current state.
  • updateSession — mutate items, shipping, etc.
  • completeSession — finalize payment and turn the session into an order.
  • cancelSession — abandon the session.

Idempotency

Every write method accepts an optional idempotencyKey, sent as a Stripe-style Idempotency-Key header. Re-sending the same key replays the original result instead of creating a duplicate, which makes retries safe:

await acp.createSession(
  { items: [{ id: 'sku_123', quantity: 1 }] },
  { idempotencyKey: 'order-attempt-7f3a' },
);

The order model (webhooks)

In ACP the order is the durable record, and it lives on the merchant side. The merchant pushes order events to your webhook endpoint rather than the agent polling for them:

  • order_create — the order was created (typically right after completeSession).
  • order_update — the order changed: fulfillment progress, status transitions, or refunds.

Agorio verifies the merchant’s signature on these events. The receiver helpers live in src/client/acp-order-events.ts:

  • verifyMerchantSignature(...) — validate the signature header on an inbound event, throwing AcpSignatureError on mismatch.
  • signOrderEventPayload(...) / buildMerchantSignatureHeader(...) — the merchant-side counterparts (useful for testing and for mock merchants).

Refunds, fulfillment, and errors

  • Refunds are modeled as adjustments on the Order, surfaced through an order_update event rather than a separate refund object.
  • Fulfillment tracking arrives as order_update events carrying shipment/fulfillment summary data.
  • Errors are structured — the client surfaces typed error shapes so agents can branch on the failure reason instead of parsing strings.

For the full rationale on why ACP orders use a webhook model (and how that interacts with the checkout session), see ADR docs/adr/0009-acp-orders-webhook-model.md in the repository.

UCPAP2