WebToffee Universal Commerce Protocol Enabler for Woocommerce

Description

WebToffee Universal Commerce Protocol Enabler for Woocommerce integrates your store with the Universal Commerce Protocol — the open standard that lets AI assistants (Google AI Mode, Gemini, ChatGPT, and others) discover, browse, and purchase from your store without custom builds for each platform.

This version implements UCP 2026-08-25 and also serves platforms still on UCP 2026-04-08.

Once activated:

1. A discovery profile is published at /.well-known/ucp — the standard entry point AI platforms fetch to learn what your store supports: its services (REST, MCP, A2A, Embedded), capabilities, payment handlers, and the public keys it signs with.
2. REST endpoints go live at /wp-json/wt-ucp/v1/, plus an MCP endpoint (/wp-json/wt-ucp/v1/mcp) and an A2A agent (/.well-known/agent-card.json).

Every request is negotiated: the calling platform names its own UCP profile in the UCP-Agent header (or, over MCP, in meta["ucp-agent"].profile). The store fetches that profile (securely, and cached), checks that it speaks UCP 2026-08-25 or 2026-04-08, and serves only the capabilities both sides support, in that version’s format.

Capabilities

Checkout (dev.ucp.shopping.checkout)
Checkout sessions are real WooCommerce orders. An agent creates a session with line items, adds the buyer and shipping details, and completes it with a payment instrument. The session reports where it stands — incomplete (with messages saying what’s missing), ready_for_complete, requires_escalation (the buyer must finish on your store, e.g. 3-D Secure), completed, or canceled — and always carries a continue_url that opens the same order on your WooCommerce checkout for the buyer.

Fulfillment (dev.ucp.shopping.fulfillment, extends Checkout)
Agents submit a shipping address and get back the rates your own WooCommerce shipping zones return (flat rate, free shipping, table rates…), pick one, and the charge is added to the order. Without this extension, checkouts for physical products hand the buyer off to your checkout page.

Cart (dev.ucp.shopping.cart)
Basket building before purchase intent, priced by WooCommerce’s own cart engine (coupons, and tax estimates when the agent supplies a location). Carts convert to checkouts with cart_id, and have a shareable continue_url that loads them into the shopper’s WooCommerce cart.

Order (dev.ucp.shopping.order)
GET /orders/{id} returns the placed order — line items with ordered/active/fulfilled quantities, fulfillment expectations, refunds and cancellations as adjustments. When the platform’s profile provides a webhook_url, the store also pushes signed order webhooks (order created, then every change).

Catalog (dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup)
Product search with category and price filters and cursor pagination, batch lookup by product/variant id or SKU, and single-product detail with interactive variant selection. Every product lists its purchasable variants (simple products are their own single variant), with prices, sale (list) prices, stock availability, options, images, categories and ratings.

Discount (dev.ucp.shopping.discount, extends Cart and Checkout)
Agents submit coupon codes in discounts.codes; WooCommerce validates and applies them, and the response lists every applied discount (including automatic ones) with per-line allocations. Rejected codes come back as typed warnings (discount_code_expired, discount_code_user_ineligible, …).

Identity Linking (dev.ucp.common.identity_linking)
An OAuth 2.0 authorization server (Authorization Code + PKCE) that lets a platform act for a signed-in shopper’s own account. Off by default; you choose which operations require a linked account (dev.ucp.shopping.order:read, dev.ucp.shopping.checkout:manage).

REST Endpoints

Method
Path
Capability

POST
/wp-json/wt-ucp/v1/catalog/search
Catalog

POST
/wp-json/wt-ucp/v1/catalog/lookup
Catalog

POST
/wp-json/wt-ucp/v1/catalog/product
Catalog

POST
/wp-json/wt-ucp/v1/carts
Cart

GET
/wp-json/wt-ucp/v1/carts/{id}
Cart

PUT
/wp-json/wt-ucp/v1/carts/{id}
Cart

POST
/wp-json/wt-ucp/v1/carts/{id}/cancel
Cart

POST
/wp-json/wt-ucp/v1/checkout-sessions
Checkout

GET
/wp-json/wt-ucp/v1/checkout-sessions/{id}
Checkout

PUT
/wp-json/wt-ucp/v1/checkout-sessions/{id}
Checkout

POST
/wp-json/wt-ucp/v1/checkout-sessions/{id}/complete
Checkout

POST
/wp-json/wt-ucp/v1/checkout-sessions/{id}/cancel
Checkout

GET
/wp-json/wt-ucp/v1/orders/{id}
Order

State-changing operations honour the Idempotency-Key header: a retry with the same key and body returns the original result; the same key with a different body is rejected with 409.

Checkout-completion and order responses are signed (RFC 9421 HTTP Message Signatures) once a signing key exists — generate one under General → Signing Keys.

Settings

Go to WooCommerce → UCP Enabler to configure:

• General — API base endpoint (for proxied setups), MCP endpoint, profile cache TTL, whether requests must carry UCP-Agent, capability toggles, and message signing keys (generate/rotate/revoke).
• Payment Handler — The Stripe Payment Handler (auto-detected when the official WooCommerce Stripe Gateway extension is active) or a generic PSP tokenizer.
• Embedded — Embedded Checkout/Cart, trusted host origins, and which delegations hosts may ask for.
• Identity Linking — The OAuth 2.0 authorization server, gated scopes, and registered platform apps.

Payment Processing

A completion request must carry exactly one payment instrument whose handler_id is one you advertise; raw card numbers are refused. The charge itself is delegated to the wbte_ucp_enabler_process_payment filter:

php
add_filter( 'wbte_ucp_enabler_process_payment', function( $result, $order, $instrument, $credential ) {
    if ( null !== $result || 'my_handler' !== $instrument['handler_id'] ) {
        return $result; // Not mine.
    }
    // Charge $credential['token'] with your gateway, then:
    //   success       → $order->payment_complete( $transaction_id ); return true;
    //   decline       → return new WP_Error( 'payment_failed', 'Card declined.' );
    //   3-D Secure    → return new WP_Error( 'requires_3ds', 'Authenticate.', array( 'redirect_url' => $challenge_url ) );
    return true;
}, 10, 4 );

For the built-in generic PSP tokenizer with no charge integration hooked in, the order is placed on hold with the token stored for manual capture.

Buyer Handoff

Every open checkout carries a continue_url. Opening it rebuilds the checkout in the shopper’s WooCommerce cart (items, coupons, addresses, the chosen shipping rate) and continues on your normal checkout page — Classic or Blocks — paying for the same order, so the agent sees the session complete. Carts have an equivalent, shareable continue_url.

Item ID Convention

• "123" → WooCommerce product 123 (a simple product is its own variant)
• "123-456" → WooCommerce product 123, variation 456

Catalog responses return variant ids in this format so agents can use them directly as line_items[].item.id. Lookup also accepts SKUs. Override with the wbte_ucp_enabler_resolve_item_id filter.

Developer Hooks

• wbte_ucp_enabler_profile — filter the published profile.
• wbte_ucp_enabler_business_capabilities — add/adjust capabilities (used for both the profile and negotiation).
• wbte_ucp_enabler_payment_handlers / wbte_ucp_enabler_payment_handlers_response — advertise payment handlers (profile and checkout responses / responses only).
• wbte_ucp_enabler_process_payment — charge a submitted instrument.
• wbte_ucp_enabler_checkout_readiness_messages — add requirements that keep a checkout from ready_for_complete.
• wbte_ucp_enabler_checkout, wbte_ucp_enabler_order, wbte_ucp_enabler_catalog_product — filter response resources.
• wbte_ucp_enabler_links, wbte_ucp_enabler_policies — legal links and structured policies on checkout/cart/order.
• wbte_ucp_enabler_embedded_implemented_delegations — delegations your embedded checkout page actually wires.
• wbte_ucp_enabler_allow_platform_host, wbte_ucp_enabler_platform_profile_request_args — control platform-profile fetching.
• wbte_ucp_enabler_checkout_completed (action) — fires when a checkout session completes.

External services

This plugin does not send any data to WebToffee. Its purpose is to let AI shopping platforms that implement the Universal Commerce Protocol (Google AI Mode, Gemini, ChatGPT, and others) browse your catalog and place orders through your store’s own endpoints. The data flows are:

Universal Commerce Protocol (ucp.dev) references. The /.well-known/ucp profile and REST responses contain fixed URLs such as https://ucp.dev/2026-08-25/schemas/shopping/checkout.json that identify which protocol version and schemas your store implements. Your server never calls these URLs; they are descriptive metadata for the platform. ucp.dev is an open specification (Apache License 2.0) maintained by the UCP Authors on GitHub.
Specification & source: https://github.com/Universal-Commerce-Protocol/ucp
License: https://github.com/Universal-Commerce-Protocol/ucp/blob/main/LICENSE

Inbound requests from AI shopping platforms. Platforms call your REST, MCP and A2A endpoints directly to search the catalog, build carts and complete checkouts. Checkout-session and order ids are unguessable references known only to the platform that created them, and requests from a different platform profile are refused.

Fetching the calling platform’s profile. UCP requires the store to fetch the profile URL each platform presents (in the UCP-Agent header or MCP meta), to negotiate capabilities. The store makes an HTTPS GET to that URL — no store or customer data is sent — refuses redirects and private/loopback/link-local addresses, bounds response size and time, and caches the result.

Order webhooks to platforms. When the platform that created an order advertises a webhook_url in its profile, the store POSTs the order (items, totals, shipping destination, refund/cancellation adjustments — the same data the platform can already read at GET /orders/{id}) to that HTTPS URL when the order is placed and whenever it changes. Each delivery is signed with your store’s key. Which platforms receive webhooks depends entirely on which platforms your customers use to place orders; the plugin sends to no platform on its own.

Optional payment handler / tokenizer. If you configure a Payment Handler (e.g. Stripe), card data is tokenized by that provider and the store charges the token through that provider’s API. Consult that provider’s own terms of service and privacy policy.