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, the site is in maintenance, or the domain isn't a storefront.

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 → priced, bookable stay item ids.
2. Create a checkout with a stay item and the buyer's name + email → a session with itemized totals (taxes and fees included).
3. Complete it → a held booking (pending, unpaid) and 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

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.