Agentic commerce

AI assistants now shop for people. Google AI Mode and Gemini can put a product in a basket and pay with Google Pay without the buyer ever opening your site. ChatGPT recommends products from the feeds merchants send it. And any MCP client (Claude, Cursor, a ChatGPT connector) can search a store that runs an MCP server. This page explains how KahunaCart takes part, what an agent can and cannot do, and how to set up each platform.

This is the shopper's side. To run your own store from an AI assistant, see Run the store from an AI assistant.

Before you begin

• KahunaCart 1.3.0 or later.
• The store served over HTTPS. For Google's native checkout, Grav must also sit at the root of its domain, because /.well-known/ucp has to answer at the host root.
• The job worker running, because feeds are built and order webhooks are sent in the background. bin/plugin kahunacart status says whether it is.
• For native Google Pay checkout, the Stripe provider 1.2.4 or later.

The four parts

The parts build on each other. Structured data and feeds let agents find products. The MCP endpoint and UCP let them buy. You can run the first two on their own, and a store that only wants to be found in ChatGPT needs nothing but the OpenAI feed.

What an agent can do

• Search the catalog and read products, variants, prices, pictures, options and availability, exactly as a guest sees them.
• Read your policies: terms, privacy, returns, shipping and the FAQ, from the pages you link.
• Build a cart and hand the buyer to your own checkout through a continue_url, where every payment provider you run works as usual.
• Create a checkout, set the buyer's address and a shipping method, apply a coupon code, and see your real totals, with tax and shipping worked out by the same calculator the storefront uses.
• Complete the checkout with Google Pay, when your store has a provider that takes agent payments. The order is placed and paid, and gets the same confirmation email, stock movement and history as any other order.
• Read back an order it placed, and hear about shipping, delivery, cancellations and refunds through signed order webhooks.
• Choose click and collect through UCP when eligible collection points are offered. Free collection is free in every currency. A charged point needs an amount in the checkout’s currency. See UCP checkout.

What an agent cannot do

• See anything a logged-out visitor cannot. Drafts, scheduled products, unlisted products and anything held back for a customer group are invisible, lookup by id included. A guest is placed in the store's default group, so a product restricted to groups that include the default group is open to agents. A members-only product restricted to other groups is never offered: not in the feeds, the MCP and UCP catalog tools, carts or checkouts. Stock quantities, costs, internal custom fields and admin data are never sent.
• Sign in. There is no identity linking, so an agent never acts as one of your customer accounts. Anything that depends on who is signed in (a group's price list or discount, store credit, a saved address) does not apply to agent checkouts.
• Set a price. Prices, tax, shipping and totals come from the store. Anything the agent sends as a price is ignored.
• Pay natively for everything. Some products are never checked out by an agent, whatever you set: a required add-on option or buy-button field, pay what you want, a deposit, a prerequisite, a members-only product, a subscription, a service, a backorder and a final sale. Digital products and used or refurbished ones are left out automatically, and you can allow them per product. Those carts still work: the buyer finishes on your checkout through the continue_url. See Agent checkout.
• Pay any other way. Google Pay through a provider with the agent_payments capability is the only native payment. Everything else is the continue_url handoff.
• Touch a shopper's own cart. The MCP and UCP endpoints never read or write the browser session, so an agent's cart and a shopper's cart never meet until the buyer follows a continue_url.
• Send card numbers. A card number anywhere in a request is refused, as on every other KahunaCart route. The Google Pay token reaches the provider and is never stored, logged or echoed.

No customer record is created for an agent session until the checkout completes. Browsing, carts and abandoned checkouts leave no customer behind, and an agent's basket is never sent a cart-recovery email.

Agent orders carry the agent attribution, with the platform as the source and the protocol as the medium, so they show up in reports and the order list like any other traffic source. A basket an agent started and a person finished through the continue_url still counts as an agent sale. See Analytics → Where an order came from.

Set up the basics

Whatever platform you are setting up for, start under Settings → Agentic Commerce in the store admin. Every part reads these settings; each key is in Configuration → Agentic commerce.

1. Turn agentic commerce on. Switch on the Agentic Commerce toggle at the top of the tab (agentic.enabled: true). Nothing else on this page takes effect until it is on.
2. Fill in Seller. The store name (empty uses the invoice store name, then the site title), a default brand for products that set none, a logo, and a support email and phone.
3. Fill in Store policies. Links to your terms, privacy, returns, shipping and FAQ pages. Site-relative links such as /terms are fine. UCP will not start without terms and privacy, and no return policy is published anywhere until policies.refund_url is set.
4. Set Returns. Whether you accept returns, the window, the countries, the method and who pays.
5. Write the Shipping summary. One row per country with a rate, an optional free-over threshold, and handling and transit days. Structured data and feeds need a price with no address to quote it for, which your shipping zones cannot give, so this is written by hand. Leave it empty to publish no shipping details.
6. Add product data. Give products a brand, GTIN or MPN, a condition and a Google product category where you have them, in the product editor's Product Data fieldset or through the CSV importer. Nothing is required, and a product with none is still listed.
7. Click Save.

Product pages now carry the extra structured data. The feeds, the MCP endpoint and UCP each still need their own switch.

Set up Google AI Mode and Gemini

Google finds products through Merchant Center and buys them through UCP.

1. Serve the store over HTTPS at the root of its domain. A Grav installed in a subdirectory cannot take part in UCP. Set system.custom_base_url when the site sits behind a proxy.
2. Switch the feeds on (feeds.enabled) and register https://your-store.example/shop/feeds/google.tsv in Merchant Center as a scheduled fetch. See Product feeds → Set up Google Merchant Center.
3. Install and configure the Stripe provider, if you want native checkout rather than the handoff. Stripe is the first provider with the agent_payments capability.
4. Switch UCP on (ucp.enabled). The worker makes a signing key on its next tick, or run bin/plugin kahunacart agentic:keys.
5. Set up Google Pay. Put your Google Pay and Wallet Console merchant id in ucp.google_pay.merchant_id, and leave ucp.google_pay.environment on TEST while you try it. See UCP checkout → Google Pay with Stripe.
6. Check readiness. The Agentic commerce screen in the store admin and bin/plugin kahunacart check both list everything still standing between the store and a working profile. /.well-known/ucp answers 404 until the list is empty.
7. Onboard in Merchant Center. Give Google your profile URL. When Google issues an API key and an order webhook URL, put them in ucp.google.api_key and ucp.google.order_webhook_url. Both are stored encrypted.
8. Go live. Once Google approves the integration, set ucp.google_pay.environment to PRODUCTION and put Stripe in live mode. The doctor warns while Google Pay is in TEST beside a live Stripe account.

While UCP is on, the Google feeds carry the native_commerce column: TRUE for each variant an agent may check out and FALSE for the rest. Switch UCP off and the supplemental google-checkout.tsv writes FALSE on every row from its next build, which tells Google to stop offering checkout. Press Rebuild feeds after switching UCP either way, so Google hears about it before the files reach feeds.max_age.

PayPal and other providers. Only Stripe charges Google Pay tokens today. PayPal's Google Pay support is planned for a later phase. A store on any other provider still sells to Google's agents: the buyer finishes on your own checkout through the continue_url.

Set up ChatGPT

ChatGPT finds products through the OpenAI product feed. OpenAI takes the file by SFTP. KahunaCart builds it, and a cron line pushes it.

1. Register as a merchant with OpenAI and get the SFTP host, user and key.
2. Fill in Seller and Store policies first. The OpenAI feed carries the seller name, the privacy and terms links and the return policy, and requires a brand on every row, so the seller name stands in for a product with none.
3. Add a nightly cron line that runs bin/plugin kahunacart feeds:build --feed=openai --out=/var/feeds and pushes openai.jsonl.gz with sftp. See Product feeds → Set up ChatGPT.

Named with --feed, the file is built even while feeds.enabled or agentic.enabled is off, so a store that only pushes to OpenAI serves nothing under {base}/feeds.

Set up an MCP client

1. Switch the endpoint on: storefront_mcp.enabled: true.
2. Give the client https://your-store.example/shop/mcp (your storefront route plus /mcp) as a Streamable HTTP server. There is nothing to authenticate.
3. A web app calling the endpoint from a browser page needs its origin in storefront_mcp.allowed_origins. Server-to-server clients send no Origin and need nothing.

A plain MCP client, one that sends no UCP profile, may browse, build carts and create checkouts while storefront_mcp.allow_anonymous is on (the default). It has no payment handler, so its checkouts end at the continue_url and the buyer pays on your checkout. Turn allow_anonymous off to serve UCP platforms only. See Storefront MCP.

Switch a part off

Keep an eye on it

• The Agentic commerce screen, under Setup in the store admin, shows whether UCP is ready and what is missing, the profile, REST and MCP addresses, the signing key, each feed file with its build time, and the open agent sessions. It has Rebuild feeds and Rotate signing key buttons. The same data is get_agentic_status, list_feeds and list_agent_sessions over the REST API.
• The doctor. bin/plugin kahunacart check runs the agentic readiness check while agentic commerce is on.
• Mark delivered. Google's order lifecycle expects a delivered event. Press Mark delivered on a shipment when the parcel arrives, or let a carrier add-on do it. See Mark a shipment delivered.
• Your CDN. Keep /.well-known/ucp, {base}/ucp/*, {base}/mcp and {base}/feeds/* out of "block AI bots" rules and JavaScript challenges. See Hardening → Agent endpoints.

Related

• Product feeds
• Storefront MCP
• UCP checkout
• Product data for search engines and agents
• Configuration → Agentic commerce
• Hardening → Agent endpoints
• Run the store from an AI assistant