Universal Commerce Protocol (UCP) and WebMCP makes your J2Commerce store usable by AI shopping agents. UCP lets shopping platforms search your catalog, build carts and start checkouts through endpoints on your store. WebMCP gives agents running in a shopper's own browser search and cart tools.
It is for store owners who want to be found and bought from through AI assistants and keep control of who can order, how much, and with which payment methods. Every optional feature is off until you turn it on.
Requirements
- Joomla 6.0 or later
- J2Commerce 6.6.5 or later
- A store reachable over HTTPS
- Privacy policy and terms of service pages on your site
This app is a separate add-on available from the J2Commerce Extensions Store. Identity linking also needs the J2Commerce OAuth server plugin.
Installation
- Download the plugin package from your J2Commerce Extensions Store account.
- In Joomla, go to System -> Install -> Extensions and upload the package.
- Go to J2Commerce -> Apps and open Universal Commerce Protocol (UCP) and WebMCP.
- Set Status to Enabled and save.
What It Does
UCP Merchant Server
With Enable the UCP Server on, your store publishes a discovery profile at /.well-known/ucp and serves the agent endpoints for catalog, carts and checkout. Each request is answered in the UCP version the platform asks for.
WebMCP Storefront Tools
With Enable WebMCP Storefront Tools on, the storefront registers search and cart tools for agents that run inside the shopper's own browser. The tools work in the shopper's own session. An optional checkout tool handles cash, money order and bank transfer only, and the shopper still confirms every order in a dialog your store shows.
Setup
- Open the Basic tab and enter your Privacy Policy URL and Terms of Service URL. The UCP server needs both.
- Turn on Enable the UCP Server, Enable WebMCP Storefront Tools, or both.
- Open the Agents and Access tab and choose who may use checkout (see Trust Levels below).
- Open the Payment tab and set up the payment methods agents may use.
- Open the Limits tab and set the largest order, countries, payment methods and hourly order limits you are comfortable with.
- Save, then check the setup checks on the J2Commerce dashboard. Each failed check has a Fix This link.
Tip
Start with the Allow List policy, a low Largest Order An Agent May Place and one trusted platform. Widen the limits once you have seen real agent orders in the Agent Log.
Settings
Basic Tab
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Enable the UCP Server | Publishes the discovery profile at /.well-known/ucp and serves the agent endpoints. Needs the privacy and terms URLs. | No | Yes, No |
| Enable WebMCP Storefront Tools | Registers search and cart tools for agents in the shopper's browser. | No | Yes, No |
| Allow Agents to Start Order Placement | Adds a checkout tool for cash, money order and bank transfer. The shopper confirms every order in a dialog the store renders. Shown when WebMCP is on. | No | Yes, No |
| UCP Versions to Serve | The UCP versions your store answers in. The 2026-04-08 profile stays the default while it is enabled. | 2026-04-08, 2026-08-25 | 2026-04-08, 2026-08-25 |
| Privacy Policy URL | Link to your privacy policy. Required for agent checkout. | Empty | A URL |
| Terms of Service URL | Link to your terms of service. Required for agent checkout. | Empty | A URL |
| Refund Policy URL | Optional link to your refund policy. | Empty | A URL |
| Shipping Policy URL | Optional link to your shipping policy. | Empty | A URL |
Agents and Access Tab
This tab decides which platforms may use your store and how fast they may send requests.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Agent Access Policy | Allow List: only the platforms you list may use the checkout endpoints. Open: any platform with a valid signature or API key. | Allow List | Allow List, Open |
| Trusted Platforms | The platforms you list, by host, with a label and how they authenticate. Shown with the Allow List policy. | Empty | Host, Label, Authentication |
| Authentication (per platform) | How a listed platform proves who it is. | Signed requests (RFC 9421) | Signed requests (RFC 9421), API key |
| Require Signatures on Catalog Requests | Catalog and checkout requests must carry a valid RFC 9421 signature or an API key. | Yes | Yes, No |
| Anonymous Checkout Build | Lets platforms without a signature or API key create and edit carts and checkouts. They cannot complete an order or read orders. Applies even when signatures are required on catalog requests. | No | Yes, No |
| API Keys | Keys for platforms that do not sign requests, each bound to one host. The secret needs at least 32 characters, for example from openssl rand -hex 32. It is stored as a hash and never shown again. | Empty | Host, Label, Secret |
| Requests Per Minute: Anonymous | Request limit for callers with no signature or key. | 30 | 1 or more |
| Requests Per Minute: API Key | Request limit for callers using an API key. | 120 | 1 or more |
| Requests Per Minute: Signed | Request limit for trusted platforms that sign requests. | 600 | 1 or more |
| Requests Per Minute (Signed, Not Listed) | Request limit for a platform that signs its requests but is not on your Trusted Platforms list. | 60 | 1 or more |
| Campaign Medium | The utm_medium value added to checkout links sent to buyers, so your analytics can tell agent visits from other traffic. Letters, numbers, dots, dashes and underscores, up to 64 characters. | ai_agent | Text |
| Campaign Source | What the utm_source value names. A platform without a label always uses its host name. | Platform Label | Platform Label, Platform Host Name |
Trust Levels
A platform falls into one of three levels. Each level has its own request limit.
- Unsigned: no signature or key. Allowed only to build carts and checkouts, and only when Anonymous Checkout Build is on. It cannot complete an order.
- Signed: sends a valid signature but is not on your list. Uses the Signed, Not Listed limit. Whether it may check out depends on the Agent Access Policy.
- Trusted: listed under Trusted Platforms. Uses the Signed or API Key limit that matches its authentication.
Agent Checkout Tab
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Checkout Session Lifetime (Minutes) | How long an agent checkout session stays open. | 360 | 30 to 360 |
| Open Sessions Per Platform | How many sessions one platform may keep open at once. | 50 | 1 or more |
| Lines Per Session | Most product lines in one session. | 25 | 1 or more |
| Maximum Quantity Per Line | Most units of one product in one line. | 99 | 1 or more |
| Maximum Request Size (Bytes) | Largest request body the endpoints accept. | 262144 | 1024 or more |
| Menu Item for Hand-Off Checkout | The menu item used for the hand-off checkout page. | None | Any menu item |
| Offer a Store Checkout Link | Open checkouts include a link that puts the same items in the buyer's own cart on your store. Not offered on AP2 checkouts. | Yes | Yes, No |
| Escalation Contact URL | Where a buyer can reach your store about a checkout held for review. Shown as a link on the review page. Leave empty to show no link. | Empty | A URL |
Cart Tab
New in 6.1. Agent carts let a platform build a cart before it starts checkout. A cart holds items and estimated totals only and never takes payment.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Agent Carts | Lets platforms build carts with the UCP cart capability. | No | Yes, No |
| Cart Lifetime (Minutes) | How long an unused cart stays open before it expires. Shown when Agent Carts is on. | 1440 | 30 to 10080 |
| Open Carts Per Platform | How many carts one platform may keep open at once. Shown when Agent Carts is on. | 50 | 1 or more |
Limits Tab
New in 6.1. These are the merchant limits on what agents may order.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Largest Order An Agent May Place | An order above this total, in the order currency, is sent to the buyer to finish on your store. 0 means no limit. | 0 | 0 or more |
| Countries Agents May Ship To | Agents can only place orders that ship to these countries. Leave empty for no restriction beyond your shipping rules. | Empty | Any country |
| Payment Methods Offered To Agents | Agents are offered only these payment methods. Leave empty to offer every payment method that works with agents. | Empty | Your payment methods |
| Agent Orders Per Hour (Store) | The most orders all agents together may place in one hour. Over the limit, agents are told to retry later and shoppers can still order on your store. 0 means no limit. | 0 | 0 or more |
| Agent Orders Per Hour (Each Platform) | The most orders one platform may place in one hour. Over the limit, that platform is told to retry later. 0 means no limit. | 0 | 0 or more |
Payment Tab
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Google Pay Environment | Whether Google Pay runs in test or live mode. | Test | Test, Production |
| Google Pay Merchant ID | Your Google Pay merchant ID. | Empty | Text |
| Google Pay Merchant Name | The merchant name shown to the buyer. | Empty | Text |
| Accept AP2 Mandates | Lets a platform that holds a signed buyer mandate complete checkout. Only payment methods that declare AP2 support receive the mandate. | No | Yes, No |
| Only AP2 Platforms May Complete | Platforms that do not use AP2 are sent to your store checkout to finish. A checkout that negotiated AP2 always needs a signed mandate. Shown when AP2 is on. | No | Yes, No |
| Mandate Audiences | One identifier per line that a buyer mandate may name as its audience, in addition to your store address and profile URL. Shown when AP2 is on. | Empty | Text, one per line |
| Payment Methods With Their Own Payment Page | Payment methods that send the buyer to the gateway's own page to pay. Agents cannot charge them, so the agent sends the buyer to the checkout link and the buyer pays there. | Empty | Your payment methods |
Discovery Files Tab
New in 6.1. These optional files describe your store to AI agents.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Serve /llms.txt | Publishes /llms.txt, a short plain-text map of your store. A physical llms.txt file in the site root takes its place. | No | Yes, No |
| Serve /agents.md | Publishes /agents.md, a guide for AI agents to your endpoints, trust levels and limits. | No | Yes, No |
| Serve Agent Card (Experimental) | Publishes /.well-known/agent-card.json describing your store. Needs the UCP server. No A2A endpoint is served. | No | Yes, No |
| Store Introduction | One or two sentences about your store, shown at the top of the discovery files. Plain text, up to 1000 characters. Leave empty for a standard summary. | Empty | Text |
Identity Linking Tab
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Enable OAuth Identity Linking | Needs the J2Commerce OAuth server plugin. Offers the order read and checkout scopes and lets a linked shopper read their own orders. | No | Yes, No |
Order Webhooks Tab
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Google API Key | Stored encrypted. Used only to deliver order events to Google. | Empty | Text |
Advanced Tab
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Log Retention (Days) | How long agent log entries are kept. | 90 | 1 or more |
| Allowed Outbound Ports | Comma-separated ports the server may contact when fetching platform profiles and delivering webhooks. | 443 | Comma-separated numbers |
| Conformance Test Mode | For development only. Needs Debug System on in Global Configuration. Do not enable on a live store. | No | Yes, No |
| Conformance Simulation Secret | For development only. The value the conformance harness sends to mark an order shipped. Shown when Conformance Test Mode is on. | Empty | Text |
| Debug Log | Writes request metadata to the plugin log. Bodies and tokens are never logged. | No | Yes, No |
Keep a Product Out of Agent Checkout
- Open the product and go to its General tab.
- Set Exclude From Agentic Checkout to Yes and save. To read the help text under the switch, turn on Toggle Inline Help in the product form toolbar.
Agents cannot add that product to a checkout, and Google is told it is not available for agent checkout. Shoppers can still buy it on your store.
After an Agent Orders
- Agent Log: lists every request from platforms and browser agents with time, channel, operation, agent, authentication, status and duration. You can export it to CSV and purge old entries.
- Dashboard: shows agent activity, revenue by platform, signature results, errors and response times for a date range.
- Signing Keys: generate, activate, retire and revoke the keys your store uses to sign order events and AP2 authorizations. One active key is needed.
Troubleshooting
| Problem | What to Check |
|---|---|
| The UCP server does not respond | Confirm Enable the UCP Server is on and both the privacy and terms URLs are filled in. |
| A platform is refused at checkout | With the Allow List policy, add the platform under Trusted Platforms, or switch the policy to Open. |
| Agents are told to retry later | Check the hourly order limits on the Limits tab and the request limits on the Agents and Access tab. |
| A large order is sent to the store checkout | The order is above Largest Order An Agent May Place. Raise the limit or leave it at 0. |
/llms.txt shows a different file | A physical llms.txt in the site root takes its place. Remove it to serve the generated one. |
| A setup check fails | Use its Fix This link. A missing signing key is created under Signing Keys. |
Uninstalling
Disable the plugin in J2Commerce -> Apps to stop serving the agent endpoints, or uninstall it under System -> Manage -> Extensions. Uninstalling removes the plugin's own tables, including the agent log.