Implementing an Agentic Checkout API on Your Commerce Stack

Any honest agentic checkout API implementation guide starts with a short inventory: five endpoints, one stream of order webhooks, and a payment token you never mint yourself. The routes are the easy part. The work sits in what the specification hands back to you, which is pricing, tax, shipping, fraud decisions, order state and measurement, all on the commerce stack you already run. This is the build as we would sequence it for a headless store, drawn from OpenAI's developer documentation and the Agentic Commerce Protocol (ACP) repository as we read them on October 7, 2026. The two disagree in at least six places. OpenAI also says it is moving away from a standalone Instant Checkout experience in ChatGPT, so read the last section before you scope the build.

Where is the API reference, and which version should you pin?

The Agentic Commerce Protocol API reference lives in two places that have drifted apart. OpenAI publishes an Agentic Checkout Spec whose example requests carry API-Version: 2025-09-12. The Agentic Commerce Protocol repository names OpenAI and Stripe as founding maintainers, marks the project as beta under an Apache 2.0 license, and holds dated snapshots from 2025-09-29 to 2026-04-17 (labeled the latest stable) plus an unreleased folder. The checkout RFC that the Agentic Commerce Protocol project keeps on its main branch is headed Status Draft, Version 2026-01-16.

Pin the version in code. Read API-Version on every request, answer untested versions with the RFC's unsupported_api_version error, and have the agent platform tell you which snapshot it sends before anyone writes the adapter. Serving TLS 1.3 satisfies both documents; the webhook names and status codes have to follow the caller's version.

Which endpoints does the checkout spec ask you to implement?

The Agentic Commerce Protocol (ACP) checkout API spec asks a merchant to implement five endpoints on one resource:

• POST /checkout_sessions creates a session from the requested items and returns 201.
• POST /checkout_sessions/{checkout_session_id} updates the items, the address or the chosen fulfillment option.
• GET /checkout_sessions/{checkout_session_id} returns the current state, or 404.
• POST /checkout_sessions/{checkout_session_id}/complete accepts payment_data and creates the order.
• POST /checkout_sessions/{checkout_session_id}/cancel cancels the session, or returns 405 when it is already completed or canceled.

Every response carries the whole session. OpenAI's spec says "each response returns the full cart state for display and validation", meaning line items, totals, fulfillment options, messages, links to your terms and privacy policy, and a status. That status is the state machine the agent reads: not_ready_for_payment until you have what you need, ready_for_payment once you do, then completed or canceled.

Authentication is a bearer token in the Authorization header. The RFC requires API-Version on every request and Idempotency-Key on every POST, and recommends a Signature with a Timestamp, plus Request-Id. Keep the raw request body for the signature check, since a JSON body parser drops the bytes, and write Request-Id to every log line.

Where does the adapter sit in your commerce architecture?

Agentic checkout architecture on an existing commerce stack is an adapter: a thin service that translates session calls into the cart, pricing, tax, inventory, payment and order services you already run. The RFC is plain about ownership: "The merchant remains the system of record for all orders, payments, taxes, and compliance." The agent platform renders the interface and collects the buyer's details. You compute, decide and fulfill.

Payment follows the same split. Under the Delegated Payment Spec from OpenAI, the platform calls your payment provider at POST /agentic_commerce/delegate_payment with the buyer's card and an allowance: a max_amount, a currency, an expiry and the checkout_session_id, with one_time as the only listed reason. The provider returns a vault token, which arrives in payment_data on your complete call for you to charge through your own account. On Stripe the credential is a shared payment token, passed to a PaymentIntent as payment_method_data[shared_payment_granted_token]; its samples call a preview API version, 2026-09-30.preview.

Why idempotency takes longer than the routes

Any Agentic Commerce Protocol implementation guide for the checkout API should spend more words on idempotency than on routing, because retries are where double charges come from. The RFC's rules are specific. Scope each key to the authenticated caller plus the endpoint path. Compare request bodies by semantic JSON equality and ignore headers. On a replay with an identical body, return the original response and status and do nothing else: "Servers MUST NOT re-execute side effects (e.g., payment capture, inventory reservation) on replay." Keep each key and its response for at least 24 hours, and never cache a 5xx against a key.

Three errors complete the contract: 400 with idempotency_key_required when the header is missing, 422 with idempotency_conflict when a key returns with a different body, and 409 with idempotency_in_flight while the first request is still running. The RFC's own change log still files this rewrite under "Unreleased", yet the 2026-04-17 release notes in the Agentic Commerce Protocol repository list the same three codes among that release's changes. OpenAI's launch checklist still expects idempotency_conflict with HTTP 409, so branch on API-Version. Ordering matters as much as the codes: insert the key as in flight before you call the payment provider, and send the provider an idempotency key of your own if it supports one, so a retry after a crash gets the original charge back.

What does this look like on a headless Node backend?

An agentic checkout on headless commerce with a Node backend comes down to a router and three functions a headless store tends to have already. The sketch is a hypothetical reference pattern with invented module names, and it leaves out error mapping, 3D Secure, and the retrieve and cancel routes.

// Hypothetical sketch: an Express adapter over your own services.
import express from 'express';
import { verifyCaller, idempotent } from './guards.js'; // bearer, version, signature, key store
import { priceCart } from './pricing.js';               // live prices, tax, shipping, stock
import { chargeAndCreateOrder } from './orders.js';     // your PSP and your OMS

const app = express();
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
app.use(verifyCaller);

app.post('/checkout_sessions', idempotent, async (req, res) => {
  const { session } = await priceCart(null, req.body);
  res.status(201).json(session);
});

app.post('/checkout_sessions/:id', idempotent, async (req, res) => {
  const { session } = await priceCart(req.params.id, req.body);
  res.json(session);
});

app.post('/checkout_sessions/:id/complete', idempotent, async (req, res) => {
  const { session, totalMoved } = await priceCart(req.params.id, {});
  if (totalMoved || session.status !== 'ready_for_payment') return res.json(session);
  const order = await chargeAndCreateOrder(session, req.body.payment_data);
  res.json({ ...session, status: 'completed', order });
});

Every route, complete included, calls one priceCart function, so the adapter never holds a price of its own, and the same pricing core can serve a second protocol later. Teams that already run a headless storefront tend to have that function behind an internal API, which leaves the adapter as mostly translation.

How is the price verified before the buyer pays?

Agentic Commerce Protocol real-time price verification before checkout is the session response itself; we found no separate price-check endpoint in either reference. The feed puts a product into the conversation and can lag your catalog, so the session has to be current. On create, on every update and again on complete, recompute prices, discounts, tax and fulfillment from live data and return totals as integers in minor units. OpenAI's spec gives the arithmetic: a line item's total is its base amount minus discount plus tax, and the order total is the items' base amount minus item discounts and order discounts, plus fulfillment, tax and fees.

When a number has moved since the last call, say so in messages (the documented error codes include out_of_stock) and return the updated session instead of charging. The payment token adds a ceiling: Stripe's page says "The agent sets the maximum amount to match the total amount of the transaction." We read that as zero headroom, so a total that rises between the last update and complete is a decline you caused. Keeping feed, product page and checkout in agreement matters upstream too, for the reason we set out in LLMs cite the brand that agrees with itself.

How does order state get back from the OMS?

Order-state sync runs outward, from your OMS to the agent platform. OpenAI's spec puts it this way: "The merchant sends OpenAI webhook events on order creation and update events." The events carry an HMAC signature made with a key OpenAI provides, and the order statuses are created, manual_review, confirmed, canceled, shipped and fulfilled. Your OMS almost certainly has more states than those six, so write the mapping down with whoever owns fulfillment. Store the checkout_session_id on the OMS order, publish status changes through an outbox so no webhook goes out for a transaction that rolled back, and retry with the same payload. The order also needs a permalink_url where, in the spec's words, customers can "provide at most their email address to view order details". A link that demands a login fails that description.

What the specs leave to you

Tax and shipping edge cases

The launch checklist that OpenAI publishes has you create a session with and without a shipping address and confirm that shipping options and tax totals come back once a valid address is provided. Until then, return no tax figure and keep the status at not_ready_for_payment. Split shipments need a decision per version: the same guide says "Today, the protocol models a single shipping address and one selected shipping option per checkout session", while the RFC's January 2026 revision introduced a selected_fulfillment_options[] array that maps selections to items. Put deposits and regulatory charges in a fee total, and add a unit test that asserts the totals arithmetic on every response, because tax rounded per line seldom sums to tax rounded per order by accident.

Fraud rules

The calls arrive server to server, so rules keyed to device fingerprint, browser or shopper IP have nothing to read unless the agent forwards those signals. We found no field for them in OpenAI's checkout spec, while the 2026-04-17 OpenAPI file in the Agentic Commerce Protocol repository defines an optional risk_signals object on the complete request with the buyer's IP address, user agent and device fingerprint. What you do get is the buyer and fulfillment details in the session, the order value, and whatever your provider exposes from the risk_signals in the delegated payment request, each with a type, a score and an action of blocked, manual_review or authorized. The consequences stay with you: asked who handles chargebacks and refunds, OpenAI's production FAQ answers "The merchant does." Use the manual_review order status for the grey band instead of declining outright.

Testing

OpenAI's checklist sets the floor: repriced totals when the shipping option changes, a completed order from a tokenized payment, both order webhooks with a valid HMAC signature, the missing, out_of_stock and payment_declined error cases, and repeated create and complete calls under one key. On Stripe, a test helper at test_helpers/shared_payment/granted_tokens grants a token with a currency, maximum amount and expiry you choose. Add cases of your own: a price change between the last update and complete, a tax service timeout mid-session, two complete calls racing on one session, and schema validation against the OpenAPI file for the version you pinned.

Analytics instrumentation

No page loads, so no tag fires and no cookie or URL campaign parameter exists. The nearest substitute is the optional affiliate_attribution object in the 2026-04-17 OpenAPI file, which lets an agent pass a provider, a publisher id and a campaign_id. Emit server-side events from the adapter when a session is created, when its status changes, and when it completes or cancels, each carrying the session id, the Request-Id, the authenticated caller as the channel, and any error code. That gives you a funnel (created, reached ready_for_payment, completed) with decline and stock-out rates to set beside web checkout. It says nothing about the step before, which is whether the assistant recommended you at all. AI share of voice measures that step, with limits we cover in where prompt-based visibility tracking breaks, and our AI visibility checker is a further resource for it.

What has changed for merchants since 2025?

Merchants who read about agentic commerce, OpenAI Instant Checkout and the Agentic Commerce Protocol in 2025 were reading about an early version of the protocol. The repository's first snapshot is dated 2025-09-29, and four more had followed by 2026-04-17. Access is a separate matter. The Agentic Commerce Protocol site says "Any AI agent can call an ACP-enabled checkout", and also that each AI platform will manage its own process for how businesses can participate. On the get-started page from OpenAI, the availability statement we found concerns feeds: "Onboarding product feeds in ChatGPT is currently available to approved partners." We found no statement on the developer pages we read about which merchants can take in-chat checkout today. The merchant page from OpenAI is blunter: the company is "moving away from a standalone Instant Checkout experience in ChatGPT", and "purchases are completed on merchant-owned websites or apps". A March 24, 2026 post from OpenAI gives the reason: the initial version of Instant Checkout "did not offer the level of flexibility that we aspire to provide", so merchants may use their own checkout while OpenAI focuses on product discovery.

So before you fund the build, get written confirmation from an agent platform that it will call these endpoints for your store, and keep the protocol at the edge of the adapter so the pricing core survives a version change. The work that pays under any protocol is being the product the assistant picks, which is the subject of how to get cited by ChatGPT and of our AI search optimization practice.

Sources

• OpenAI, Agentic Checkout Spec
• OpenAI, Delegated Payment Spec
• OpenAI, Agentic commerce in production
• OpenAI, Get started
• Agentic Commerce Protocol, repository README
• Agentic Commerce Protocol, agentic checkout RFC
• Agentic Commerce Protocol, project site
• Stripe, Shared payment tokens
• OpenAI, Power product discovery in ChatGPT (merchant page)
• OpenAI, Powering Product Discovery in ChatGPT, March 24, 2026
• Agentic Commerce Protocol, 2026-04-17 changelog
• Agentic Commerce Protocol, 2026-04-17 checkout OpenAPI file