Skip to main content
Merchant-side adapter for the Agentic Commerce Protocol (ACP), a REST commerce layer co-authored by OpenAI and Stripe with deployments live at Etsy, and rolling out across Shopify merchants including Glossier, Vuori, and Spanx. The protocol lets buyer agents (ChatGPT, Claude tools, custom orchestrators) submit a cart and settle payment against any ACP-conformant merchant endpoint. This package provides the Zod schemas and pure handler functions for the two ACP endpoints; the actual Next.js route handlers and settlement dependencies live in apps/web. This package is a wire-format adapter, not the source of truth for the ACP spec. When ACP publishes a new dated release that changes wire shape, the version literal is bumped, both route handlers are updated, and the merchant integration tests are re-run. The current pinned version is echoed on every response via the X-Acp-Version header so SDK consumers can detect what variant they are talking to.

Install

npmjs.com/package/@glideco/acp-merchant

Why strict parsing matters

ACP’s reference clients (Etsy’s buyer-agent SDK, Shopify Sidekick) produce largely valid payloads, but third-party agents regularly emit lowercase currency strings, signed amounts on positive-only fields, and ids containing URL-reserved characters. Those errors surface silently downstream in Stripe SPT cache lookups and tax exporters that key on literal strings. The v2026-04-17.1 strictness bump closes those gaps: ISO 4217 uppercase enforced via regex on all currency fields, non-negative amounts required on unitPrice / subtotal / total / shipping / tax, and URL-safe ids on carts and line items.

Spec version

Pinned to ACP 2026-04-17.1 — exported as ACP_SPEC_VERSION. The .1 Glide suffix marks a parser-only tightening: the upstream ACP wire spec at v2026-04-17 is unchanged, but our parser now rejects what the spec says is invalid but previously accepted silently.

API surface

Wiring the /agentic_checkout route

Cart validation

Always recompute and validate cart totals server-side before minting a payment intent:

Error codes

Common pitfalls

Discount polarity. discount keeps acpMoneySchema (allows negative amounts) because the spec represents discounts as negative values. All other money fields use acpMoneyPositiveSchema — a negative unitPrice produces a 400. Idempotency key location. The ACP spec mandates Idempotency-Key as an HTTP header (Stripe-inherited). Both route handlers accept a body field as fallback for legacy clients, but the header takes precedence when both are present. Cart repricing. The buyer agent constructs the cart; the merchant must reprice it server-side using recomputeCartSubtotal before charging. A buyer agent that inflates subtotal to reduce the charged amount is stopped here.

Reading list