Guide
ACP: testing, certification and monitoring
What to check before an agent platform tests your shop's ACP integration, what is known about certification, how to watch it once it runs, and what to do when a product stops showing. The setup steps come first, in ACP. Facts about outside services were checked on 2026-11-15; links are given so you can check them again.
Test before anyone else does
1. The feed, at build time
Build with check_acp: strict (or ssg --check-acp=strict) so a broken row
fails the build instead of quietly leaving the file. Then read the file the
build wrote:
1ssg --check-acp=strict
2wc -l output/acp/products.jsonl # one line per product
3head -n 1 output/acp/products.jsonl # item_id, price "24.00 EUR", seller fields
Compare every item_id with the SKUs in the shop panel. A row the platform
shows but the shop does not know is a sale that fails at the last step.
2. The shop's own tests
In a checkout of the ssg repository (Node 23.6 or newer, no npm install):
1node --import ./workers/ecommerce/test/resolve.mjs --test \
2 'workers/ecommerce/test/acp-*.test.ts'
They run the real handlers on fakes: SQLite standing in for D1, and a Stripe
and a platform receiver written from the published documents
(workers/ecommerce/test/acp-helpers.ts). They prove the code does what the
specification says as we read it. They prove nothing about a live platform.
3. Your own shop, with Stripe in test mode
Run the built site locally with the shop's Functions
(npx wrangler pages dev output), with a .dev.vars holding a Stripe
test key and test values for the ACP settings:
1SHOP_ACP_ENABLED="true"
2SHOP_ACP_API_KEY="local-test-key"
3SHOP_ACP_MERCHANT_ID="profile_test"
4STRIPE_SECRET_KEY="sk_test_..."
Create a session as an agent would. Every call needs the bearer token and
API-Version; every POST an Idempotency-Key:
1curl -s http://localhost:8788/api/shop/acp/checkout_sessions \
2 -H 'Authorization: Bearer local-test-key' -H 'API-Version: 2026-04-17' \
3 -H 'Idempotency-Key: test-1' -H 'Content-Type: application/json' \
4 -d '{"line_items":[{"id":"EBOOK-SHOP","quantity":1}],
5 "buyer":{"email":"[email protected]"},
6 "fulfillment_details":{"address":{"country":"PL"}}}'
The answer is 201 with status: "ready_for_payment", the shop's own price
and tax, or messages[] saying what is missing. Stripe's sandbox can grant
your account a Shared Payment Token without any agent
(Stripe, "Generate an SPT in a sandbox"):
POST /v1/test_helpers/shared_payment/granted_tokens with a test payment
method and usage_limits for the currency and the session's total in minor
units. Complete the session with that token:
1curl -s http://localhost:8788/api/shop/acp/checkout_sessions/<id>/complete \
2 -H 'Authorization: Bearer local-test-key' -H 'API-Version: 2026-04-17' \
3 -H 'Idempotency-Key: test-2' -H 'Content-Type: application/json' \
4 -d '{"payment_data":{"handler_id":"card_tokenized",
5 "instrument":{"type":"card","credential":{"type":"spt","token":"spt_..."}}}}'
The order then appears in the panel with an ACP badge, and the buyer gets
the download email if mail is configured. Send the same complete again with
the same key: the answer is replayed with Idempotent-Replayed: true and
Stripe is not called twice.
This step was not run while writing this guide: there was no wrangler
and no Stripe account on the machine. The commands follow the code
(functions/api/shop/_acp-*.ts) and Stripe's page; report anything that
does not match.
What certification checks
What we could find on 2026-11-15:
- OpenAI's public commerce pages describe no certification process for merchants: not for feeds, not for checkout. They say checkout needs "a separately enabled integration" and do not say how it is enabled. Ask the platform.
- The protocol's site says each platform runs its own process.
- The protocol itself has a conformance checklist (§10 of
rfcs/rfc.agentic_checkout.md). It is a list to check yourself, not a test anyone runs for you. How the shop stands against it:
| Checklist item | The shop |
|---|---|
HTTPS, JSON, API-Version |
JSON and API-Version are enforced; HTTPS is your deployment's. The checklist names 2026-01-15, which the shop does not accept (it takes 2026-04-17, 2026-01-30, 2026-01-16) |
| Authoritative cart state on every response | yes, priced by the storefront's code |
| Integer minor units | yes |
| Create, update, retrieve, complete, cancel | yes |
Idempotency-Key on every POST, 400/422/409 |
yes |
Flat errors type/code/message/param? |
yes |
| Verifies auth; signs/verifies requests | bearer always; request signatures when SHOP_ACP_SIGNING_SECRET is set |
| Order webhooks | order_create on completion; order_update when Stripe's webhook confirms a refund |
fulfillment_details, selected_fulfillment_options[] |
yes; the only option is digital |
If a platform runs its own tests, expect it to need a test product it can buy, your test-mode keys, and the order-events receiver it gave you.
Monitoring
- Every build: the
check_acplines and the item count. Withstrictin CI a broken row, or a feed with no rows at all, stops the deploy. - The feed push:
npx wrangler tailinacp-feed-push/shows one JSON line per run (outcome,status,bytes,ms, the two hosts). A run that did not push is marked failed in the Cloudflare dashboard. Outcomes:pushed,not_configured,fetch_failed,too_large,empty_feed,push_failed,timeout. - The shop panel: orders filter by channel (ACP); failing order events
stay in the outbox list with their error; an exception inside an ACP call
is written to the audit log as
acp.error. - The platform's own reports (for OpenAI, the upload review in Business Hub): the only place that says what it rejected.
A product disappeared: checklist
Work down the list; most causes are at the top.
- The build left it out. Search the build log for its SKU. A missing field or a bare price drops the row.
- It is not in the published file.
curl -s https://<your-site>/acp/products.jsonl | grep '"EBOOK-SHOP"'. No hit after a good build: the deploy did not finish, or a cache serves an old copy. - The platform did not receive it. Hosted URL: check the platform's last
fetch. Push:
wrangler tail, look for anything butpushed. - The id changed. A new SKU, or a page with no SKU whose URL (used as the id) changed with its slug. To the platform that is a new product.
- The row says no.
availabilityout_of_stock, oris_eligible_search: falseon the page or the feed. - The platform rejected it. Read its upload report. OpenAI's schema also says "Eligibility does not guarantee display".
- It shows but cannot be bought. The shop decides at checkout: the
product must exist under that SKU, be active, be digital, and have a price
in the session's currency, and the buyer's country must be in your tax
table. Each failure is a message on the session (
not_found,out_of_stock,invalid,region_restricted). - Every ACP call fails. 404:
SHOP_ACP_ENABLEDis not exactly"true". 503: the API key, the Stripe key or the merchant id is missing. 401: the key was rotated on one side only, or a required signature is late or wrong. 429: the agent budget for that credential is spent; it answers withRetry-After.
Security, as the code implements it
- Who may call:
Authorization: Bearercompared withSHOP_ACP_API_KEYin constant time, on every call. - Signed requests (only with
SHOP_ACP_SIGNING_SECRET): HMAC-SHA256 over<Timestamp>.<body>, and aTimestampmore than 300 seconds from the shop's clock is refused as a replay. The specification leaves the algorithm to the seller, so agree it with the platform or leave the secret unset. - Order events you send:
Merchant-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">withSHOP_ACP_WEBHOOK_SECRET, delivered with retries. The secret is read at delivery and never stored in the queue. - Idempotency: the same key and body replays the stored answer; another
body is
422 idempotency_conflict; a key still running is409withRetry-After; 5xx answers are not stored. A key is honoured for 24 hours (the protocol's minimum); after that the same key is a new request, and the rows are deleted after 7 days. The Stripe charge carries its own idempotency key built from the session and the token, so a retried completion never charges twice. - Price: an agent's
unit_amountis compared, never charged. A total that moved before completion sends the session back with a warning.
What was not tried against the real thing
- No live platform has called the checkout, and no feed has been uploaded to one by us.
- No live or test Stripe account was used; Stripe was a fake written from its documentation.
- Step 3 above was written from the code and Stripe's page, not run.
- No certification or platform test was taken, because none is published.