AI agents & UCP

Every Stayblox storefront speaks the Universal Commerce Protocol (UCP), the open standard AI assistants use to discover, price, and buy from businesses. If you build an agent (or integrate a UCP client), you can search a storefront's live availability, hold a priced checkout session, and place a real booking. The host stays merchant of record; the guest pays on the storefront's own payment page.

There is nothing to install and no API key to request: discovery is automatic on every storefront domain that has agent bookings enabled.

Discovery

Fetch the storefront's UCP profile (public, no auth):

GET https://{storefront-domain}/.well-known/ucp

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "transport": "mcp",
          "endpoint": "https://stay.example.com/api/mcp",
          "schema": "https://ucp.dev/2026-04-08/services/shopping/mcp.openrpc.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.catalog.lookup": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }]
    },
    "payment_handlers": {}
  },
  "signing_keys": [{ "kty": "EC", "crv": "P-256", "alg": "ES256", "use": "sig", "kid": "key_…" }]
}

The single service binding is an MCP server (Streamable HTTP) at /api/mcp on the same domain. The capability list is live per storefront:

Profile shows	Means
catalog.search + catalog.lookup	You can always discover and price stays.
dev.ucp.shopping.checkout	The host takes instant bookings: you can hold and complete checkouts.
No checkout capability	The host reviews booking requests manually. Discover and deep-link; don't attempt checkout (the tools aren't registered).
404 on the profile	The host has agent bookings switched off, or the domain isn't a storefront.
503 on the profile	The site is in maintenance mode. Retry after the Retry-After interval.

payment_handlers is empty in v1: agents never handle payment. Completing a checkout returns a payment link for the guest (see Checkout & booking).

The booking model

1. Search the catalog with dates and party size. Results are priced, bookable stay item ids.
2. Create a checkout with a stay item and the buyer's name and email. You get a session with itemized totals (taxes and fees included).
3. Complete it. That places a held booking (pending, unpaid) and returns an order.permalink_url where the guest pays.
4. The hold is released automatically if the guest never pays (typically after ~2 hours), exactly like an abandoned web checkout.

Amounts are always integers in the currency's minor unit (12345 = €123.45), per the UCP amount schema.

Limits and lifecycle

What	Value
Rate limit	60 requests/min per IP + storefront domain
Checkout session lifetime	24 h from last mutation, then canceled
Unpaid booking hold	Released by the storefront's abandoned-booking sweep (~2 h)
Idempotency	complete_checkout retries return the original order, never a duplicate booking

ACP (REST checkout)

Storefronts that also speak ACP (the Agentic Commerce Protocol) advertise a REST checkout surface alongside this profile: look for a top-level acp object with a checkout_url. It's a separate wire format over the same booking engine, useful if your platform is ACP-native rather than UCP-native. See ACP checkout for the full endpoint reference, auth, and the v1 payment posture.

Spec version and the lodging extension

Storefronts pin UCP v2026-04-08 with the generic shopping schemas. UCP's official lodging vertical is not yet published, so stay parameters (dates, party size) ride inside the catalog item id; see stay item ids. When the lodging extension lands, storefronts will adopt it additively; the profile's date-versioned capability declarations are how you'll detect it.

Not in v1 (roadmap): tokenized in-chat payments, identity linking (OAuth), push order webhooks, and a REST binding.