Agentic Commerce Protocol

Let AI agents such as ChatGPT buy from a Scipio 4.0 store: ACP checkout sessions, Stripe Shared Payment Tokens, signed order webhooks and a product feed.

The Agentic Commerce Protocol (ACP) is an open standard from OpenAI and Stripe. It lets an AI agent, for example ChatGPT, buy from a merchant for a person. Scipio 4.0 implements the merchant side of spec version 2026-04-17 in the component applications/acp.

What Scipio supports#

Checkout sessions: create, read, update, complete and cancel.
An MCP binding with the tools create_checkout_session, get_checkout_session, update_checkout_session, complete_checkout_session and cancel_checkout_session.
Pricing with the store cart engine: catalog prices, stock, promotions, discount codes, the shipping options of the store and tax. Amounts are in minor units.
Payment with a Stripe Shared Payment Token (spt_...).
Signed order webhooks and a product feed.
A guest customer for each order. The sales channel is ACP_SALES_CHANNEL.

Setup#

Check enabled=true in applications/acp/config/acp.properties. When it is false, every ACP path answers 404.
Create a token for the login scp-acp-agent (group SCIPIO_ACP_AGENT, permission ACP_CHECKOUT). Run the service createMcpAccessToken with userLoginId=scp-acp-agent.
Set up the payment (see below).
Optional: set webhook.url and webhook.secret.
Serve /.well-known/acp.json on the root host so that agents find the store.

Every setting can also be a SystemProperty (resource acp) or be set per product store with the suffix .<productStoreId>.

Endpoints#

Each store webapp answers ACP. The examples use /shop.

Method	Path	Purpose
GET	`/.well-known/acp.json` and `/shop/.well-known/acp.json`	Discovery, no authentication
POST	`/shop/acp/checkout_sessions`	Create a session
GET, POST	`/shop/acp/checkout_sessions/{id}`	Read or update a session
POST	`/shop/acp/checkout_sessions/{id}/complete`	Pay and create the order
POST	`/shop/acp/checkout_sessions/{id}/cancel`	Cancel a session
POST	`/shop/acp/mcp`	MCP binding
GET	`/shop/acp/feed/products.jsonl`, `/shop/acp/feed/metadata.json`	Product feed

The agent sends Authorization: Bearer <token> and the header API-Version. Every POST needs an Idempotency-Key. A replay returns the first answer with the header Idempotent-Replayed. A request that runs twice at once gives 409 idempotency_in_flight. The same key with another body gives 422 idempotency_conflict. When signature.secret is set, each request also needs Signature and Timestamp.

Payment#

Set payment.handler:

stripe: the Stripe account of the store. Set the secret key in stripe.secretKey or in the environment variable ACP_STRIPE_SECRET_KEY. Scipio records the payment and approves the order.
hub: the Scipio hosted hub. The hub records the payment with its Stripe webhook.
auto: hub when hubcheckout.properties is complete, else stripe.

Webhooks#

Scipio sends order_create and order_update with the full Order object to webhook.url. The header Merchant-Signature: t=<unix>,v1=<hex> holds the HMAC-SHA256 of <t>.<body> with webhook.secret. A failed delivery retries with backoff (job acpDeliverWebhooks). The script tools/acp-webhook-listener.py receives test webhooks.

Product feed#

The daily job acpGenerateFeeds writes products.jsonl (JSON Lines) and metadata.json. Set feed.prodCatalogId when the store has more than one catalog.

Limits#

Stripe is the only payment provider.
3-D Secure interventions are not supported yet. A card that needs 3-D Secure is declined with requires_3ds.
Each order has a guest customer.
Rate limit: 120 requests per minute per token (rateLimit.perMinute).

Test it#

tools/acp-test.sh runs 29 checks against a running server. It passed against a local server with a real Stripe test token. The full guide is docs/AGENTIC-COMMERCE.md in the Scipio repository. For the token model, see Agent security .