API reference (OpenAPI)

Every UCP endpoint, header, field and response — OpenAPI 3.1 to download for Swagger, Postman and client generators.

On this page

Base URL and conventions
Downloads
Using the document in your tools
Swagger Editor
Postman and Insomnia
A typed TypeScript client
openapi-generator
Operations

The reference below is generated from the OpenAPI 3.1 document that describes Monokaido's UCP API: every operation, header, field, status code and example. The same document is published for download, so you can import it into your tools or generate a typed client from it. A guided walk through one purchase is in the Developer quickstart.

Base URL and conventions

One server per shop. Each shop serves the API on its own custom domain: the business profile at https://shop.example.com/.well-known/ucp, the REST operations under https://shop.example.com/ucp/v1. Take the base from the profile's endpoint, which names the shop's primary domain. The routes under /ucp/continue/ are opened by the buyer's browser, never by an agent.
No authentication. No API key, no OAuth, no cookie: the shop is chosen by the host you call. Every call under /ucp/v1 names your platform profile in UCP-Agent: profile="https://…".
Headers. Content-Type: application/json on every request with a body; Idempotency-Key on the seven writes (optional, strongly recommended); Accept-Language optional.
JSON in UTF-8. Fields the API does not know are ignored. A field it reads with the wrong JSON type is refused with 400 invalid_request, and content names the field. A few hints it cannot use are dropped instead: an unreadable context.language, context.currency or context.address_country, entries of discounts.codes or ids that are not strings, a selected_option_id or selected_destination_id that is not a string, and line ids (the full list: What is adjusted instead of refused).
Key order of JSON objects is not significant, in requests or answers. Answers built from stored data — a replayed write, a completed, canceled or handed-over checkout, a stored buyer or context — come back in PostgreSQL's JSONB key order (shorter keys first, then alphabetical).
Money is an integer in the ISO 4217 minor units of its currency, VAT included. The catalog writes it as an object, {"amount": 69900, "currency": "EUR"} (699.00 €); carts and checkouts write bare integers in item.price and totals[].amount next to one currency for the whole session. EUR, CZK, PLN and HUF have two decimals (1 990 Ft is 199000), JPY none, KWD three. A discount total is negative.
Timestamps are ISO 8601 in UTC with milliseconds: "expires_at": "2026-10-27T09:21:30.551Z".
Ids. Carts and checkouts have lower-case UUID v4 ids; products, variants, lines, shipping options and orders are UUIDs too. A path {id} that is not a UUID answers like an unknown session. The token in continue_url is 64 hexadecimal characters and is never the session id.
Two kinds of failure. A protocol error is an HTTP error status with {"code", "content", "continue_url"?}. A business outcome is HTTP 200 (201 for a created cart or checkout) with messages[], and with ucp.status: "error" when no resource came back. An unknown cart, checkout or product is such a 200, never a 404. A few answers come from the web server in front as HTML. Every code is in Errors and messages.
Caching. Every API answer is Cache-Control: no-store, except the business profile (public, max-age=300).
Limits per client IP and operation: 600 reads, 300 writes and 60 handoff requests per minute, shared by every shop your IP calls. Answers within the limit carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds); a 429 carries Retry-After: 60. The web server in front adds 100 requests per second per IP (bursts of up to 200 more) and a body limit of 1 MiB. Details in Idempotency, concurrency and limits.

Downloads

OpenAPI 3.1 (JSON)
The whole UCP API to import into Swagger Editor, Postman, Insomnia or openapi-generator — by URL or as a file.
https://help.monokaido.com/ucp/openapi.json
OpenAPI 3.1 (YAML)
The same document in YAML, for tools and reviews that prefer it.
https://help.monokaido.com/ucp/openapi.yaml
Agent tool definitions
Tool definitions for a language model’s function calling, mapped onto the UCP operations.
https://help.monokaido.com/ucp/tools.json
Full guide for LLMs
The whole UCP developer guide as one Markdown file, for a language model’s context.
https://help.monokaido.com/ucp/llms-full.txt
llms.txt
The contents of the whole manual for language models, in the llms.txt format.
https://help.monokaido.com/llms.txt

Using the document in your tools

The files are served with Access-Control-Allow-Origin: *, so tools that run in a browser can import them by URL too. The document's server is https://{shopDomain} with shop.example.com as the default: point every tool at the shop you integrate with, and replace the example UCP-Agent value with your own profile.

Swagger Editor

Open editor.swagger.io, choose File → Import URL and paste https://help.monokaido.com/ucp/openapi.json. The editor is good for reading and validating. Its Try it out sends requests from your browser, which the shop's API does not allow from other origins, so send requests from Postman, Insomnia, curl or your server instead.

Postman and Insomnia

Use Import and paste the URL https://help.monokaido.com/ucp/openapi.json; both turn the operations into a collection of requests. Then set the collection's base URL to the shop's origin and the UCP-Agent header to your profile. Both send requests from the desktop app, so CORS does not apply.

A typed TypeScript client

openapi-typescript turns the document into types, and openapi-fetch uses them for a small typed client:

npm install openapi-fetch
npx openapi-typescript https://help.monokaido.com/ucp/openapi.json -o src/ucp.d.ts

import createClient from 'openapi-fetch';
import type { paths } from './ucp.js';

const shop = createClient<paths>({ baseUrl: 'https://shop.example.com' });
const agent = 'profile="https://platform.example.com/.well-known/ucp"';

const { data, error, response } = await shop.POST('/ucp/v1/catalog/search', {
  params: { header: { 'UCP-Agent': agent } },
  body: { query: 'marlin', pagination: { limit: 2 }, context: { language: 'sk' } },
});
if (!data) throw new Error(`HTTP ${response.status}: ${JSON.stringify(error)}`);
// HTTP 200 is either the result or a business error with ucp.status "error".
if ('products' in data) {
  for (const p of data.products) console.log(p.title, p.price_range.min.amount);
} else {
  console.log(data.messages);
}

A 200 answer is typed as the result or a business error, so the type checker makes you handle both.

openapi-generator

openapi-generator builds clients for many languages. It needs Java; the npm wrapper downloads the generator itself:

# TypeScript (fetch)
npx @openapitools/openapi-generator-cli generate \
  -i https://help.monokaido.com/ucp/openapi.json \
  -g typescript-fetch -o ./ucp-client

# Python
npx @openapitools/openapi-generator-cli generate \
  -i https://help.monokaido.com/ucp/openapi.json \
  -g python -o ./ucp-client-py --package-name ucp_client

The generator calls its OpenAPI 3.1 support beta and prints warnings while it runs; it also renames models whose names clash with the target language (in TypeScript the Error schema becomes ModelError and RequestContext becomes ModelRequestContext) and names the inline answer types itself (GetCart200Response, CreateCheckout200Response for every checkout operation). Pass the shop's origin as the client's base path: the generated default is https://shop.example.com. A generated client cannot tell the business error of an HTTP 200 from a resource by the status: check ucp.status === "error" on every 200 as well.

Operations

The examples call https://shop.example.com — use the domain of a shop that has UCP switched on instead.

Discovery

The business profile at /.well-known/ucp: the protocol version, the REST endpoint and the capabilities this shop declares. Needs no UCP-Agent header.

Get the business profile

GET/.well-known/ucp

The shop’s UCP business profile: protocol version, the REST endpoint to call, the capabilities it declares and payment_handlers: {}. Fetch it first and use its endpoint (on the shop’s primary domain). Needs no UCP-Agent header and no negotiation.

Cacheable: Cache-Control: public, max-age=300 (every other UCP answer is no-store). Never redirected.
A shop in catalog mode declares only dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup.
No supported_versions (one version only), no signing_keys (no webhooks are sent, responses are not signed).
The web server maps this path to the API’s /ucp/well-known, which answers the same. /.well-known/ucp/ (trailing slash) is not this route.

Merchant checks: Turning UCP on for a shop.

Responses

200The business profile.

Response headers

Cache-Controlstring
The business profile may be cached for 5 minutes by anyone.
always:public, max-age=300
ETagstring
An ETag of the body, generated by the API on every response with a body (writes included). The API’s ETag is strong; the web server sends it weak (W/"…") when it compresses the response, which it does for a client that sends Accept-Encoding: gzip. A GET that sends a matching If-None-Match (either form) can be answered 304 Not Modified even though the answer is no-store.
X-RateLimit-Limitinteger
Requests this client IP may make to this operation per 60-second window (600 reads, 300 writes, 60 handoff). Set on every answer that passed the rate limiter.
X-RateLimit-Remaininginteger
The operation’s limit minus this client IP’s current count. The counts live in the API server’s memory; each request is meant to leave the count 60 s after it was made, but the rate limiter (@nestjs/throttler 6.5) drops those pending decrements, for every client, whenever any client’s block ends. Read it as an upper bound and keep steady traffic at half a limit or less.
minimum: 0
X-RateLimit-Resetinteger
Seconds left in a 60-second window the limiter keeps per client IP and operation. The count is not reset when that window ends, so this is not the moment the budget comes back.
minimum: 0

SchemaBusinessProfile

application/jsonProfile of a shop that takes orders

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/overview",
          "transport": "rest",
          "endpoint": "https://shop.example.com/ucp/v1",
          "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/catalog/search",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json"
        }
      ],
      "dev.ucp.shopping.catalog.lookup": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/catalog/lookup",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json"
        }
      ],
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/cart",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json"
        }
      ],
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/checkout",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/fulfillment",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/discount",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json",
          "extends": [
            "dev.ucp.shopping.checkout",
            "dev.ucp.shopping.cart"
          ]
        }
      ]
    },
    "payment_handlers": {}
  }
}

application/jsonProfile of a shop in catalog mode

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/overview",
          "transport": "rest",
          "endpoint": "https://shop.example.com/ucp/v1",
          "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/catalog/search",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json"
        }
      ],
      "dev.ucp.shopping.catalog.lookup": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/catalog/lookup",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json"
        }
      ]
    },
    "payment_handlers": {}
  }
}

304Not Modified — only when the request sent If-None-Match equal to the current answer’s ETag (strong as the API generates it on every response, or the weak W/"…"…NotModified

404not_found. Either the host serves no UCP — an unknown host, a *.shop.monokaido.com subdomain, a domain without verified DNS or an active certificate, UCP switc…NoBusinessOnHost

429Too Many Requests, from one of two layers: The API (application/json, rate_limited, Retry-After: 60): this client IP’s count for the operation passed its limit…RateLimited

500internal_error: an unexpected failure (logged on the server; no detail is sent). A failed write released its Idempotency-Key: retry with the same key.InternalError

502Bad Gateway — the API is down or restarting. Not produced by the API: nginx, the web server in front of the shop, answers it with its own HTML page.BadGateway

503service_unavailable "This shop is temporarily unavailable", Retry-After: 60: the shop’s company is deactivated or billing-locked, or the shop lookup failed.ShopUnavailable

504Gateway Timeout — the API did not answer within 60 s. Not produced by the API: nginx, the web server in front of the shop, answers it with its own HTML page. A…GatewayTimeout

Request with curl

curl

curl 'https://shop.example.com/.well-known/ucp'

Catalog

Search, lookup and product detail over the shop’s catalog — the same products, prices and stock states the shop’s own pages show. Search reads the shop’s product listing, a materialised view the platform refreshes in the background after catalog changes, so a new or changed product can take a few minutes to show up there; lookup and product read the product data itself. Reads only; no Idempotency-Key.

Search the catalog

POST/ucp/v1/catalog/search

Full-text search over the products the shop lists, with paging and an optional price filter.

Matching: query is a case-insensitive, diacritic-sensitive (modra does not find Modrá) substring of the product title in the answer’s language, or of the product code / external ids. Descriptions, brand names, variant SKUs and GTINs are not searched — use lookupCatalog for SKUs and ids.
Order: newest product first. There is no relevance ranking and no sort option.
What is listed: published, enabled, listed and orderable products the storefront shows (its exclusion filters and blocked categories apply). A product without a priced variant, or with no variant inside the price filter, is dropped after the page is read, so a page can be short — even empty while has_next_page is true. Keep following cursor until has_next_page is false.
Paging: pagination.limit default 10, at most 20 (larger values are lowered). The cursor encodes only the page number; repeat the query, filters, limit and context with it. total_count is the number of matching listed products and is left out whenever a price filter is in effect. Pages are counted over a listing that can change while you page (a product published meanwhile shifts the later pages): de-duplicate products by id.
Prices: in the currency of the answer’s language; filters.price is in context.currency (see PriceFilter). Search reads the shop’s product listing, a materialised view refreshed in the background after catalog changes: a new or changed product can take a few minutes to show here (lookup and product read the product data itself).
Categories: not supported; a non-empty filters.categories → 400.

An absent body — or one of a content type the API does not parse (anything but application/json and application/x-www-form-urlencoded) — is an empty search.

Parameters

UCP-Agentheaderstringrequired
Names your platform profile. Required on every /ucp/v1/* operation; never read by the profile and handoff routes.
Details
Grammar — a subset of an RFC 8941 Dictionary, at most 4096 characters:
- members separated by , (spaces or tabs around it allowed; a trailing comma is an error); keys lower-case, matching [a-z*][a-z0-9_\-.*]*;
- the profile member must be an sf-string: profile="https://…", printable ASCII 0x20–0x7E, escapes \" and \\ only;
- other members (tokens, numbers, booleans, strings) and parameters (;key=value) are parsed and ignored; when profile appears twice the last one wins;
- any parse error makes the whole header unusable.
Accepted: profile="https://platform.example.com/.well-known/ucp", version="2026-04-08", profile="https://platform.example.com/.well-known/ucp";sig=abc. Refused: a missing header, profile=https://… (a token, not a string), Profile="…", a=1 b=2, profile="…".
The URL — at most 1000 characters, no whitespace anywhere, starting https://, no user name or password, a non-empty host. Any port, path and query string are accepted (the spec’s /.well-known/ucp path is not enforced). Failing any rule → 400 invalid_profile_url.
The fetch — GET with Accept: application/json and User-Agent: Monokaido-UCP/1.0 (+https://monokaido.com); no redirects followed; only HTTP 200 accepted; at most 256 KiB; 3 s idle, 5 s total; the host must resolve to a public address (private, loopback, link-local and other reserved ranges are refused). Anything else → 424 profile_unreachable. A body that is not JSON, or whose ucp.version is not a YYYY-MM-DD string → 422 profile_malformed; a valid profile of another version → 422 version_unsupported. Only ucp.version and ucp.capabilities (name → [{"version"}], first 20 entries per name, names like dev.ucp.shopping.cart) are read; everything else in it is ignored.
Caching — a fetched profile is cached for its Cache-Control: max-age, clamped to 60 s – 1 h (5 min without one; no-store, no-cache and private are ignored) and served up to 1 h past that while one background refresh runs. A failed fetch (424, or 422 profile_malformed) is remembered for 60 s. A profile of another ucp.version is a valid profile and is cached like one, so after you change its version expect 422 version_unsupported until that entry is refreshed (its max-age, then one more request) — or use a new profile URL. These caches are kept in memory by each API process. Fetching a profile the shop does not know yet is budgeted: 5 new profile URLs per minute per client (IPv4 address, IPv6 /64) and 60 per minute in all → 503 service_unavailable with Retry-After. The full URL string is the cache key, so keep it stable (no per-request query strings).
minLength: 1maxLength: 4096example:profile="https://platform.example.com/.well-known/ucp"
Accept-Languageheaderstring
Fallback for the answer’s language after context.language in the body. The first 10 comma-separated tags are tried in header order (q= weights are ignored, * is skipped) against the languages the shop offers: an exact tag (case-insensitive), then the primary subtag (en-US → en-GB); with no match, the shop’s first language. (A storefront without a language list of its own offers every language of the company: then the primary subtag of the first usable tag is used as it is — a language the company has not set up is answered in its default currency, untranslated — and, with no tag at all, the company’s default language.)
The language decides the currency of every price and the translations. A cart or checkout keeps the language it was created in: a later request changes it only when its body names a context.language different from the stored one, and when that switches the shop language every line is re-added in the new currency and gets a new line id. Once a session has a language, this header alone never switches it. On a storefront without a language list, a session created with no usable tag stores none: each later request is then answered in the language its own tags pick, and a different pick adds the lines again (new line ids). Send context.language on the create.
example:sk-SK,sk;q=0.9,en;q=0.8

Request body

Optional. No body lists every product, newest first.

object · CatalogSearchRequest

A catalog search. The whole body is optional: no body (or {}) lists every product. Unknown fields (signals, …) are ignored.

querystring | null
Free text; longer text is cut to 200 characters. Matches, case-insensitively (but not ignoring diacritics) as a substring, the product title in the answer’s language or the product code / external ids — not descriptions, brands, variant SKUs or GTINs (use lookup for SKUs). Absent: every listed product.
maxLength: 200
filtersSearchFilters
Filters. Other filters (brand, availability …) are ignored without a message.
paginationobject
Paging.
- limitinteger
  Page size, default 10. A value above 20 is lowered to 20; 0, decimals and strings → 400.
  default:10minimum: 1
- cursorstring | null
  pagination.cursor from the previous answer. Opaque, at most 40 characters. It carries only the page number: resend the same query, filters, limit and context with it.
  maxLength: 40
contextRequestContext | null
Buyer context. Every field is optional; strings longer than the stated length are cut (counted in code points). Unknown fields (intent, eligibility, payment …) are ignored.

application/jsonSearch “marlin”, two per page

{
  "query": "marlin",
  "pagination": {
    "limit": 2
  },
  "context": {
    "language": "sk",
    "address_country": "SK",
    "currency": "EUR"
  }
}

application/jsonThe next page

{
  "query": "marlin",
  "pagination": {
    "limit": 2,
    "cursor": "cDoy"
  },
  "context": {
    "language": "sk",
    "address_country": "SK",
    "currency": "EUR"
  }
}

application/jsonA price filter in another currency

{
  "query": "marlin",
  "filters": {
    "price": {
      "max": 2500000
    }
  },
  "pagination": {
    "limit": 2
  },
  "context": {
    "language": "sk",
    "currency": "CZK"
  }
}

Responses

200A page of results (CatalogSearchResponse), or — when your profile does not declare dev.ucp.shopping.catalog.search — the capabilities_incompatible business err…

A page of results (CatalogSearchResponse), or — when your profile does not declare dev.ucp.shopping.catalog.search — the capabilities_incompatible business error.

Response headers

Cache-Controlstring
Every UCP answer (success or error) except the business profile.
always:no-store
ETagstring
An ETag of the body, generated by the API on every response with a body (writes included). The API’s ETag is strong; the web server sends it weak (W/"…") when it compresses the response, which it does for a client that sends Accept-Encoding: gzip. A GET that sends a matching If-None-Match (either form) can be answered 304 Not Modified even though the answer is no-store.
X-RateLimit-Limitinteger
Requests this client IP may make to this operation per 60-second window (600 reads, 300 writes, 60 handoff). Set on every answer that passed the rate limiter.
X-RateLimit-Remaininginteger
The operation’s limit minus this client IP’s current count. The counts live in the API server’s memory; each request is meant to leave the count 60 s after it was made, but the rate limiter (@nestjs/throttler 6.5) drops those pending decrements, for every client, whenever any client’s block ends. Read it as an upper bound and keep steady traffic at half a limit or less.
minimum: 0
X-RateLimit-Resetinteger
Seconds left in a 60-second window the limiter keeps per client IP and operation. The count is not reset when that window ends, so this is not the moment the budget comes back.
minimum: 0

oneOf

Exactly one of

CatalogSearchResponseobject · CatalogSearchResponse
A page of search results.
additionalProperties: false
- ucpResponseMetadatarequired
  The ucp object of a successful catalog or cart answer. A missing status means success.
- productsarray<Product>required
  Newest product first (there is no relevance ranking).
- paginationCatalogPaginationrequired
  Search paging.
- messagesarray<Message>
  Present only when non-empty. Search emits only price_filter_ignored.
  minItems: 1
UcpBusinessErrorResponseobject · UcpBusinessErrorResponse
HTTP 200 with no resource. The cases:
- capabilities_incompatible — your profile and this shop share no version of the operation’s root capability (always for carts and checkouts on a shop in catalog mode). Nothing ran; no Idempotency-Key was used.
- not_found — the product, cart (Cart not found or has expired) or checkout (Checkout session not found) does not exist for this shop, is malformed, or (carts) was canceled or expired. An unknown cart_id on POST /checkout-sessions also reads Checkout session not found.
- out_of_stock / item_unavailable — a create in which none of the requested items could be added; no session was created.
- handed_off — converting a cart whose lines the buyer already took to the shop.
Inside a write the last three are stored under the Idempotency-Key like a success (capabilities_incompatible is answered before the key is read).
additionalProperties: false
- ucpErrorResponseMetadatarequired
  The ucp object of a business error. Never has payment_handlers. capabilities is {} for capabilities_incompatible and lists the operation’s root (and its negotiated extensions) otherwise.
- messagesarray<MessageError>required
  Exactly one error message saying why no resource could be returned.
  minItems: 1maxItems: 1
- continue_urlstring (uri)required
  Where a buyer could go instead: the shop home (https://{primary domain}/), or https://{primary domain}/cart for handed_off. Not a handoff link.

application/jsonFirst page: two products, more to come

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {
          "version": "2026-04-08"
        }
      ]
    }
  },
  "products": [
    {
      "id": "6f1d2b7c-3a84-4e59-b0c2-8d7e1f4a5b62",
      "handle": "trek-marlin-5",
      "title": "Trek Marlin 5",
      "description": {
        "plain": "Horský bicykel s hliníkovým rámom Alpha Silver, odpruženou vidlicou a 29\" kolesami.",
        "html": "<p>Horský bicykel pre začínajúcich jazdcov.</p><ul><li>Rám Alpha Silver Aluminium</li><li>Vidlica SR Suntour XCT 30, zdvih 100 mm</li><li>Pohon Shimano 2×8</li></ul>"
      },
      "url": "https://shop.example.com/products/trek-marlin-5",
      "price_range": {
        "min": {
          "amount": 69900,
          "currency": "EUR"
        },
        "max": {
          "amount": 71900,
          "currency": "EUR"
        }
      },
      "list_price_range": {
        "min": {
          "amount": 74900,
          "currency": "EUR"
        },
        "max": {
          "amount": 74900,
          "currency": "EUR"
        }
      },
      "media": [
        {
          "type": "image",
          "url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp",
          "alt_text": "Trek Marlin 5, modrá, bočný pohľad"
        },
        {
          "type": "image",
          "url": "https://images.vendor.example/trek/marlin-5-detail.jpg"
        }
      ],
      "options": [
        {
          "name": "Farba",
          "values": [
            {
              "label": "Modrá"
            },
            {
              "label": "Čierna"
            }
          ]
        },
        {
          "name": "Veľkosť",
          "values": [
            {
              "label": "M"
            },
            {
              "label": "L"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47",
          "sku": "MARLIN5-M-MOD",
          "barcodes": [
            {
              "type": "EAN",
              "value": "8594012345674"
            }
          ],
          "title": "Modrá / M",
          "description": {
            "plain": "Modrá / M"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 69900,
            "currency": "EUR"
          },
          "list_price": {
            "amount": 74900,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "in_stock"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Modrá"
            },
            {
              "name": "Veľkosť",
              "label": "M"
            }
          ]
        },
        {
          "id": "7c2f9b1e-4a68-4e3d-b2c9-5d1f7a3e8b06",
          "sku": "MARLIN5-L-MOD",
          "title": "Modrá / L",
          "description": {
            "plain": "Modrá / L"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 69900,
            "currency": "EUR"
          },
          "availability": {
            "available": false,
            "status": "out_of_stock"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Modrá"
            },
            {
              "name": "Veľkosť",
              "label": "L"
            }
          ]
        },
        {
          "id": "d93b4a7e-1f26-4c85-a0e7-3b9c6d2f4e18",
          "sku": "MARLIN5-M-CIE",
          "title": "Čierna / M",
          "description": {
            "plain": "Čierna / M"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 71900,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "preorder"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Čierna"
            },
            {
              "name": "Veľkosť",
              "label": "M"
            }
          ]
        }
      ],
      "tags": [
        "Trek"
      ]
    },
    {
      "id": "2f6c8a1d-7e43-4b95-9c2a-4d1e8b6f3a07",
      "handle": "trek-marlin-7",
      "title": "Trek Marlin 7",
      "description": {
        "plain": "Trek Marlin 7"
      },
      "url": "https://shop.example.com/products/trek-marlin-7",
      "price_range": {
        "min": {
          "amount": 104900,
          "currency": "EUR"
        },
        "max": {
          "amount": 104900,
          "currency": "EUR"
        }
      },
      "media": [
        {
          "type": "image",
          "url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-7.webp"
        }
      ],
      "options": [
        {
          "name": "Veľkosť",
          "values": [
            {
              "label": "L"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "c8e2a5f1-3d79-4a16-b4e3-9f6c2d8a1e54",
          "sku": "MARLIN7-L",
          "title": "L",
          "description": {
            "plain": "L"
          },
          "url": "https://shop.example.com/products/trek-marlin-7",
          "price": {
            "amount": 104900,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "in_stock"
          },
          "options": [
            {
              "name": "Veľkosť",
              "label": "L"
            }
          ]
        }
      ],
      "tags": [
        "Trek"
      ]
    }
  ],
  "pagination": {
    "has_next_page": true,
    "cursor": "cDoy",
    "total_count": 3
  }
}

application/jsonPrice filter ignored for lack of an exchange rate

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {
          "version": "2026-04-08"
        }
      ]
    }
  },
  "products": [
    {
      "id": "6f1d2b7c-3a84-4e59-b0c2-8d7e1f4a5b62",
      "handle": "trek-marlin-5",
      "title": "Trek Marlin 5",
      "description": {
        "plain": "Horský bicykel s hliníkovým rámom Alpha Silver, odpruženou vidlicou a 29\" kolesami.",
        "html": "<p>Horský bicykel pre začínajúcich jazdcov.</p><ul><li>Rám Alpha Silver Aluminium</li><li>Vidlica SR Suntour XCT 30, zdvih 100 mm</li><li>Pohon Shimano 2×8</li></ul>"
      },
      "url": "https://shop.example.com/products/trek-marlin-5",
      "price_range": {
        "min": {
          "amount": 69900,
          "currency": "EUR"
        },
        "max": {
          "amount": 71900,
          "currency": "EUR"
        }
      },
      "list_price_range": {
        "min": {
          "amount": 74900,
          "currency": "EUR"
        },
        "max": {
          "amount": 74900,
          "currency": "EUR"
        }
      },
      "media": [
        {
          "type": "image",
          "url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp",
          "alt_text": "Trek Marlin 5, modrá, bočný pohľad"
        },
        {
          "type": "image",
          "url": "https://images.vendor.example/trek/marlin-5-detail.jpg"
        }
      ],
      "options": [
        {
          "name": "Farba",
          "values": [
            {
              "label": "Modrá"
            },
            {
              "label": "Čierna"
            }
          ]
        },
        {
          "name": "Veľkosť",
          "values": [
            {
              "label": "M"
            },
            {
              "label": "L"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47",
          "sku": "MARLIN5-M-MOD",
          "barcodes": [
            {
              "type": "EAN",
              "value": "8594012345674"
            }
          ],
          "title": "Modrá / M",
          "description": {
            "plain": "Modrá / M"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 69900,
            "currency": "EUR"
          },
          "list_price": {
            "amount": 74900,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "in_stock"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Modrá"
            },
            {
              "name": "Veľkosť",
              "label": "M"
            }
          ]
        },
        {
          "id": "7c2f9b1e-4a68-4e3d-b2c9-5d1f7a3e8b06",
          "sku": "MARLIN5-L-MOD",
          "title": "Modrá / L",
          "description": {
            "plain": "Modrá / L"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 69900,
            "currency": "EUR"
          },
          "availability": {
            "available": false,
            "status": "out_of_stock"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Modrá"
            },
            {
              "name": "Veľkosť",
              "label": "L"
            }
          ]
        },
        {
          "id": "d93b4a7e-1f26-4c85-a0e7-3b9c6d2f4e18",
          "sku": "MARLIN5-M-CIE",
          "title": "Čierna / M",
          "description": {
            "plain": "Čierna / M"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 71900,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "preorder"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Čierna"
            },
            {
              "name": "Veľkosť",
              "label": "M"
            }
          ]
        }
      ],
      "tags": [
        "Trek"
      ]
    },
    {
      "id": "2f6c8a1d-7e43-4b95-9c2a-4d1e8b6f3a07",
      "handle": "trek-marlin-7",
      "title": "Trek Marlin 7",
      "description": {
        "plain": "Trek Marlin 7"
      },
      "url": "https://shop.example.com/products/trek-marlin-7",
      "price_range": {
        "min": {
          "amount": 104900,
          "currency": "EUR"
        },
        "max": {
          "amount": 104900,
          "currency": "EUR"
        }
      },
      "media": [
        {
          "type": "image",
          "url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-7.webp"
        }
      ],
      "options": [
        {
          "name": "Veľkosť",
          "values": [
            {
              "label": "L"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "c8e2a5f1-3d79-4a16-b4e3-9f6c2d8a1e54",
          "sku": "MARLIN7-L",
          "title": "L",
          "description": {
            "plain": "L"
          },
          "url": "https://shop.example.com/products/trek-marlin-7",
          "price": {
            "amount": 104900,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "in_stock"
          },
          "options": [
            {
              "name": "Veľkosť",
              "label": "L"
            }
          ]
        }
      ],
      "tags": [
        "Trek"
      ]
    }
  ],
  "pagination": {
    "has_next_page": true,
    "cursor": "cDoy",
    "total_count": 3
  },
  "messages": [
    {
      "type": "warning",
      "code": "price_filter_ignored",
      "path": "$.filters.price",
      "content": "filters.price is denominated in CZK, prices are presented in EUR and cannot be converted, so the price filter was not applied"
    }
  ]
}

application/jsoncapabilities_incompatible (HTTP 200)

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error",
    "capabilities": {}
  },
  "messages": [
    {
      "type": "error",
      "code": "capabilities_incompatible",
      "content": "The platform and this business share no version of the capability this operation needs",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://shop.example.com/"
}

400Bad Request (Error): invalid_profile_url — the UCP-Agent header is missing or unusable (with continue_url); invalid_request — a field this operation reads has …

Bad Request (Error):

invalid_profile_url — the UCP-Agent header is missing or unusable (with continue_url);
invalid_request — a field this operation reads has the wrong JSON type or value; content names it. Malformed JSON or a top-level JSON primitive says only "The request is not valid". Unknown fields are ignored, never refused. For this operation: request must be an object (a JSON body that is not an object), request.query must be a string, filters must be an object, filters.price must be an object, filters.price.min|max must be a non-negative integer, filters.categories must be an array of strings, filters.categories is not supported by this shop; search by query (and filters.price) instead, pagination must be an object, pagination.limit must be a positive integer (also null), pagination.cursor is not valid, context must be an object, context.<field> must be a string.

Response headers

Cache-Controlstring
Every UCP answer (success or error) except the business profile.
always:no-store

SchemaError

application/jsonUCP-Agent missing or unusable

{
  "code": "invalid_profile_url",
  "content": "The UCP-Agent header must carry profile=\"https://…\"",
  "continue_url": "https://shop.example.com/"
}

application/jsonCategory filter refused

{
  "code": "invalid_request",
  "content": "filters.categories is not supported by this shop; search by query (and filters.price) instead"
}

application/jsonCursor not valid

{
  "code": "invalid_request",
  "content": "pagination.cursor is not valid"
}

application/jsonBody is not valid JSON

{
  "code": "invalid_request",
  "content": "The request is not valid"
}

403Forbidden — invalid_request "The request is not valid" from the platform’s cross-origin write gate: the POST / PUT carried a Monokaido session cookie (accessTo…CrossOriginRejected

404not_found. Either the host serves no UCP — an unknown host, a *.shop.monokaido.com subdomain, a domain without verified DNS or an active certificate, UCP switc…NoBusinessOnHost

413Payload Too Large, from one of two layers: The web server (text/html): a request body over 1 MiB, whatever its content type. Not produced by the API: nginx, th…PayloadTooLarge

415invalid_request "The request is not valid" with HTTP 415: the body declares a charset its parser does not read (JSON: charset= must start with utf-; form-encod…UnsupportedMediaType

422Unprocessable Content — your platform profile: profile_malformed (not JSON, no ucp object, no YYYY-MM-DD ucp.version; remembered for 60 s) or version_unsupport…ProfileProblem

424Failed Dependency — profile_unreachable: your platform profile could not be fetched (network error, timeout, a redirect, a status other than 200, over 256 KiB,…ProfileUnreachable

429Too Many Requests, from one of two layers: The API (application/json, rate_limited, Retry-After: 60): this client IP’s count for the operation passed its limit…RateLimited

500internal_error: an unexpected failure (logged on the server; no detail is sent). A failed write released its Idempotency-Key: retry with the same key.InternalError

502Bad Gateway — the API is down or restarting. Not produced by the API: nginx, the web server in front of the shop, answers it with its own HTML page.BadGateway

503service_unavailable, always with Retry-After: "This shop is temporarily unavailable" (Retry-After: 60) — the company is deactivated or billing-locked, or the s…ServiceUnavailable

504Gateway Timeout — the API did not answer within 60 s. Not produced by the API: nginx, the web server in front of the shop, answers it with its own HTML page. A…GatewayTimeout

Request with curl

curl

curl -X POST 'https://shop.example.com/ucp/v1/catalog/search' \
  -H 'UCP-Agent: profile="https://platform.example.com/.well-known/ucp"' \
  -H 'Accept-Language: sk-SK,sk;q=0.9,en;q=0.8' \
  -H 'Content-Type: application/json' \
  --data '{
    "query": "marlin",
    "pagination": {
      "limit": 2
    },
    "context": {
      "language": "sk",
      "address_country": "SK",
      "currency": "EUR"
    }
  }'

Look products up by identifier

POST/ucp/v1/catalog/lookup

Up to 20 identifiers in one call — variant ids, variant SKUs, product ids, product handles — answered from the product data itself, not from the search listing.

A variant id or SKU matches that variant (inputs[].match: "exact"); a SKU can match variants of several products. A product id or handle (in any language) matches the product’s featured variant ("featured"). An identifier that matched a variant is not tried as a product.
Each product appears once, in the order its first identifier appears in ids, and lists only the variants that were asked for; its price_range, list_price_range and options still describe all its priced variants (within the price filter, when one is set).
Every identifier that matched nothing — unknown, hidden by the shop, or the asked variant has no price — gets an info not_found message whose content is the identifier.
Unlike search, a product the shop does not list in its catalog pages (but would show by its URL) is found, and a product that is not orderable is returned with every variant discontinued.
filters.price works as in search; an asked variant outside it is reported not_found.

Parameters

UCP-Agentheaderstringrequired
Names your platform profile. Required on every /ucp/v1/* operation; never read by the profile and handoff routes.
Details
Grammar — a subset of an RFC 8941 Dictionary, at most 4096 characters:
- members separated by , (spaces or tabs around it allowed; a trailing comma is an error); keys lower-case, matching [a-z*][a-z0-9_\-.*]*;
- the profile member must be an sf-string: profile="https://…", printable ASCII 0x20–0x7E, escapes \" and \\ only;
- other members (tokens, numbers, booleans, strings) and parameters (;key=value) are parsed and ignored; when profile appears twice the last one wins;
- any parse error makes the whole header unusable.
Accepted: profile="https://platform.example.com/.well-known/ucp", version="2026-04-08", profile="https://platform.example.com/.well-known/ucp";sig=abc. Refused: a missing header, profile=https://… (a token, not a string), Profile="…", a=1 b=2, profile="…".
The URL — at most 1000 characters, no whitespace anywhere, starting https://, no user name or password, a non-empty host. Any port, path and query string are accepted (the spec’s /.well-known/ucp path is not enforced). Failing any rule → 400 invalid_profile_url.
The fetch — GET with Accept: application/json and User-Agent: Monokaido-UCP/1.0 (+https://monokaido.com); no redirects followed; only HTTP 200 accepted; at most 256 KiB; 3 s idle, 5 s total; the host must resolve to a public address (private, loopback, link-local and other reserved ranges are refused). Anything else → 424 profile_unreachable. A body that is not JSON, or whose ucp.version is not a YYYY-MM-DD string → 422 profile_malformed; a valid profile of another version → 422 version_unsupported. Only ucp.version and ucp.capabilities (name → [{"version"}], first 20 entries per name, names like dev.ucp.shopping.cart) are read; everything else in it is ignored.
Caching — a fetched profile is cached for its Cache-Control: max-age, clamped to 60 s – 1 h (5 min without one; no-store, no-cache and private are ignored) and served up to 1 h past that while one background refresh runs. A failed fetch (424, or 422 profile_malformed) is remembered for 60 s. A profile of another ucp.version is a valid profile and is cached like one, so after you change its version expect 422 version_unsupported until that entry is refreshed (its max-age, then one more request) — or use a new profile URL. These caches are kept in memory by each API process. Fetching a profile the shop does not know yet is budgeted: 5 new profile URLs per minute per client (IPv4 address, IPv6 /64) and 60 per minute in all → 503 service_unavailable with Retry-After. The full URL string is the cache key, so keep it stable (no per-request query strings).
minLength: 1maxLength: 4096example:profile="https://platform.example.com/.well-known/ucp"
Accept-Languageheaderstring
Fallback for the answer’s language after context.language in the body. The first 10 comma-separated tags are tried in header order (q= weights are ignored, * is skipped) against the languages the shop offers: an exact tag (case-insensitive), then the primary subtag (en-US → en-GB); with no match, the shop’s first language. (A storefront without a language list of its own offers every language of the company: then the primary subtag of the first usable tag is used as it is — a language the company has not set up is answered in its default currency, untranslated — and, with no tag at all, the company’s default language.)
The language decides the currency of every price and the translations. A cart or checkout keeps the language it was created in: a later request changes it only when its body names a context.language different from the stored one, and when that switches the shop language every line is re-added in the new currency and gets a new line id. Once a session has a language, this header alone never switches it. On a storefront without a language list, a session created with no usable tag stores none: each later request is then answered in the language its own tags pick, and a different pick adds the lines again (new line ids). Send context.language on the create.
example:sk-SK,sk;q=0.9,en;q=0.8

Request bodyrequired

The identifiers.

object · CatalogLookupRequest

A batch lookup by identifier. Unknown fields are ignored.

idsarray<string>required
Up to 20 identifiers, each a variant id (any case), a variant SKU (exact, case-sensitive; several products may share one), a product id or a product handle (in any language). Non-string and blank entries are dropped, exact duplicates removed. Empty or missing → 400 invalid_request; more than 20 → 400 request_too_large.
minItems: 1maxItems: 20each item:maxLength: 255
filtersSearchFilters
Filters. Other filters (brand, availability …) are ignored without a message.
contextRequestContext | null
Buyer context. Every field is optional; strings longer than the stated length are cut (counted in code points). Unknown fields (intent, eligibility, payment …) are ignored.

application/jsonFour identifiers of four kinds

{
  "ids": [
    "7C2F9B1E-4A68-4E3D-B2C9-5D1F7A3E8B06",
    "BOTTLE-750-BLK",
    "trek-marlin-9",
    "a2c94e18-5d37-4b6f-8e21-0f9b3c7d6e15"
  ],
  "context": {
    "language": "sk"
  }
}

Responses

200The products found (CatalogLookupResponse) — HTTP 200 also when none was — or the capabilities_incompatible business error.

Response headers

Cache-Controlstring
Every UCP answer (success or error) except the business profile.
always:no-store
ETagstring
An ETag of the body, generated by the API on every response with a body (writes included). The API’s ETag is strong; the web server sends it weak (W/"…") when it compresses the response, which it does for a client that sends Accept-Encoding: gzip. A GET that sends a matching If-None-Match (either form) can be answered 304 Not Modified even though the answer is no-store.
X-RateLimit-Limitinteger
Requests this client IP may make to this operation per 60-second window (600 reads, 300 writes, 60 handoff). Set on every answer that passed the rate limiter.
X-RateLimit-Remaininginteger
The operation’s limit minus this client IP’s current count. The counts live in the API server’s memory; each request is meant to leave the count 60 s after it was made, but the rate limiter (@nestjs/throttler 6.5) drops those pending decrements, for every client, whenever any client’s block ends. Read it as an upper bound and keep steady traffic at half a limit or less.
minimum: 0
X-RateLimit-Resetinteger
Seconds left in a 60-second window the limiter keeps per client IP and operation. The count is not reset when that window ends, so this is not the moment the budget comes back.
minimum: 0

oneOf

Exactly one of

CatalogLookupResponseobject · CatalogLookupResponse
Lookup results. No pagination.
additionalProperties: false
- ucpResponseMetadatarequired
  The ucp object of a successful catalog or cart answer. A missing status means success.
- productsarray<Product>required
  One entry per product, in the order its first identifier appears in ids; each holds only the matched variants.
- messagesarray<Message>
  Present only when non-empty: price_filter_ignored first, then one info not_found per identifier that matched nothing, in ids order.
  minItems: 1
UcpBusinessErrorResponseobject · UcpBusinessErrorResponse
HTTP 200 with no resource. The cases:
- capabilities_incompatible — your profile and this shop share no version of the operation’s root capability (always for carts and checkouts on a shop in catalog mode). Nothing ran; no Idempotency-Key was used.
- not_found — the product, cart (Cart not found or has expired) or checkout (Checkout session not found) does not exist for this shop, is malformed, or (carts) was canceled or expired. An unknown cart_id on POST /checkout-sessions also reads Checkout session not found.
- out_of_stock / item_unavailable — a create in which none of the requested items could be added; no session was created.
- handed_off — converting a cart whose lines the buyer already took to the shop.
Inside a write the last three are stored under the Idempotency-Key like a success (capabilities_incompatible is answered before the key is read).
additionalProperties: false
- ucpErrorResponseMetadatarequired
  The ucp object of a business error. Never has payment_handlers. capabilities is {} for capabilities_incompatible and lists the operation’s root (and its negotiated extensions) otherwise.
- messagesarray<MessageError>required
  Exactly one error message saying why no resource could be returned.
  minItems: 1maxItems: 1
- continue_urlstring (uri)required
  Where a buyer could go instead: the shop home (https://{primary domain}/), or https://{primary domain}/cart for handed_off. Not a handoff link.

application/jsonMatched variants only, plus one not_found

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.catalog.lookup": [
        {
          "version": "2026-04-08"
        }
      ]
    }
  },
  "products": [
    {
      "id": "6f1d2b7c-3a84-4e59-b0c2-8d7e1f4a5b62",
      "handle": "trek-marlin-5",
      "title": "Trek Marlin 5",
      "description": {
        "plain": "Horský bicykel s hliníkovým rámom Alpha Silver, odpruženou vidlicou a 29\" kolesami.",
        "html": "<p>Horský bicykel pre začínajúcich jazdcov.</p><ul><li>Rám Alpha Silver Aluminium</li><li>Vidlica SR Suntour XCT 30, zdvih 100 mm</li><li>Pohon Shimano 2×8</li></ul>"
      },
      "url": "https://shop.example.com/products/trek-marlin-5",
      "price_range": {
        "min": {
          "amount": 69900,
          "currency": "EUR"
        },
        "max": {
          "amount": 71900,
          "currency": "EUR"
        }
      },
      "list_price_range": {
        "min": {
          "amount": 74900,
          "currency": "EUR"
        },
        "max": {
          "amount": 74900,
          "currency": "EUR"
        }
      },
      "media": [
        {
          "type": "image",
          "url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp",
          "alt_text": "Trek Marlin 5, modrá, bočný pohľad"
        },
        {
          "type": "image",
          "url": "https://images.vendor.example/trek/marlin-5-detail.jpg"
        }
      ],
      "options": [
        {
          "name": "Farba",
          "values": [
            {
              "label": "Modrá"
            },
            {
              "label": "Čierna"
            }
          ]
        },
        {
          "name": "Veľkosť",
          "values": [
            {
              "label": "M"
            },
            {
              "label": "L"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "7c2f9b1e-4a68-4e3d-b2c9-5d1f7a3e8b06",
          "sku": "MARLIN5-L-MOD",
          "title": "Modrá / L",
          "description": {
            "plain": "Modrá / L"
          },
          "url": "https://shop.example.com/products/trek-marlin-5",
          "price": {
            "amount": 69900,
            "currency": "EUR"
          },
          "availability": {
            "available": false,
            "status": "out_of_stock"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Modrá"
            },
            {
              "name": "Veľkosť",
              "label": "L"
            }
          ],
          "inputs": [
            {
              "id": "7C2F9B1E-4A68-4E3D-B2C9-5D1F7A3E8B06",
              "match": "exact"
            }
          ]
        }
      ],
      "tags": [
        "Trek"
      ]
    },
    {
      "id": "0b7e3f5a-9c12-4d8e-a6f4-2e1c5b9d7a83",
      "handle": "flasa-na-vodu-750-ml",
      "title": "Fľaša na vodu 750 ml",
      "description": {
        "plain": "Fľaša bez BPA s uzáverom proti vytečeniu & úchytom.",
        "html": "<p>Fľaša bez BPA s <b>uzáverom proti vytečeniu</b> &amp; úchytom.</p>"
      },
      "url": "https://shop.example.com/products/flasa-na-vodu-750-ml",
      "price_range": {
        "min": {
          "amount": 990,
          "currency": "EUR"
        },
        "max": {
          "amount": 990,
          "currency": "EUR"
        }
      },
      "options": [
        {
          "name": "Farba",
          "values": [
            {
              "label": "Čierna"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25",
          "sku": "BOTTLE-750-BLK",
          "title": "Čierna",
          "description": {
            "plain": "Čierna"
          },
          "url": "https://shop.example.com/products/flasa-na-vodu-750-ml",
          "price": {
            "amount": 990,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "in_stock"
          },
          "options": [
            {
              "name": "Farba",
              "label": "Čierna"
            }
          ],
          "inputs": [
            {
              "id": "BOTTLE-750-BLK",
              "match": "exact"
            }
          ]
        }
      ]
    },
    {
      "id": "a2c94e18-5d37-4b6f-8e21-0f9b3c7d6e15",
      "handle": "cyklisticka-prilba-lumen",
      "title": "Cyklistická prilba Lumen",
      "description": {
        "plain": "Ľahká prilba s integrovaným zadným svetlom."
      },
      "url": "https://shop.example.com/products/cyklisticka-prilba-lumen",
      "price_range": {
        "min": {
          "amount": 5990,
          "currency": "EUR"
        },
        "max": {
          "amount": 5990,
          "currency": "EUR"
        }
      },
      "variants": [
        {
          "id": "4a6e2d9c-8b15-4f37-9c48-1e7a5b3d2f90",
          "sku": "LUMEN-HELM-M",
          "barcodes": [
            {
              "type": "UPC",
              "value": "859401234567"
            }
          ],
          "title": "Cyklistická prilba Lumen",
          "description": {
            "plain": "Cyklistická prilba Lumen"
          },
          "url": "https://shop.example.com/products/cyklisticka-prilba-lumen",
          "price": {
            "amount": 5990,
            "currency": "EUR"
          },
          "availability": {
            "available": true,
            "status": "in_stock"
          },
          "inputs": [
            {
              "id": "a2c94e18-5d37-4b6f-8e21-0f9b3c7d6e15",
              "match": "featured"
            }
          ]
        }
      ],
      "tags": [
        "Lumen"
      ]
    }
  ],
  "messages": [
    {
      "type": "info",
      "code": "not_found",
      "content": "trek-marlin-9"
    }
  ]
}

application/jsoncapabilities_incompatible (HTTP 200)

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error",
    "capabilities": {}
  },
  "messages": [
    {
      "type": "error",
      "code": "capabilities_incompatible",
      "content": "The platform and this business share no version of the capability this operation needs",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://shop.example.com/"
}

400Bad Request (Error): invalid_profile_url — the UCP-Agent header is missing or unusable (with continue_url); invalid_request — a field this operation reads has …

Bad Request (Error):

invalid_profile_url — the UCP-Agent header is missing or unusable (with continue_url);
invalid_request — a field this operation reads has the wrong JSON type or value; content names it. Malformed JSON or a top-level JSON primitive says only "The request is not valid". Unknown fields are ignored, never refused. For this operation: request must be an object (also for no body), ids must be a non-empty array, and the price / category filter refusals of search.
request_too_large "ids holds at most 20 identifiers" — more than 20 entries in ids (HTTP 400, not 413).

Response headers

Cache-Controlstring
Every UCP answer (success or error) except the business profile.
always:no-store

SchemaError

application/jsonUCP-Agent missing or unusable

{
  "code": "invalid_profile_url",
  "content": "The UCP-Agent header must carry profile=\"https://…\"",
  "continue_url": "https://shop.example.com/"
}

application/jsonNo ids

{
  "code": "invalid_request",
  "content": "ids must be a non-empty array"
}

application/jsonMore than 20 ids

{
  "code": "request_too_large",
  "content": "ids holds at most 20 identifiers"
}

application/jsonBody is not valid JSON

{
  "code": "invalid_request",
  "content": "The request is not valid"
}