REST API Fallback

REST API transport

UCP Playground uses REST as the main transport for REST-only stores, and as a fallback when an MCP call fails. The UCP specification defines the REST endpoints agents use to search, build a cart and check out.

REST-only stores

Stores that declare only a rest transport in their UCP profile (/.well-known/ucp) work in the Playground as they are. With no MCP endpoint, the Playground maps each tool call the agent makes to your REST endpoints. A run on a store that declares both uses MCP first.

REST has no tool list to ask for, so the tools come from the capabilities your profile declares, under the names the MCP binding uses. A store that declares dev.ucp.shopping.catalog.lookup gets both of its operations: lookup_catalog (several ids in one call) and get_product (one product in full). Inspect works the same way: at a REST-only store it starts over REST and lists the same tools.

json
{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [{
        "version": "2026-08-25",
        "spec": "https://ucp.dev/2026-08-25/specification/overview",
        "transport": "rest",
        "schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json",
        "endpoint": "https://yourstore.com/wp-json/wc/ucp/v1"
      }]
    }
  }
}

REST endpoint paths

The Playground calls these paths, relative to your declared endpoint. For a store on UCP 2026-08-25:

  • POST /catalog/search — search products, with the query and filters in the body
  • POST /catalog/lookup — look up several products by ID in one call (ids)
  • POST /catalog/product — read one product in full (id)
  • POST /carts, GET /carts/:id, PUT /carts/:id, POST /carts/:id/cancel — create, read, replace and cancel a cart
  • POST /checkout-sessions — create a checkout
  • GET /checkout-sessions/:id — read a checkout
  • PUT /checkout-sessions/:id — update a checkout. The body is the whole checkout, not just the fields that changed.
  • POST /checkout-sessions/:id/complete — complete a checkout
  • POST /checkout-sessions/:id/cancel — cancel a checkout
  • GET /orders/:id — read an order
  • POST /common/locations/search, POST /common/locations/lookup — find locations, if you declare them

For stores on earlier releases, the Playground updates a checkout with a partial PATCH /checkout-sessions/:id and uses a single /cart path (POST /cart, GET /cart/:id, PATCH /cart/:id).

json
// POST /catalog/search
{
  "query": "running shoes",
  "limit": 10
}

// Response
{
  "ucp": { "version": "2026-08-25" },
  "products": [
    {
      "id": "123",
      "title": "Trail Runner",
      "price_range": { "min": { "amount": 14500, "currency": "USD" } }
    }
  ],
  "pagination": { "has_next_page": false, "total_count": 1 }
}

Permalinks are not a REST call

A UCP shopping permalink (dev.ucp.shopping.permalink) is a browser link your store answers with 303 See Other, not an operation of the REST binding. When your profile declares the capability, runs and Inspect get an open_permalink tool that writes the link, opens it once without following the redirect, and checks your answer against the capability's rules. See Inspect.

Legacy fallback

For stores on older REST conventions, the Playground also tries legacy paths:

  • GET /products?search=query — legacy search with query parameters
  • GET /products/:id — legacy product lookup by ID

It tries the UCP paths first, then the legacy ones.

MCP-to-REST fallback

When a store has both MCP and REST endpoints, the Playground uses MCP first. If an MCP call fails, it checks whether the failure qualifies for a REST fallback:

  • Error code -32601 — method not found. The MCP endpoint does not recognise the tool name.
  • HTTP 4xx or 5xx from MCP — the MCP endpoint is unreachable or misconfigured.

Error code -32603 (internal error) does not trigger a fallback. It means MCP is working but the tool itself failed.

Each tool falls back on its own

The fallback is decided per tool. If search fails over MCP and falls back to REST, checkout still tries MCP first. Once a tool has fallen back to REST in a run, later calls to that tool skip MCP.

Tip

To try your REST endpoints on their own, open your store in Inspect and choose REST under Calls go over. Each call goes to your REST endpoint, and you see the request and response. If your store declares only REST, a run on Runs uses it directly.

Something wrong on this page?