Referencia API (OpenAPI)

Každý endpoint, hlavička, pole a odpoveď UCP API — OpenAPI 3.1 na stiahnutie pre Swagger, Postman a generátory klientov.

Na tejto stránke

Základná adresa a konvencie
Na stiahnutie
Dokument vo vašich nástrojoch
Swagger Editor
Postman a Insomnia
Typovaný klient v TypeScripte
openapi-generator
Operácie

Referencia nižšie sa generuje z dokumentu OpenAPI 3.1, ktorý opisuje UCP API Monokaida: každú operáciu, hlavičku, pole, stavový kód aj príklad. Ten istý dokument je zverejnený na stiahnutie, takže ho môžete importovať do svojich nástrojov alebo z neho vygenerovať typovaného klienta. Celý jeden nákup krok za krokom prechádza Rýchly štart pre vývojárov.

Základná adresa a konvencie

Každý obchod je samostatný server. Obchod poskytuje API na vlastnej doméne: profil obchodu na https://shop.example.com/.well-known/ucp, operácie REST pod https://shop.example.com/ucp/v1. Základ vezmite z endpoint v profile, ktorý uvádza primárnu doménu obchodu. Cesty pod /ucp/continue/ otvára prehliadač kupujúceho, nikdy agent.
Žiadne overovanie. Žiadny API kľúč, OAuth ani cookie: obchod sa určí podľa hostiteľa, ktorého voláte. Každé volanie pod /ucp/v1 uvádza profil vašej platformy v UCP-Agent: profile="https://…".
Hlavičky. Content-Type: application/json pri každej požiadavke s telom; Idempotency-Key pri siedmich zápisoch (nepovinný, dôrazne odporúčaný); Accept-Language je nepovinná.
JSON v UTF-8. Polia, ktoré API nepozná, sa ignorujú. Ak má pole, ktoré API číta, zlý typ JSON, požiadavka sa odmietne s 400 invalid_request a content to pole pomenuje. Niekoľko nápovied, ktoré API nevie použiť, sa namiesto toho zahodí: nečitateľné context.language, context.currency alebo context.address_country, položky discounts.codes či ids, ktoré nie sú reťazce, selected_option_id či selected_destination_id, ktoré nie je reťazec, a id položiek (celý zoznam: Čo sa namiesto odmietnutia upraví).
Poradie kľúčov v objektoch JSON nie je podstatné ani v požiadavkách, ani v odpovediach. Odpovede zostavené z uložených dát — zopakovaný zápis, dokončený, zrušený alebo odovzdaný checkout, uložený buyer či context — prichádzajú v poradí kľúčov typu JSONB v PostgreSQL (kratšie kľúče skôr, potom abecedne).
Peňažné sumy sú celé čísla v najmenších jednotkách meny podľa ISO 4217, s DPH. Katalóg ich zapisuje ako objekt {"amount": 69900, "currency": "EUR"} (699,00 €); košíky a checkouty zapisujú holé celé čísla v item.price a totals[].amount popri jednej mene currency pre celú reláciu. EUR, CZK, PLN a HUF majú dve desatinné miesta (1 990 Ft je 199000), JPY žiadne, KWD tri. Súčet typu discount je záporný.
Časové údaje sú vo formáte ISO 8601 v UTC s milisekundami: "expires_at": "2026-10-27T09:21:30.551Z".
Identifikátory. Košíky a checkouty majú UUID v4 malými písmenami; produkty, varianty, položky, spôsoby dopravy aj objednávky majú tiež UUID. Ak {id} v ceste nie je UUID, odpoveď je rovnaká ako pri neznámej relácii. Token v continue_url má 64 šestnástkových znakov a nikdy nie je identifikátorom relácie.
Dva druhy zlyhania. Chyba protokolu je chybový stav HTTP s {"code", "content", "continue_url"?}. Obchodný výsledok je HTTP 200 (201 pri vytvorenom košíku alebo checkoute) so zoznamom messages[] a so ucp.status: "error", keď sa nevrátil žiadny zdroj. Neznámy košík, checkout či produkt je práve taká odpoveď 200, nikdy 404. Niekoľko odpovedí posiela webový server pred API ako HTML. Všetky kódy sú v kapitole Chyby a správy.
Vyrovnávacia pamäť. Každá odpoveď API má Cache-Control: no-store, okrem profilu obchodu (public, max-age=300).
Limity na IP adresu klienta a operáciu: 600 čítaní, 300 zápisov a 60 požiadaviek odovzdania za minútu, spoločne pre všetky obchody, ktoré z tej IP voláte. Odpovede v rámci limitu nesú X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (v sekundách); 429 nesie Retry-After: 60. Webový server pred API pridáva limit 100 požiadaviek za sekundu na IP adresu (nárazovo najviac 200 navyše) a obmedzuje veľkosť tela na 1 MiB. Podrobnosti sú v kapitole Idempotencia, súbežnosť a limity.

Na stiahnutie

OpenAPI 3.1 (JSON)
Celé UCP API na import do Swagger Editora, Postmana, Insomnie alebo openapi-generatora — podľa adresy alebo ako súbor.
https://help.monokaido.com/ucp/openapi.json
OpenAPI 3.1 (YAML)
Ten istý dokument vo formáte YAML, pre nástroje a revízie, ktoré ho uprednostňujú.
https://help.monokaido.com/ucp/openapi.yaml
Definície nástrojov pre agenta
Nástroje (tools) pre function calling jazykového modelu, mapované na operácie UCP.
https://help.monokaido.com/ucp/tools.json
Celý návod pre LLM
Celý návod pre vývojárov UCP ako jeden súbor Markdown do kontextu jazykového modelu.
https://help.monokaido.com/ucp/llms-full.txt
llms.txt
Obsah celého manuálu pre jazykové modely vo formáte llms.txt.
https://help.monokaido.com/llms.txt

Dokument vo vašich nástrojoch

Súbory sa posielajú s Access-Control-Allow-Origin: *, takže ich podľa adresy naimportujú aj nástroje, ktoré bežia v prehliadači. Server v dokumente je https://{shopDomain} s predvolenou hodnotou shop.example.com: v každom nástroji ho nastavte na obchod, s ktorým sa integrujete, a ukážkovú hodnotu UCP-Agent nahraďte svojím profilom.

Swagger Editor

Otvorte editor.swagger.io, zvoľte File → Import URL a vložte https://help.monokaido.com/ucp/openapi.json. Editor sa hodí na čítanie a kontrolu dokumentu. Jeho Try it out posiela požiadavky z vášho prehliadača a API obchodu požiadavky z cudzích pôvodov nepovoľuje; požiadavky preto posielajte z Postmanu, Insomnie, curl alebo zo svojho servera.

Postman a Insomnia

Použite Import a vložte adresu https://help.monokaido.com/ucp/openapi.json; oba nástroje z operácií vytvoria kolekciu požiadaviek. Potom nastavte základnú adresu kolekcie na pôvod (origin) obchodu a hlavičku UCP-Agent na svoj profil. Oba posielajú požiadavky z desktopovej aplikácie, takže CORS sa ich netýka.

Typovaný klient v TypeScripte

openapi-typescript z dokumentu vytvorí typy a openapi-fetch ich použije v malom typovanom klientovi:

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);
}

Odpoveď 200 je typovaná ako výsledok alebo obchodná chyba, takže vás kontrola typov prinúti ošetriť oboje.

openapi-generator

openapi-generator vytvára klientov pre mnoho jazykov. Potrebuje Javu; obal z npm si samotný generátor stiahne:

# 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

Generátor označuje svoju podporu OpenAPI 3.1 ako beta a počas behu vypisuje varovania; modely, ktorých názov koliduje s cieľovým jazykom, premenuje (v TypeScripte sa schéma Error volá ModelError a RequestContext ModelRequestContext) a vnorené typy odpovedí pomenuje sám (GetCart200Response, CreateCheckout200Response pre každú operáciu checkoutu). Pôvod obchodu odovzdajte klientovi ako základnú cestu: vygenerovaná predvolená hodnota je https://shop.example.com. Vygenerovaný klient podľa stavu nerozozná obchodnú chybu s HTTP 200 od zdroja: pri každej odpovedi 200 kontrolujte aj ucp.status === "error".

Operácie

Príklady volajú https://shop.example.com — namiesto neho použite doménu obchodu, ktorý má UCP zapnuté.

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.

Odpovede

200The business profile.

Hlavičky odpovede

Cache-Controlstring
The business profile may be cached for 5 minutes by anyone.
vždy: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

SchémaBusinessProfile

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

Požiadavka cez 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.

Parametre

UCP-Agenthlavičkastringpovinné
Names your platform profile. Required on every /ucp/v1/* operation; never read by the profile and handoff routes.
Podrobnosti
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: 4096príklad:profile="https://platform.example.com/.well-known/ucp"
Accept-Languagehlavičkastring
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.
príklad:sk-SK,sk;q=0.9,en;q=0.8

Telo požiadavky

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.
  predvolené: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"
  }
}

Odpovede

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.

Hlavičky odpovede

Cache-Controlstring
Every UCP answer (success or error) except the business profile.
vždy: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

Práve jedna z možností

CatalogSearchResponseobject · CatalogSearchResponse
A page of search results.
additionalProperties: false
- ucpResponseMetadatapovinné
  The ucp object of a successful catalog or cart answer. A missing status means success.
- productsarray<Product>povinné
  Newest product first (there is no relevance ranking).
- paginationCatalogPaginationpovinné
  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
- ucpErrorResponseMetadatapovinné
  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>povinné
  Exactly one error message saying why no resource could be returned.
  minItems: 1maxItems: 1
- continue_urlstring (uri)povinné
  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.

Hlavičky odpovede

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

SchémaError

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

Požiadavka cez 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.

Parametre

UCP-Agenthlavičkastringpovinné
Names your platform profile. Required on every /ucp/v1/* operation; never read by the profile and handoff routes.
Podrobnosti
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: 4096príklad:profile="https://platform.example.com/.well-known/ucp"
Accept-Languagehlavičkastring
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.
príklad:sk-SK,sk;q=0.9,en;q=0.8

Telo požiadavkypovinné

The identifiers.

object · CatalogLookupRequest

A batch lookup by identifier. Unknown fields are ignored.

idsarray<string>povinné
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: 20každá položka: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"
  }
}

Odpovede

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

Hlavičky odpovede

Cache-Controlstring
Every UCP answer (success or error) except the business profile.
vždy: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

Práve jedna z možností

CatalogLookupResponseobject · CatalogLookupResponse
Lookup results. No pagination.
additionalProperties: false
- ucpResponseMetadatapovinné
  The ucp object of a successful catalog or cart answer. A missing status means success.
- productsarray<Product>povinné
  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
- ucpErrorResponseMetadatapovinné
  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>povinné
  Exactly one error message saying why no resource could be returned.
  minItems: 1maxItems: 1
- continue_urlstring (uri)povinné
  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).

Hlavičky odpovede

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

SchémaError

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"
}