Guide
UCP: testing, checks and monitoring
What to check before Google tests your shop's UCP integration, what Google publishes about its checks, how to watch it once it runs, and what to do when a product stops showing. The setup steps come first, in UCP. Facts about Google's process were read on 2026-11-15; each has a link so you can check it again.
Test before Google does
- Build with
check_ucp: strictand openoutput/merchant.xml. A feed with no rows at all fails the build too (since 1.9.10). - The shop's tests, from a checkout of the ssg repository:
node --import ./workers/ecommerce/test/resolve.mjs --test 'workers/ecommerce/test/ucp-*.test.ts'. They run the real handlers against fakes of Google's platform, Stripe and an order-webhook receiver that verifies the signatures. They passed on 2026-11-15. They prove nothing about Google's live systems. - The profile:
curl -s https://<your-site>/.well-known/ucpmust answer 200 with your endpoint and asigning_keysentry withoutd. - The UCP conformance suite, which Google's native checkout guide points to. How to run it and what it says about the shop: the conformance suite below.
The conformance suite
github.com/Universal-Commerce-Protocol/conformance
was run against the shop on 2026-11-15 (commit 0642adf of 2026-11-13,
ucp-sdk 0.4.6, protocol 2026-04-08, its flower-shop fixtures with the
SKUs seeded as downloads) — locally: the shop's real Functions on the test
fakes, Stripe faked. Nothing reached Google or Stripe.
What a run needs from the shop (since 1.9.11), on a test deployment only:
1SHOP_UCP_TEST_MODE = "true" # refused (503) next to sk_live_/pk_live_ or PRODUCTION
2SHOP_UCP_HANDLER_ID = "google_pay" # only for the suite's `--platform=google` handler check
3SHOP_UCP_WEBHOOK_URL = "http://localhost:8284/webhooks/partners/test_partner/events/order"
plus the secret SHOP_UCP_SIMULATION_SECRET (pass the same value as
--simulation_secret) and /testing/* in routes_include. Test mode
accepts the suite's http://localhost agent profile and receiver, its test
payment handler (success_token delivers the product without payment)
and /testing/simulate-shipping/{id}
(workers/ecommerce/UCP).
The suite sends no X-API-Key and has no option for one, so put a proxy
in front of the shop that adds it; the API key is never switched off.
Results (83 tests; 28 skipped because the shop does not advertise discount, fulfillment, buyer consent or AP2):
| Run | Passed | Failed |
|---|---|---|
| before 1.9.11, no API key (as the suite sends) | 3 | 52 (401) |
| before 1.9.11, key added by the proxy | 3 | 52 (400 invalid_profile_url: the agent profile is http) |
| 1.9.11, key added, test mode off | 3 | 52 — unchanged for a shop not in test mode |
| 1.9.11, key added, test mode on | 13 | 42 |
| the same, suite patched locally to skip fulfillment when the server does not advertise it | 29 | 26 |
| … and to send a buyer email, which a download needs | 40 | 15 |
The 42 failures of the unpatched suite come from one helper: before every
completion it reads fulfillment.methods[0] from the session (41 tests
fail with KeyError: 'fulfillment'), although fulfillment is an optional
extension that "applies only to items requiring physical delivery"
(fulfillment.md). A downloads-only shop cannot pass those tests without
inventing a shipping method. The last one is test_version_negotiation,
which sends UCP-Agent: profile="...": not a URL, so 400 invalid_profile_url, as overview.md lists it.
The 15 left after both local patches, and why they stay:
| Tests | Why |
|---|---|
test_order_update, test_order_adjustments, test_invalid_adjustment_status, test_malformed_adjustment_payload |
they PUT /orders/{id}; the protocol defines only Get Order |
test_order_fulfillment_retrieval, test_ready_for_complete_when_nothing_is_outstanding, test_update_checkout, test_webhook_order_address_known_customer, test_webhook_order_address_new_address |
they need shipping options and fulfillment fields without checking the capability |
test_card_credential_payment |
it pays with a raw card number; the shop never accepts one |
test_complete_is_idempotent |
completing a completed session answers 200 with the order (a safe replay); the suite wants a 4xx. The protocol only says a completed session is immutable |
test_delivery_carries_standard_webhook_headers |
Webhook-Timestamp is RFC 3339, as every Google example shows; order.md's table says unix (ambiguity 6 in workers/ecommerce/UCP.md) |
test_transient_failure_retries_preserve_event_identity |
a failed event is retried by the outbox with backoff (minutes), not within the suite's few seconds |
test_update_inventory_validation |
quantity 10001 is a 400 invalid_request ({code, content}, overview.md's error shape); the suite wants detail, an out-of-stock message or a clamped quantity |
test_version_negotiation |
as above |
--platform=google also fails: Google's profile in the suite requires the
fulfillment capability (with SHOP_UCP_HANDLER_ID = "google_pay" that is
the only finding left). Whether Google's approval uses this profile is not
stated.
What Google checks
- Approval before going live (UCP). Google's pages read on 2026-11-15 do not publish the criteria.
- Service levels (native checkout overview): at least 95% availability for create, update and complete; latency p50/p95 at most 1 s/4 s for create, 1 s/5 s for update, 6 s/10 s for complete, over a rolling 24 hours. Nothing in ssg measures these.
- Conformance: the suite above has a
googlecertification profile. Whether Google's approval runs it is not stated.
Monitoring, and a product that disappeared
- Merchant Center's product diagnostics say why a product is not shown or not eligible. ssg cannot see them.
- In the shop panel: orders filter by channel (UCP); order events that keep failing stay in the outbox list; refunds are sent to Google as order updates.
- If a product vanished: check the build log for its SKU; check the
published
merchant.xmlcontains it withcheckout_eligibilityTRUE; check ssg did not writeFALSE(pre-order, used, refurbished, no returns); check thatidormerchant_item_idstill equals the shop's SKU; check the product is active, digital and priced in the shop; then Merchant Center's diagnostics. - Every UCP call failing: 404 = not switched on; 503 = a setting is missing
(UCP.md, step 2); 401 =
the API key differs; 400
invalid_profile_url= the caller sent noUCP-Agent: profile="https://…".
Security, as the code implements it
X-API-Keycompared withSHOP_UCP_API_KEYin constant time; every call must carryUCP-Agentwith anhttpsprofile URL (checked for shape, not fetched;httptoo in test mode only). OAuth 2.0 and mTLS are options in the protocol, not requirements, and are not implemented; mTLS would be a Cloudflare zone rule in front of the Worker (workers/ecommerce/UCP, ambiguity 2).- Test mode (
SHOP_UCP_TEST_MODE) is off by default and refused (503 on every UCP route) next to a live Stripe key or Google PayPRODUCTION. - Order events are signed as RFC 9421 HTTP Message Signatures with ES256,
covering method, host, path,
UCP-Agent,Idempotency-Key,Content-DigestandContent-Type, with acreatedtime; retries reuse the sameWebhook-IdandIdempotency-Key. Idempotency-Keyis optional; when sent, the same body replays the stored answer, another body is409 idempotency_conflict, and a key is honoured for 48 hours (rows are deleted after 7 days). The Stripe charge has its own idempotency key per session and token, so a retried completion never charges twice.- A decline or a Stripe failure on complete answers 200 with the session and a message, as Google asks, so the buyer can try another card.
Every choice the code made where the specification left room is listed in workers/ecommerce/UCP.
What was not tried against the real thing
- No Google system has called the shop; no Merchant Center account was used.
- No Google Pay token was ever decrypted or charged; Stripe was a fake.
- The conformance suite was run locally against the shop's Functions on fakes, not against a deployment.
- Microsoft Merchant Center also asks for a "UCP-ready" feed with different attribute names; whether it reads Google's names is not confirmed (CONFIGURATION).