Guide
Selling through Google's agents with UCP
The Universal Commerce Protocol (ucp.dev, repository
github.com/Universal-Commerce-Protocol/ucp)
is the protocol Google uses to let a shopper buy in AI Mode in Google Search
and in the Gemini app, paying with Google Pay. This guide is for a site owner
running the ssg shop (workers/ecommerce). It is a separate protocol from
ACP, with its own steps; ACP has its own guide: ACP.
ssg sells nothing and is not part of Google's programme. The Merchant Center account, Google's approval, the payment accounts and their terms are yours. Facts about Google's process below were read on 2026-11-15; each has a link so you can check it again.
The versions involved
- The shop implements UCP release
2026-04-08(functions/api/shop/_ucp-http.ts). The protocol's latest release on 2026-11-15 wasv2026-08-25; Google's native checkout guide covers2026-04-08and2026-01-23. - Google Pay payment handler
2026-01-23; Google Pay tokens are processed by Stripe, the only processor the code implements.
What ssg and the shop do, and what they do not
| Part | Done by |
|---|---|
UCP attributes in the Merchant feed (native_commerce, variants, notices, merchant_item_id) |
ssg, at build time: ucp: on a google-merchant feed |
| Checking them | ssg: check_ucp: warn or strict |
| Getting the feed into Merchant Center | you: Merchant Center fetches the URL on the schedule you set |
Business profile at /.well-known/ucp |
the shop worker |
| Checkout endpoints, Google Pay through Stripe, signed order events | the shop worker, off by default |
| Merchant Center settings, waitlist, Google's approval | you |
The shop sells digital products only, with no shipping, no discounts, no cart transfer and no identity linking.
Before you start (Google's requirements)
From Google's Prepare your Merchant Center account (page dated 2026-10-29) and UCP implementation overview:
- A Merchant Center account in good standing, with products approved for free listings.
- A return policy in Merchant Center with return cost, return window and a link to the full policy.
- Customer support information: at least one of a website URL, an email address or a phone number.
- Join the waitlist at support.google.com/merchants/contact/ucp_integration_interest. Google: "Your integration must be approved by Google before you can go live on AI Mode in Google Search and Gemini."
- A Stripe account (for the card processing behind Google Pay) and, for production, a Google Pay merchant id.
Check that your products may be sold this way. Google lists categories that are ineligible for checkout. One of its headings is "Digital goods and services", with services, rentals, virtual items (its examples are in-game goods) and goods that need software installed first. Whether e-books and other downloads fall under it is not stated. Ask Google before you build on it.
Step 1: UCP attributes on the Merchant feed
UCP has no feed format of its own: Google reads checkout eligibility from the
products it already has in Merchant Center. So the attributes go on the
google-merchant feed, switched on with ucp::
1feeds:
2 - path: /merchant.xml
3 format: google-merchant
4 source: shop
5 merchant:
6 brand: Example Press
7 ucp:
8 checkout_eligibility: true # the default once ucp: is present
9check_ucp: strict
Product pages need Product JSON-LD in schema: as for any Merchant feed;
the example in ACP
applies unchanged. Every key and attribute:
CONFIGURATION.
The id the checkout receives is your shop's SKU. Google sends
merchant_item_id when a product has one, otherwise id. ssg writes id
from the page's sku. The shop looks the product up by SKU, so either keep
sku equal to the SKU in the shop panel, or set merchant.merchant_item_id
to it on the page.
ssg writes checkout_eligibility FALSE for what it can see is ineligible:
pre-orders, used or refurbished items, and offers with no returns. For any
other ineligible product set merchant.checkout_eligibility: false on its
page.
check_ucp messages name the source file, feed, item and field. A few:
| Message contains | Meaning |
|---|---|
the row is left out |
a required Merchant attribute or the currency is missing |
written FALSE: Google lists … as ineligible |
ssg overrode checkout eligibility |
is stated by no page |
availability was assumed, and checkout sells what the feed says is in stock |
notice_type / notice_message |
a consumer_notice Google would reject |
variant_option / item_group_title |
a variant Google cannot show as one |
As with ACP, a feed with no rows at all is a finding (since 1.9.10):
warn reports it with the likely cause (no page with schema: Product, or
every product missing a required attribute), strict fails the build, and
with check_ucp off the build prints one line about it.
examples/ebook-shop in the repository declares such a feed, one row per
book.
Add the feed URL to Merchant Center as a data source. Google recommends a supplemental data source for these attributes; ssg puts them in the main feed, so they arrive with the products.
Step 2: switch on the shop's UCP checkout
Route the profile to Functions. In .ssg.yaml, the shop's workers: entry:
1 routes_include:
2 - /api/shop/*
3 - /.well-known/ucp
Make the signing key for order events, an EC P-256 private JWK with a kid
(Node 23.6 or newer; keep the output secret):
1node --input-type=module -e 'const k=await crypto.subtle.generateKey({name:"ECDSA",namedCurve:"P-256"},true,["sign"]);const j=await crypto.subtle.exportKey("jwk",k.privateKey);console.log(JSON.stringify({kty:j.kty,crv:j.crv,x:j.x,y:j.y,d:j.d,kid:"shop-2026-11"}))'
In the shop's wrangler.toml [vars]:
1SHOP_UCP_ENABLED = "true"
2SHOP_UCP_STRIPE_PUBLISHABLE_KEY = "pk_test_…" # public: it is in the profile
3SHOP_UCP_GPAY_ENVIRONMENT = "TEST" # "PRODUCTION" once approved
4# SHOP_UCP_GPAY_MERCHANT_ID = "…" # required with PRODUCTION
5# SHOP_UCP_HANDLER_ID = "gpay" # this shop's id for its Google Pay handler
6SHOP_UCP_WEBHOOK_URL = "https://webhooks.example.com/v1/webhooks/partners/PARTNER_ID/events/order"
Secrets, with npx wrangler pages secret put <NAME>: SHOP_UCP_API_KEY (the
key Google sends in X-API-Key), SHOP_UCP_SIGNING_KEY (the JWK above),
SHOP_UCP_WEBHOOK_API_KEY (sent as X-Goog-Api-Key with order events), and
STRIPE_SECRET_KEY. Google's
order lifecycle page
says it shares a partner id and an API key with you during onboarding; put
the URL without ?key= in SHOP_UCP_WEBHOOK_URL.
With SHOP_UCP_ENABLED unset, /.well-known/ucp and every UCP route are 404.
With it on and something missing (the API key, the Stripe secret key, a
pk_test_/pk_live_ publishable key, a valid signing key, or the Google Pay
merchant id in PRODUCTION) they are 503. Google's
authentication guide
offers an API key, OAuth 2.0 (which it recommends) or mTLS; the shop
implements the API key only — the protocol makes all three optional
("Authentication is optional and depends on business requirements",
checkout-rest.md). mTLS, if Google asks for it, would be a Cloudflare zone
rule in front of the shop, not shop code
(workers/ecommerce/UCP, ambiguity 2).
Route under https://<your-site>/api/shop/ucp |
Operation |
|---|---|
POST /checkout-sessions |
create |
GET /checkout-sessions/{id} |
read |
PUT /checkout-sessions/{id} |
update |
POST /checkout-sessions/{id}/complete |
pay and place the order |
POST /checkout-sessions/{id}/cancel |
cancel |
GET /orders/{id} |
read an order a UCP checkout placed (since 1.9.11) |
The profile at https://<your-site>/.well-known/ucp names this endpoint, the
checkout and order capabilities, the Google Pay handler and the public half
of your signing key. Google finds everything else from it.
Step 3: test, then watch it
Testing before Google does, what Google publishes about its checks, the monitoring, the "my product disappeared" checklist, running the UCP conformance suite (with the shop's test mode, since 1.9.11) and its results, how the code handles security and idempotency, and what was never tried against Google's live systems: UCP-OPERATIONS. Where the specification left room and what the shop's code chose: workers/ecommerce/UCP.