|
What is UCP?
The Universal Commerce Protocol (UCP) is an open standard co-developed by Google, Shopify, Etsy, Wayfair, Target, Walmart and endorsed by over 40 companies including Stripe, PayPal, Visa, Mastercard, Best Buy, Macy's and many more.
UCP establishes a common language for AI agents, platforms and businesses to interact. It allows AI assistants (such as Google Gemini, ChatGPT, Claude and others) to discover products on your store, create carts, process checkout and handle payments on behalf of their users : all through a standardized API.
In practice, this means a customer can say to their AI assistant "find me a blue jacket under $100" and the AI can search your store, show matching products, and guide the customer through checkout without them ever needing to visit your website directly.
HikaShop implements UCP through a system plugin that exposes the necessary API endpoints. Once enabled and configured, your store becomes discoverable and purchasable by any UCP-compatible AI agent.
How it works
UCP works through a set of REST API endpoints that your store exposes. AI agents interact with these endpoints to perform commerce operations. Here is an overview of the different components and how they communicate:
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────────┐
│ │ │ │ │ │ │ │
│ Customer │ │ AI Agent │ │ Your HikaShop │ │ Payment Gateway │
│ │ │ (Gemini, │ │ Store + UCP Plugin │ │ (Stripe, │
│ │ │ Claude, │ │ │ │ Worldline) │
│ │ │ etc.) │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ └────────┬─────────┘
│ │ │ │
│ "Find me a │ │ │
│ blue jacket" │ │ │
│───────────────────>│ │ │
│ │ │ │
│ │ GET /.well-known/ucp │ │
│ │───────────────────────>│ │
│ │ Discovery response │ │
│ │<───────────────────────│ │
│ │ │ │
│ │ POST /ucp/v1/search │ │
│ │ { "query": "blue │ │
│ │ jacket" } │ │
│ │───────────────────────>│ │
│ │ Product results │ │
│ │<───────────────────────│ │
│ │ │ │
│ "Here are 3 │ │ │
│ options..." │ │ │
│<───────────────────│ │ │
│ │ │ │
│ "I'll take the │ │ │
│ second one" │ │ │
│───────────────────>│ │ │
│ │ │ │
│ │ POST /checkout-sessions│ │
│ │ { items, buyer, │ │
│ │ shipping address } │ │
│ │───────────────────────>│ │
│ │ Session with totals │ │
│ │<───────────────────────│ │
│ │ │ │
│ "Total is $79. │ │ │
│ Confirm?" │ │ │
│<───────────────────│ │ │
│ │ │ │
│ "Yes, pay with │ │ │
│ Google Pay" │ │ │
│───────────────────>│ │ │
│ │ │ │
│ │ POST /complete │ │
│ │ { payment credential }│ │
│ │───────────────────────>│ │
│ │ │ Process payment │
│ │ │─────────────────────────>│
│ │ │ Payment confirmed │
│ │ │<─────────────────────────│
│ │ Order confirmed │ │
│ │<───────────────────────│ │
│ │ │ │
│ "Done! Order │ │ │
│ #1234 placed." │ │ │
│<───────────────────│ │ │
│ │ │ │
The purchase flow
Here is a closer look at what happens during each step of the UCP purchase flow between the AI agent and your HikaShop store:
AI Agent HikaShop UCP Plugin
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 1: DISCOVERY │ │
│ │ The AI agent discovers your store's capabilities │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ GET /.well-known/ucp │
│──────────────────────────────────────────────────────>│
│ │ Reads plugin config,
│ │ detects Google Pay gateway,
│ { │ builds capability list
│ "ucp": { │
│ "version": "2026-01-11", │
│ "capabilities": [ │
│ "dev.ucp.shopping.catalog", │
│ "dev.ucp.shopping.checkout", │
│ "dev.ucp.shopping.payment" │
│ ] │
│ }, │
│ "payment": { "handlers": ["com.google.pay"] } │
│ } │
│<──────────────────────────────────────────────────────│
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 2: PRODUCT SEARCH │ │
│ │ The AI searches for products matching the │ │
│ │ customer's request │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ POST /ucp/v1/search │
│ { "query": "blue jacket", "limit": 10 } │
│──────────────────────────────────────────────────────>│
│ │ Searches products,
│ { │ applies stock/access
│ "products": [ │ filters, formats
│ { "id": "gid://site/Product/42", │ prices in cents
│ "name": "Classic Blue Jacket", │
│ "price": { "amount": 7900, "currency":"USD" }, │
│ "availability": "in_stock", │
│ "images": [...] } │
│ ], │
│ "total": 3 │
│ } │
│<──────────────────────────────────────────────────────│
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 3: CREATE CHECKOUT SESSION │ │
│ │ A cart is created with the selected products, │ │
│ │ buyer info, and shipping address │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ POST /ucp/v1/checkout-sessions │
│ { │
│ "line_items": [ │
│ { "item": { "id": "gid://.../42" }, │
│ "quantity": 1 } │
│ ], │
│ "buyer": { │
│ "email": "john@example.com", │
│ "first_name": "John" }, │
│ "fulfillment": { │
│ "methods": [{ │
│ "type": "shipping", │
│ "destinations": [{ │
│ "country": "US", │
│ "postal_code": "10001", │
│ "street_address": "123 Main St" }] │
│ }] │
│ } │
│ } │
│──────────────────────────────────────────────────────>│
│ │ Creates UCP cart,
│ { │ assigns user,
│ "id": "gid://site/Checkout/99", │ calculates taxes
│ "status": "incomplete", │ and shipping options
│ "totals": [ │
│ { "type": "subtotal", "amount": 7900 }, │
│ { "type": "tax", "amount": 632 }, │
│ { "type": "fulfillment", "amount": 500 }, │
│ { "type": "total", "amount": 9032 } │
│ ], │
│ "fulfillment": { │
│ "options": [ │
│ { "id": "5", "name": "Standard", ... }, │
│ { "id": "8", "name": "Express", ... } │
│ ] │
│ } │
│ } │
│<──────────────────────────────────────────────────────│
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 4: COMPLETE CHECKOUT │ │
│ │ The order is created and payment is processed │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ POST /ucp/v1/checkout-sessions/99/complete │
│ { "payment_method_id": "gid://.../7", │
│ "payment_data": { │
│ "handler_id": "com.google.pay", │
│ "credential": { "token": "..." } │
│ } │
│ } │
│──────────────────────────────────────────────────────>│
│ │ Creates order from cart,
│ { │ sends payment token to
│ "status": "completed", │ gateway, confirms order
│ "order": { │
│ "id": "gid://site/Order/1234", │
│ "permalink_url": "https://..." } │
│ } │
│<──────────────────────────────────────────────────────│
│ │
Payment flows
UCP supports two different payment flows depending on how the payment gateway works:
Direct token flow (Google Pay)
The AI agent's platform (e.g., Google) obtains a payment token from the customer's wallet and sends it directly in the checkout completion request. The payment plugin processes the token server-side without any customer redirect. This is the fastest and most seamless flow.
AI Agent HikaShop Payment Gateway
│ │ │
│ POST /complete │ │
│ { token: "..." } │ │
│────────────────────>│ │
│ │ Charge token │
│ │───────────────────────>│
│ │ Payment confirmed │
│ │<───────────────────────│
│ Order confirmed │ │
│<────────────────────│ │
│ │ │
Hosted checkout flow
When no payment token is available, the AI agent receives a hosted checkout URL from the payment gateway. The customer is redirected to the gateway's secure page to complete payment. After payment, the gateway notifies HikaShop via webhook.
AI Agent HikaShop Payment Gateway Customer
│ │ │ │
│ POST /complete │ │ │
│ { method_id only } │ │ │
│────────────────────>│ │ │
│ │ Create hosted session │ │
│ │───────────────────────>│ │
│ │ Hosted checkout URL │ │
│ │<───────────────────────│ │
│ continue_url │ │ │
│<────────────────────│ │ │
│ │ │ │
│ Redirect customer │ │ │
│─────────────────────────────────────────────────────────────────>│
│ │ │ Customer pays │
│ │ │<──────────────────│
│ │ Webhook notification │ │
│ │<───────────────────────│ │
│ │ Order confirmed │ │
│ │ │ │
Setting up UCP on your website
Setting up UCP on your HikaShop store involves enabling the plugin, configuring a few settings, and making sure you have a compatible payment method. Here are the steps:
1. Install and enable the plugin
The UCP plugin is included with HikaShop. Go to Extensions > Plugins in your Joomla backend and search for "HikaShop UCP". Enable the plugin by clicking on the status icon.
On WordPress, go to Plugins and make sure the HikaShop UCP plugin is activated.
2. Configure the plugin
Open the plugin settings and configure the following:
- API Keys: Add one API key per client (AI platform or agent) that will access your store. Each entry has a client name (for your reference) and a secret key value that the client sends via the
X-API-KEYheader. If no keys are configured, the API is accessible without authentication (not recommended for production as it can lead to spam orders on your shop). - Base Path: The URL path for the REST API endpoints. Default is
/ucp/v1. You generally don't need to change this. - Privacy Policy URL and Terms of Service URL: Links to your store's legal pages. These are included in the UCP discovery response so that AI agents can present them to customers. These should be provided.
Google Pay settings
If you want to enable Google Pay as a payment handler (recommended), configure these additional settings:
- Enable Google Pay: Set to Yes.
- Environment: Use TEST for development, switch to PRODUCTION for your live store.
- Merchant ID: Your Google Pay merchant ID from the Google Pay Business Console.
- Merchant Name: Your business name as it should appear in Google Pay.
- Card Networks: The card types you accept (Visa, Mastercard, Amex, Discover, JCB).
- Auth Methods: PAN_ONLY (cards saved in Google Account) and/or CRYPTOGRAM_3DS (device tokens from Android phones).
3. Set up a compatible payment plugin
You need at least one UCP-compatible payment plugin installed and configured. Currently, two payment plugins support UCP:
See the Compatible payment plugins section below for details on each.
4. Verify your setup
Once the plugin is enabled and configured, you can verify your setup by accessing the discovery endpoint in your browser:
https://www.yoursite.com/.well-known/ucp
You should see a JSON response listing your store's UCP capabilities, the supported services, and the available payment handlers. If Google Pay is properly configured, you should see it listed under the payment.handlers section.
Connecting to AI platforms
Once UCP is set up on your store, AI platforms need to know about it. The process differs depending on the platform.
Google (Gemini, Search AI Mode)
Google is one of the first platforms to support UCP natively for shopping. To connect your HikaShop store to Google's AI surfaces (Gemini, Search AI Mode), you need to:
- Set up Google Merchant Center: You need a Google Merchant Center account in good standing with approved products listed for free listings. Configure your shipping settings, return policies, and customer support information.
- Configure the HikaShop Google Products plugin: This plugin generates the product feed that Google Merchant Center uses to index your products. Make sure it is installed, enabled, and properly configured. See the Google Products plugin documentation for setup instructions. When the UCP plugin is enabled, the Google Products plugin automatically adds the
native_commerceattribute to all products in the feed, which signals to Google that they are eligible for UCP checkout. - Set up Google Pay: Create a business account in the Google Pay & Wallet Console. Note your Google Pay Merchant ID : you will need it for the UCP plugin's Google Pay settings.
- Join the Google UCP program: Google requires merchants to go through an approval process before their UCP integration can go live. Visit the Google UCP developer guide to fill out the interest form and get in contact with Google's team.
- Google discovers your store automatically: Once approved, Google crawls your
/.well-known/ucpendpoint to discover your store's capabilities, available services, payment handlers, and product catalog. You do not need to paste any token or URL into Google Merchant Center : the discovery is automatic based on your domain.
Note: Authentication between Google and your store uses cryptographic signing keys (JWK format) published in your /.well-known/ucp manifest, not the API key from the plugin settings. Google verifies webhooks and messages using these public keys. The UCP plugin handles this automatically.
Other AI agents
For other AI platforms and agents that support UCP (or any custom integration), the process is simpler:
- Create an API key: In the UCP plugin settings, add an API key entry for the platform (give it a recognizable client name). Share the key value with the platform so their agent can authenticate against your store's REST API via the
X-API-KEYheader. - Provide your discovery URL: Give them your store's discovery endpoint:
https://www.yoursite.com/.well-known/ucp. The AI agent will call this to discover your store's capabilities and API endpoints. - MCP-compatible agents: If the AI agent supports MCP (Model Context Protocol) : like Claude : you can enable the MCP endpoint in the plugin settings and provide the MCP URL instead (see MCP support).
Since UCP is an open standard, any AI platform that implements the specification can interact with your store. As more platforms adopt UCP, your store will be accessible to a growing number of AI agents without any additional configuration.
ChatGPT Shopping (product feed)
ChatGPT Shopping uses a different approach than UCP. Instead of a real-time API, OpenAI crawls a static product feed file (JSON) hosted on your website. This feed allows your products to appear in ChatGPT search results.
The Google Products plugin can generate this JSON feed alongside the existing Google Shopping XML feed. See the OpenAI / ChatGPT Shopping section of the Google Products plugin documentation for setup instructions.
Plugin settings reference
| Setting | Description | Default |
|---|---|---|
| API Keys | Repeatable table of API keys for authenticating requests. Each row has a Client name (label for your reference, e.g. "Google", "Claude") and an API Key value sent by the client via the X-API-KEY header. Configure one key per AI platform or agent. Leave empty to disable authentication (not recommended for production). |
empty |
| Base Path | URL path prefix for all REST endpoints (e.g., /ucp/v1). |
/ucp/v1 |
| Enable MCP | Enables the Model Context Protocol (MCP) JSON-RPC endpoint for AI-native integration. See MCP support. | No |
| MCP Slug | URL slug for the MCP endpoint (e.g., /ucp-mcp). |
ucp-mcp |
| Privacy Policy URL | Link to your privacy policy. Included in the discovery response. | empty |
| Terms of Service URL | Link to your terms of service. Included in the discovery response. | empty |
| Enable Google Pay | Advertise Google Pay as a payment handler in UCP discovery. | No |
| Google Pay Environment | TEST for sandbox testing, PRODUCTION for live payments. | TEST |
| Google Pay Merchant ID | Your merchant ID from the Google Pay Business Console. | empty |
| Google Pay Merchant Name | Business name displayed in Google Pay. | empty |
| Card Networks | Accepted card types for Google Pay. | VISA, MASTERCARD |
| Auth Methods | PAN_ONLY (cards in Google Account) and/or CRYPTOGRAM_3DS (device tokens). | PAN_ONLY, CRYPTOGRAM_3DS |
Compatible payment plugins
For UCP to process payments, you need a payment plugin that supports at least one of the UCP payment flows: the direct token flow (for Google Pay) and/or the hosted checkout flow (for redirect-based payments). Currently, two plugins support UCP:
Stripe Checkout
Available on the HikaShop marketplace
The Stripe Checkout plugin supports both UCP payment flows:
- Direct token flow: Processes Google Pay tokens via the Stripe PaymentIntents API. Supports 3D Secure challenges when required by the card issuer.
- Hosted checkout flow: Generates a Stripe Checkout Session URL where the customer can pay using any method supported by Stripe (cards, Apple Pay, Google Pay, bank transfers, etc.).
Setup for UCP: Make sure your Stripe plugin is configured with a valid Publishable Key and Secret Key. The publishable key is automatically used as the Google Pay gateway merchant ID. No additional UCP-specific configuration is needed in the Stripe plugin itself : UCP support is built-in.
Note: The Stripe Checkout plugin uses the gateway identifier stripe for Google Pay tokenization. Stripe handles all PCI compliance and token decryption on their servers.
Worldline Direct
Available on the HikaShop marketplace
The Worldline Direct plugin (formerly Ingenico Direct) also supports both UCP payment flows:
- Direct token flow: Processes Google Pay encrypted tokens via the Worldline CreatePayment API. Automatically handles 3D Secure authentication for PAN_ONLY tokens. Supports redirect-based 3DS challenges when required.
- Hosted checkout flow: Generates a Worldline hosted checkout page URL where the customer can pay using cards and other methods supported by Worldline.
Setup for UCP: Make sure your Worldline Direct plugin is configured with a valid PSPID, API Key, API Secret, and Webhook Secret. The PSPID is automatically used as the Google Pay gateway merchant ID. No additional UCP-specific configuration is needed in the Worldline plugin itself.
Note: The Worldline Direct plugin uses the gateway identifier worldline for Google Pay tokenization. Worldline uses product code 320 for Google Pay payments.
Making other payment plugins UCP-compatible
Payment plugin developers can add UCP support to their plugins by implementing up to three methods in their payment plugin class:
getPaymentURL(&$order, &$method): Return a hosted checkout URL for the order.onUcpPaymentProcess(&$order, &$paymentContext, &$paymentResult): Process a payment token directly.getUcpGooglePayConfig(): Return the Google Pay gateway configuration (gateway name and merchant ID).
All three methods are optional. A plugin can support just the hosted checkout flow, just the direct token flow, or both. You can base yourself on the example payment plugin.
MCP support
In addition to the REST API, HikaShop's UCP plugin can optionally expose an MCP (Model Context Protocol) endpoint. MCP is a JSON-RPC based protocol designed for AI models to interact with external tools natively. It is the protocol used by AI assistants like Claude to call external tools.
When MCP is enabled, AI agents can interact with your store using MCP tools instead of REST calls. The following tools are available:
create_checkout: Create a checkout sessionget_checkout: Retrieve a checkout sessionupdate_checkout: Update a checkout sessioncomplete_checkout: Complete checkout and create an ordercancel_checkout: Cancel a checkout sessionlist_payment_methods: List available payment methods
To enable MCP, set Enable MCP to Yes in the plugin settings and configure the MCP Slug (default: ucp-mcp). The MCP endpoint will be available at https://www.yoursite.com/ucp-mcp.
Security
The UCP plugin includes several security mechanisms:
- API key authentication: All REST and MCP endpoints (except the discovery endpoint at
/.well-known/ucp) require a valid API key sent via theX-API-KEYheader. You can configure multiple API keys (one per client) so that each AI platform or agent has its own credentials. We strongly recommend setting API keys for production stores. - Opaque session IDs: Checkout session IDs use random opaque tokens (e.g.,
gid://site/Checkout/ucp_1773956959_c5c89f9d586ac6da) instead of sequential database IDs. This makes session URLs unguessable and prevents enumeration of other sessions. - Idempotency: The plugin supports an
Idempotency-Keyheader on checkout session creation. Sending the same key within 24 hours returns the existing session instead of creating a duplicate, preventing double orders from network retries. - Payment security: Payment tokens (such as Google Pay tokens) are encrypted by the payment gateway and can only be decrypted by the gateway's servers. HikaShop never sees or stores raw card details.
FAQ
Do customers need an account on my store?
No. The UCP plugin automatically creates a HikaShop user from the buyer's email address provided by the AI agent. If a user with that email already exists, the existing account is used.
Which AI assistants support UCP?
UCP is an open standard supported by a growing number of AI platforms. Google Gemini and Google Search AI Mode are among the first to support UCP natively for shopping. Any AI agent that implements the UCP specification can interact with your store.
Can I use UCP without Google Pay?
Yes. Google Pay is optional. Without it, the hosted checkout flow is still available: the AI agent receives a payment URL and redirects the customer to the payment gateway's page to complete payment.
Does UCP work with product variants?
Yes. Product variants are returned in search results with their own IDs, prices, and availability. AI agents can add specific variants to the cart.
Are discount codes / coupons supported?
Yes. AI agents can apply a discount code when creating or updating a checkout session. The discount is validated and applied just like it would be during a normal checkout.
What is the difference between UCP and the ChatGPT Shopping feed?
UCP is a real-time API that allows AI agents to search products, create carts, and process payments directly. The ChatGPT Shopping feed is a static JSON file that OpenAI crawls to index your products in ChatGPT search results. UCP enables a full purchase flow within the AI conversation, while the ChatGPT feed links customers back to your website to complete their purchase. Both can be used simultaneously. See the Google Products plugin documentation for the ChatGPT Shopping feed setup.
Where can I learn more about the UCP specification?
Visit ucp.dev for the full specification, or browse the GitHub repository for technical details and code samples.
