Integrate with the WooCommerce AI UCP REST API

This reference describes the UCP endpoints shipped in WooCommerce AI 0.8.0. The plugin advertises UCP version 2026-04-08. Use the protocol version and capabilities advertised in the store’s discovery document when choosing request schemas.

Prerequisites and discovery

↑ Back to top

Enable agentic commerce and verify the store’s WordPress.com connection and eligibility for the intended shopping integration. Fetch the public discovery document at:

https://your-store.example/.well-known/ucp

Read its shopping endpoint, protocol version, capabilities, and payment handlers. Consult the versioned UCP specification and the matching REST schema.

Proxy mode and access control

↑ Back to top

WordPress.com proxy mode is enabled by default. The local wc/ucp/v1 routes accept WordPress.com-signed requests in this mode; an unsigned direct request is rejected. Use the endpoint advertised by discovery rather than constructing a WordPress.com URL.

The woocommerce_ai_ucp_wpcom_proxy_enabled filter controls proxy mode. Returning false changes discovery to the store’s direct REST endpoint. This exposes the direct routes, with cart/session access controls enforced in the request flow. Changing proxy mode changes how requests are authenticated. Test the direct configuration on an isolated store before deploying it.

Catalog requests

↑ Back to top

• POST /catalog/search: search published, catalog-visible products using query, filters, and pagination. The limit defaults to 10 and is capped at 100. Use the returned cursor for the next page.
• POST /catalog/lookup: resolve a non-empty ids array containing product IDs, variation IDs, or SKUs. The release limits lookup requests to 50 identifiers.
• POST /catalog/product: retrieve a product by id, with optional selected options for a variation choice.

Catalog requests use JSON bodies and do not require an Idempotency-Key. They are rate limited. The local catalog tier defaults to 120 requests per 60 seconds. In direct mode, requests without a valid session use a client-address bucket. Pre-session proxy requests defer that path to WordPress.com, whose limits are a separate backend contract.

Test a read-only catalog request

↑ Back to top

The following example is for an isolated integration test store already configured for direct mode. Replace the host with that test store’s endpoint. It will not authenticate an unsigned request to a store that remains in proxy mode.

curl --request POST "https://your-test-store.example/wp-json/wc/ucp/v1/catalog/search" \
  --header "Content-Type: application/json" \
  --data '{"query":"shirt","pagination":{"limit":1}}'

Check the HTTP status, UCP metadata, product data, and any returned messages. A store with no matching visible products can return an empty result. A proxy-mode store requires a WordPress.com-signed request; an unsigned request returns 401.

Cart and checkout routes

↑ Back to top

• POST /carts: create a cart from line_items.
• GET /carts/{id}: retrieve an existing cart.
• PUT /carts/{id}: replace its line_items.
• POST /carts/{id}/cancel: empty the cart.
• POST /checkout-sessions: start a session from line_items or an existing cart_id.
• GET /checkout-sessions/{id}: retrieve the session.
• PUT /checkout-sessions/{id}: update the session.
• POST /checkout-sessions/{id}/complete: submit the payment block and place the order.
• POST /checkout-sessions/{id}/cancel: cancel the session.

Use the session identifier returned by the API and the payload schema advertised for the store. Creating a cart or session returns 201 on success. Missing or expired sessions can return 404; attempts to change a terminal checkout can return 409. Payment completion must be tested with the selected payment handler and shopping service before production use.

Idempotency and retry behavior

↑ Back to top

Mutating cart and checkout routes require an Idempotency-Key by default. Send a UUID for each distinct operation. For a retry, retain the same method, route, key, and semantically identical JSON body. The release fingerprints canonicalized JSON, so whitespace and object-key ordering do not require byte-identical requests.

• A completed request with the same fingerprint replays its stored successful response with Idempotency-Replayed: true.
• Reusing a key for a different fingerprint returns 409 with IDEMPOTENCY_KEY_REUSED.
• A request still in progress returns 409 with IDEMPOTENCY_CONFLICT.
• A missing key returns 400 with IDEMPOTENCY_KEY_REQUIRED; an invalid UUID in strict mode returns IDEMPOTENCY_KEY_INVALID.
• Only successful 2xx responses are stored. A handler error releases the key. Inspect the session state before retrying a failed payment or another action with external effects.

Rate-limit responses

↑ Back to top

The general mutation tier defaults to 60 requests per 60 seconds. Checkout completion uses a separate default of five requests per 300 seconds. Mutation buckets use verified session identity; requests without that identity can follow a different path. An over-limit response returns 429 and Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Honor Retry-After. Local middleware checks limits before idempotency replay.

Order webhooks

↑ Back to top

For UCP-origin orders in proxy mode, the plugin sends created when the order reaches a paid status, fulfilled when it completes, canceled when it is cancelled, and refund when it is refunded. The woocommerce_ai_ucp_webhooks_enabled filter can disable this delivery.

Integration checks before launch

↑ Back to top

• Confirm discovery and the advertised protocol version.
• Verify catalog visibility and variant selection.
• Test cart/session creation, updates, expiration, and cancellation.
• Verify the selected payment handler in its test mode, including failures and retries.
• Test idempotency replay, conflicting requests, 429 responses, and webhook handling.
• Confirm the WordPress.com backend and external shopping service support the intended flow.