Princípy a životný cyklus

Táto kapitola opisuje model, na ktorom stojí každé volanie UCP v obchode na Monokaide: ktorý obchod odpovedá, čo sľubuje jeho profil, ako sa predstaví vaša platforma, na čom sa obe strany dohodnú, ako sa správajú košík a checkout a ako nákup z API prejde do vlastnej pokladne obchodu. Presné polia nájdete v Referencii API, všetky kódy v Chybách a správach a opakovanie požiadaviek, súbežnosť a limity v kapitole Idempotencia, súbežnosť a limity.

Príklady používajú obchod https://shop.example.com a platformu, ktorej profil je na adrese https://platform.example.com/.well-known/ucp.

Jeden obchod, jedna doména

Monokaido prevádzkuje veľa obchodov na tých istých serveroch. Požiadavka UCP nájde svoj obchod podľa jedinej veci: podľa názvu hostiteľa, na ktorý bola poslaná. Nie je tu žiadny API kľúč, účet ani id obchodu v ceste. Obchod určuje hlavička Host, s ktorou požiadavka prišla.

Hostiteľ poskytuje UCP, iba kým platí každá z týchto podmienok:

Ak niektorá neplatí, profil a každé volanie /ucp/v1 na danom hostiteľovi odpovie 404 s telom {"code":"not_found","content":"No UCP business on this host"} a stránka continue_url odpovie 404 prázdnou stránkou HTML. Odpoveď je zámerne rovnaká bez ohľadu na príčinu. Adresy Monokaida *.shop.monokaido.com UCP neposkytujú nikdy. Obchod, ktorý má UCP zapnuté, ale jeho firma je deaktivovaná alebo zablokovaná pre nezaplatené predplatné, odpovedá namiesto toho na každú požiadavku 503 service_unavailable s Retry-After: 60.

Cesty používajte presne tak, ako sú zverejnené: /.well-known/ucp (bez lomky na konci) a /ucp/v1/… malými písmenami. Iný zápis môže skončiť na webových stránkach obchodu namiesto API. Obyčajné http:// webový server presmeruje na https:// kódom 301; volajte rovno https://.

Ďalšie domény a primárna doména

Obchod môže mať viac vlastných domén. Každá z nich, na ktorej sa UCP poskytuje, odpovedá za ten istý obchod — rovnaký katalóg aj rovnaké košíky a checkouty: relácia vytvorená na jednej doméne sa nájde aj na ostatných. Každá adresa, ktorú obchod zverejní, však obsahuje jeho primárnu doménu: endpoint v profile, každé continue_url, order.permalink_url, adresy produktov, adresy obrázkov obchodu aj continue_url v chybových odpovediach. Ak sa na samotnej primárnej doméne UCP neposkytuje (DNS nie je overené alebo chýba aktívny certifikát) alebo žiadna doména nie je označená ako primárna, každá doména, na ktorej sa UCP poskytuje, uvádza samu seba.

Obchod objavte cez jeho profil, uložte si endpoint, ktorý zverejní, a každé ďalšie volanie posielajte na tohto hostiteľa. Kupujúcemu odovzdajte presne to continue_url, ktoré ste dostali.

Ako rýchlo sa k vám dostane zmena obchodníka

Zmena, ktorú obchodník uloží v administrácii, platí hneď: zapnutie či vypnutie UCP, vypnutie obchodu alebo jeho kľúča, odobratie domény alebo jej nastavenie ako primárnej. Rovnako hneď platí vypnutie modulu e-shop a deaktivácia či zablokovanie firmy. Novo pridanú doménu API začne poskytovať až vtedy, keď má overené DNS a aktívny certifikát, a odvtedy do 30 sekúnd; aj uplynutie platnosti kľúča sa prejaví najneskôr do 30 sekúnd. Vaša kópia profilu obchodu môže byť až päť minút stará (Cache-Control: public, max-age=300), takže ešte niekoľko minút po vypnutí dostávate spomínaný 404. Odpoveď 404 not_found na profil chápte ako „tento obchod teraz UCP neposkytuje“.

Profil obchodu

GET /.well-known/ucp na doméne obchodu vráti profil obchodu (business profile): obchod opísaný jazykom protokolu. Nepotrebuje hlavičku UCP-Agent ani žiadnu inú, nikdy nepresmerováva, odpovedá s Cache-Control: public, max-age=300 a počíta sa do limitu čítaní (600 požiadaviek za minútu z jednej IP adresy).

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

V profile nie sú: supported_versions (existuje jediná verzia), signing_keys (Monokaido neposiela webhooky a nič nepodpisuje) ani názov či logo obchodu. Medzi obchodmi sa líši iba hostiteľ v endpoint a v katalógovom režime kratší zoznam schopností. Profil sa môže zmeniť, keď obchodník zmení obchod, preto si ho po uplynutí platnosti kópie načítajte znova a nedržte ho naveky.

Profil platformy a hlavička UCP-Agent

Každé volanie pod /ucp/v1 uvádza v hlavičke UCP-Agent profil vašej platformy — JSON dokument, ktorý hostujete vy:

UCP-Agent: profile="https://platform.example.com/.well-known/ucp"

Obchod si dokument stiahne, overí verziu protokolu a schopnosti, ktoré dokument uvádza, porovná so svojimi. Profil obchodu a cesty continue_url túto hlavičku nikdy nečítajú.

Čo musí profil obsahovať

Profil, ktorý odomkne všetko, čo obchod môže ponúknuť:

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.catalog.lookup": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.cart": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.fulfillment": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.discount": [{ "version": "2026-04-08" }]
    }
  }
}

Profil bez ucp.capabilities je platný, ale nič neodomkne: každá operácia potom odpovie capabilities_incompatible.

Hlavička

Hlavička je malá podmnožina slovníka (dictionary) podľa RFC 8941, najviac 4096 znakov:

• Člen profile musí byť reťazec v úvodzovkách, profile="https://…". Zápis bez úvodzoviek profile=https://… sa odmietne.
• Kľúče sa píšu malými písmenami (Profile= sa odmietne). Ostatné členy aj ;parametre sa prijmú a ignorujú.
• Reťazec smie obsahovať iba tlačiteľné znaky ASCII a escape sekvencie \" a \\.
• Keď sa profile objaví dvakrát, platí posledný. Hlavička, ktorú sa na ktoromkoľvek mieste nepodarí rozobrať, sa ignoruje celá.

Adresa musí začínať https://, mať najviac 1000 znakov a nesmie obsahovať medzery ani meno a heslo. Prijme sa akýkoľvek port, cesta aj query string: cesta /.well-known/ucp zo špecifikácie sa nevynucuje, hoci je pre dokument prirodzeným miestom. Hlavička, ktorá niektoré z pravidiel poruší, dostane odpoveď 400 invalid_profile_url.

Ako si ho obchod stiahne

Obchod odmietne hostiteľa profilu, ktorý sa preloží na adresu z týchto rozsahov:

• IPv4: 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10 (carrier-grade NAT), 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.168.0.0/16, 198.18.0.0/15 a všetko od 224.0.0.0 vyššie (multicast a rezervované adresy).
• IPv6: ::/96 (nešpecifikovaná adresa, loopback a adresy kompatibilné s IPv4), fe80::/10, fec0::/10, fc00::/7, ff00::/8 a prefixy NAT64 64:ff9b::/96 a 64:ff9b:1::/48. Adresa IPv4 mapovaná do IPv6 (::ffff:0:0/96) sa posudzuje podľa adresy IPv4, ktorú obsahuje.

Každá iná adresa sa prijme.

Dokument posielajte ako obyčajný, nekomprimovaný JSON v UTF-8 bez BOM: obchod neposiela Accept-Encoding a telo spracuje tak, ako príde.

Cache a rozpočty

• Stiahnutý profil sa uloží na čas podľa max-age z jeho Cache-Control, obmedzený na 60 sekúnd až 1 hodinu; bez neho na 5 minút. no-store, no-cache, private a s-maxage sa ignorujú.
• Po uplynutí tohto času sa uložená kópia používa ešte najviac hodinu, kým na pozadí beží jediné obnovenie. Neúspešné obnovenie ponechá starú kópiu.
• Neúspešné stiahnutie si obchod pamätá 60 sekúnd: počas nich odpovedá tou istou chybou bez ďalšieho sťahovania.
• Profil s inou verziou protokolu sa ukladá ako každý platný. Keď verziu opravíte, obchod to uvidí po uplynutí platnosti svojej kópie — podľa vášho max-age, najviac do hodiny.
• Kľúčom cache je celý reťazec adresy vrátane query stringu a cache drží server Monokaida, nie každý obchod zvlášť.
• Sťahovanie profilov, ktoré server ešte nepozná, má rozpočet: 5 nových adries profilu za minútu na klienta (jedna IPv4 adresa alebo jedna IPv6 /64) a spolu 60 za minútu. Nad rozpočet obchod odpovie 503 service_unavailable s Retry-After. Už známy profil na rozpočet nikdy nečaká.

Keď sa profil nedá použiť

Každá z týchto odpovedí nesie continue_url na úvodnú stránku obchodu. Kontroly prebiehajú v tomto poradí: najprv obchod (neznámy hostiteľ odpovie 404 aj bez hlavičky), potom hlavička a stiahnutie profilu, potom verzia a nakoniec vyjednávanie.

Čo hlavička nerobí

Hlavička vašu platformu identifikuje, ale neoveruje. Monokaido nekontroluje žiadny podpis, kľúč ani certifikát, takže ktokoľvek môže uviesť akúkoľvek adresu profilu. Hodnoty Idempotency-Key sú viazané na adresu profilu, relácie však nie: k relácii stačí jej id, preto ho držte v tajnosti. Viac v kapitole Bezpečnosť a ochrana údajov.

Vyjednávanie schopností

Na každú požiadavku sa odpovedá tým, čo podporujú obe strany. Obchod uvádza svoje schopnosti (capabilities) v profile obchodu, vy svoje v profile platformy a pri každej požiadavke sa urobí ich prienik.

Vyjednávanie postupuje takto:

1. Verzia. ucp.version vášho profilu sa musí ako reťazec rovnať 2026-04-08. Čokoľvek iné, staršie aj novšie, skončí chybou 422 version_unsupported skôr, ako sa spustí čokoľvek ďalšie.
2. Prienik. Schopnosť obchodu je aktívna, keď ju váš profil uvádza — presne, s rozlišovaním veľkosti písmen — vo verzii, ktorú uvádzajú obe strany. Vyhrá najvyššia spoločná verzia; dnes je to vždy 2026-04-08.
3. Orezanie. Rozšírenie zostane aktívne, iba kým je aktívny aspoň jeden z jeho rodičov, ako ich uvádza obchod; opakuje sa to, kým sa nič nezmení. dev.ucp.shopping.discount vydrží aj so samotným košíkom, dev.ucp.shopping.fulfillment potrebuje checkout. Vaše vlastné extends nemá vplyv.
4. Zvyšok. Schopnosti, ktoré uvádza iba váš profil (napríklad vlastné názvy com.example.…), sa ignorujú.

Výsledok vyjednávania sa nikde neukladá. Pri každej požiadavke sa vyjednáva znova s kópiou vášho profilu, ktorú obchod práve má.

Obálka ucp

Každá JSON odpoveď okrem chyby protokolu obsahuje objekt ucp:

Poradie kľúčov v JSON objekte nemá žiadny význam. Odpovede zostavené z uložených údajov — zápis zopakovaný s jeho Idempotency-Key, uzavretý checkout, relácia po odovzdaní — prichádzajú s kľúčmi v poradí PostgreSQL JSONB (najprv kratšie kľúče, potom abecedne), takže ani ucp nemusí byť prvý. Každú odpoveď čítajte podľa kľúčov.

S profilom, ktorý uvádza všetkých šesť schopností:

Rozšírenie, ktoré ste nevyjednali, v zozname chýba. Zápis zopakovaný s tým istým Idempotency-Key vráti obálku uloženú s prvou odpoveďou.

Keď schopnosť chýba

Koreňová schopnosť operácie. Odpoveď je HTTP 200 s ucp.status: "error", ucp.capabilities: {}, správou capabilities_incompatible a continue_url na úvodnú stránku obchodu. Nič sa nevykoná: telo sa nekontroluje a žiadny Idempotency-Key sa nepoužije. Rovnako odpovedá každé volanie košíka a checkoutu v obchode v katalógovom režime.

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

Rozšírenie. Jeho polia sa ignorujú bez kontroly a v odpovedi chýba jeho objekt:

• Bez dev.ucp.shopping.fulfillment checkout nemá fulfillment, v súčtoch nemá dopravu a na pripravenosť nepotrebuje adresu. Dopravu si kupujúci vyberie v obchode.
• Bez dev.ucp.shopping.discount košík ani checkout nemá discounts, poslané kódy sa ignorujú a kód, ktorý už v relácii bol, sa pri najbližšom PUT odstráni — súčty potom žiadnu zľavu neukazujú.

Ak zámerne nechcete menej, uveďte všetkých šesť schopností vo verzii 2026-04-08.

Košík a checkout

UCP má dva druhy relácie. Obe nacení obchod cez vlastný košík podľa svojich cien, DPH, prirážok, skladu a pravidiel zliav — podľa tých istých pravidiel ako na webe.

Košík použite na zbieranie položiek, kým neviete, kto bude kupovať, alebo keď chcete kupujúcemu odovzdať nákup tak, ako je. Checkout použite, keď máte e-mail kupujúceho a chcete dopravu a konečné súčty — a vždy, keď chcete zistiť, či nasledovala objednávka, pretože stav completed môže dosiahnuť iba checkout. Košík nie je podmienkou: checkout môžete vytvoriť rovno z line_items.

Keď sa nedá kúpiť žiadna položka

Vytvorenie — košíka, checkoutu z line_items alebo checkoutu z košíka —, pri ktorom zlyhajú všetky položky, nevytvorí žiadnu reláciu. Odpoveď je HTTP 200 s ucp.status: "error", bez id a s jedinou správou so závažnosťou unrecoverable: out_of_stock, ak bola každá správa požiadavky out_of_stock, inak item_unavailable. Jej continue_url vedie na úvodnú stránku obchodu. Prázdne line_items takým zlyhaním nie je: vytvorí košík bez položiek alebo checkout, ktorý zostane incomplete, kým položky nedostane.

Identifikátory

Položky v odpovedi prichádzajú v poradí obchodu, nie vo vašom: párujte ich podľa item.id, nikdy podľa pozície. path správy, napríklad $.line_items[1], ukazuje do odpovede, v ktorej prišla.

O svojom tovare toho položka povie málo:

• item.title je názov produktu v jazyku relácie — nikdy nie názov variantu. Dve položky jedného produktu (bicykel v modrej M a v modrej L) sa volajú rovnako. Variant, ktorý ste vybrali — jeho title, options a sku z katalógu —, si uchovajte podľa item.id alebo id dohľadajte cez POST /ucp/v1/catalog/lookup ({"ids": [item.id, …]}), skôr než košík ukážete kupujúcemu.
• item.id sa overuje voči produktom firmy, nie voči katalógu tohto obchodu. Položka sa prijme pre každý aktívny variant publikovaného produktu firmy; vylučovacie filtre a blokované kategórie obchodu, ktoré produkty skrývajú vo vyhľadávaní a v lookupe, sa na ňu neuplatnia. Používajte iba id variantov, ktoré ste dostali z katalógu tohto obchodu: id uložené z iného obchodu tej istej firmy sa tu môže prijať.
• quantity a item.price počítajú jednotku, ktorú obchod predáva. Pri tovare predávanom v baleniach (napríklad krabica podlahových dosiek) je to jedno balenie. UCP obsah balenia nezverejňuje, takže množstvo v štvorcových metroch cez UCP na balenia neprepočítate.

Z košíka checkout

POST /ucp/v1/checkout-sessions s {"cart_id": "<id košíka>"} urobí z košíka checkout. cart_id sa uplatní, iba keď je vyjednaná schopnosť košíka; inak je požiadavka priamym vytvorením a potrebuje line_items.

• K jednému košíku jeden otvorený checkout. Na opakovaný prevod košíka obchod odpovie otvoreným checkoutom s HTTP 200 a z novej požiadavky sa nepoužije nič: checkout meňte cez PUT.
• Otvorený checkout košíka, ktorému uplynula platnosť, sa najprv zruší a vytvorí sa nový (201).
• Košík, ktorý si kupujúci už odniesol do obchodu (alebo ktorého checkout si odniesol), sa odmietne s 200, ucp.status: "error" a správou handed_off; continue_url odpovede vedie na stránku košíka obchodu. Ak má košík ešte otvorený checkout, obchod namiesto toho odpovie týmto checkoutom.
• Na neznáme, zrušené alebo vypršané cart_id obchod odpovie 200 not_found s textom Checkout session not found.
• Checkout má vlastné položky s novými id. Košík zostane, aký bol, a jeho neskoršie zmeny sa do checkoutu nedostanú: po prevode pracujte s checkoutom.

Stavy checkoutu

Stavy ready_for_complete a complete_in_progress zo špecifikácie sa nikdy neobjavia: API samo checkout nikdy nedokončí.

Čo je potrebné na pripravenosť

Pripravený checkout má stav requires_escalation. Vždy nesie payment_required (závažnosť requires_buyer_input) a continue_url:

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "3d7b9e2a-6f14-4c58-9b3e-8a2f1c6d4e97",
  "status": "requires_escalation",
  "currency": "EUR",
  "line_items": [
    {
      "id": "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
      "item": {
        "id": "1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47",
        "title": "Trek Marlin 5",
        "price": 69900,
        "image_url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 69900
        },
        {
          "type": "total",
          "amount": 69900
        }
      ]
    },
    {
      "id": "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49",
      "item": {
        "id": "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25",
        "title": "Fľaša na vodu 750 ml",
        "price": 990
      },
      "quantity": 2,
      "totals": [
        {
          "type": "subtotal",
          "amount": 1980
        },
        {
          "type": "total",
          "amount": 1980
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "amount": 71880
    },
    {
      "type": "discount",
      "amount": -5844,
      "display_text": "JESEN10"
    },
    {
      "type": "fulfillment",
      "amount": 490
    },
    {
      "type": "total",
      "amount": 66526
    }
  ],
  "messages": [
    {
      "type": "error",
      "code": "payment_required",
      "content": "Payment is completed on the shop website — continue there to place the order",
      "severity": "requires_buyer_input"
    }
  ],
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://shop.example.com/obchodne-podmienky",
      "title": "Obchodné podmienky"
    },
    {
      "type": "privacy_policy",
      "url": "https://shop.example.com/ochrana-osobnych-udajov",
      "title": "Ochrana osobných údajov"
    }
  ],
  "buyer": {
    "first_name": "Jana",
    "last_name": "Nováková",
    "email": "jana.novakova@example.com",
    "phone_number": "+421 905 123 456"
  },
  "context": {
    "language": "sk",
    "address_country": "SK"
  },
  "fulfillment": {
    "methods": [
      {
        "id": "shipping",
        "type": "shipping",
        "line_item_ids": [
          "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
          "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
        ],
        "destinations": [
          {
            "id": "destination",
            "street_address": "Hlavná 12",
            "address_locality": "Bratislava",
            "postal_code": "811 01",
            "address_country": "SK",
            "first_name": "Jana",
            "last_name": "Nováková"
          }
        ],
        "selected_destination_id": "destination",
        "groups": [
          {
            "id": "default",
            "line_item_ids": [
              "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
              "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
            ],
            "options": [
              {
                "id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75",
                "title": "GLS kuriér",
                "description": "Doručenie na adresu do 1–2 pracovných dní",
                "totals": [
                  {
                    "type": "total",
                    "amount": 490
                  }
                ]
              },
              {
                "id": "6b2d9f4e-3a17-4c68-9d5b-1f8e3a7c2b40",
                "title": "Packeta – výdajné miesto",
                "description": "Delivery in 2–3 business days",
                "totals": [
                  {
                    "type": "total",
                    "amount": 290
                  }
                ]
              }
            ],
            "selected_option_id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75"
          }
        ]
      }
    ]
  },
  "discounts": {
    "codes": [
      "JESEN10"
    ],
    "applied": [
      {
        "code": "JESEN10",
        "title": "JESEN10",
        "amount": 5844,
        "method": "across"
      }
    ]
  },
  "continue_url": "https://shop.example.com/ucp/continue/9bbd3dedf887f93c6287fa7f4b8de141501155714c3b2050bb83551e36ec780b",
  "expires_at": "2026-10-27T09:21:30.551Z"
}

Ako sa stav určuje

• Stav otvoreného checkoutu sa určí nanovo pri každom vytvorení, PUT, GET aj POST …/complete, podľa aktuálneho stavu relácie. Akákoľvek správa error so závažnosťou recoverable z neho urobí incomplete; inak je requires_escalation. Po odovzdaní sa už nemení (pozri Po odovzdaní je relácia zmrazená).
• Správy k položkám — out_of_stock, item_unavailable, quantity_adjusted, vat_mix_not_allowed — sú iba v odpovedi na zápis, ktorý ich spôsobil. V tej odpovedi je položka už odstránená, znížená alebo ponechaná bez zmeny, takže ďalší GET môže ten istý checkout vrátiť ako requires_escalation. Na správy reagujte v odpovedi na svoj zápis.
• POST …/complete objednávku nevytvorí. Ako GET odpovie aktuálnym stavom, určeným nanovo, a nepredĺži platnosť.
• completed vzniká iba objednávkou, ktorú kupujúci vytvorí v obchode.

Uzavretý checkout

completed a canceled sú konečné. Každá odpoveď je HTTP 200, stav sa nemení, chýba continue_url aj ucp.status:

Nič sa nezapíše. Objednávka dokončeného checkoutu sa cez UCP nikdy nezruší.

Košík nemá stav

Odpoveď s košíkom nemá status. Na zrušenie košíka obchod odpovie košíkom v stave, v akom bol — aj s continue_url, ktoré už nefunguje. Odvtedy, rovnako ako po uplynutí platnosti, obchod na každé volanie odpovie 200 not_found s Cart not found or has expired. Zrušenie košíka nezruší checkout, ktorý z neho vznikol: ten zrušte samostatne.

Zmena relácie

PUT uvádza polia; pole, ktoré vynechá, si ponechá uloženú hodnotu. Niektoré polia však uložený obsah nahrádzajú celý:

Položky.

• Zoznam nahradí položky relácie. Párujú sa podľa variantu; položka, ktorú vynecháte, sa odstráni. id, ktoré pri položke pošlete, sa ignoruje.
• quantity je kladné celé číslo, predvolene 1. Množstvo nad 999 sa bez správy zníži na 999; viac položiek s tým istým variantom sa sčíta a súčet nad 999 sa zníži s upozornením quantity_adjusted.
• V jednej požiadavke najviac 100 položiek (pri viacerých obchod odpovie 400).

Kupujúci. Posielajte vždy celého kupujúceho: {"buyer":{"first_name":"Jana"}} vymaže uložený e-mail. E-mail sa uloží tak, ako prišiel, a ak je platný, malými písmenami; neplatný sa hlási ako missing $.buyer.email.

Doprava (fulfillment, s rozšírením):

• Číta sa prvý spôsob, ktorého type je "shipping" alebo chýba. Iné typy vrátane pickup sa ignorujú. Číta sa iba prvých 10 spôsobov a prvých 10 cieľov doručenia spôsobu.
• Jeho cieľom doručenia je ten, ktorý určuje selected_destination_id, inak prvý. Uloží sa celá adresa a jej id sa zmení na "destination". Kontroluje sa iba krajina tohto cieľa: na krajinu, ktorú obchod nerozpozná, odpovie 400 so žiadosťou o kód ISO 3166-1 alpha-2, napríklad "SK".
• groups[0].selected_option_id vyberie možnosť; null ju zruší; chýbajúca alebo prázdna hodnota nič nemení.
• Možnosti sú aktívne spôsoby dopravy obchodu pre tento obchod, filtrované podľa krajiny cieľa (bez cieľa sa podľa krajiny zatiaľ nefiltruje) a podľa vlastných pravidiel spôsobov pre produkty, v poradí obchodu.
• Vybraná možnosť, ktorá sa už neponúka — napríklad po zmene krajiny — zostane vybraná: odpoveď ukazuje selected_option_id: null a invalid_option, kým nevyberiete znova.
• title možnosti je názov spôsobu dopravy v jazyku relácie. Jej description je popis spôsobu v tomto jazyku, inak vlastný popis spôsobu, ktorý môže byť v inom jazyku obchodu, inak anglická veta zostavená z odhadu doručenia (Delivery in 2–3 business days); najviac 300 znakov a chýba, ak nie je nič z toho. Ukazujte title, prípadne si description preložte sami.

Zľavové kódy (discounts, s rozšírením):

• Pri každom vytvorení a PUT sa kódy skúšajú v poradí a uplatní sa prvý, ktorý obchod prijme. Každý ďalší dostane upozornenie discount_code_combination_disallowed. Odmietnutý kód dostane discount_code_expired, discount_code_user_ineligible alebo discount_code_invalid a skúsi sa ďalší. Tieto správy sú upozornenia: checkout nikdy nedržia v stave incomplete. discounts.applied obsahuje najviac jednu položku, a to iba vtedy, keď uplatnený kód niečo odpočíta.
• Najviac 10 kódov (pri viacerých obchod odpovie 400), každý skrátený na 50 znakov; duplicity sa odstránia bez ohľadu na veľkosť písmen. GET kódy znova neuplatňuje.
• V relácii bez položiek sa neuplatní žiadny kód: discounts.applied je prázdne a súčty žiadnu zľavu neukazujú. Kódy zostanú uložené a pri ďalšom vytvorení alebo PUT sa skúsia znova.

Platnosť. Každý PUT košíka predĺži platnosť košíka na 7 dní odteraz a každý PUT checkoutu platnosť checkoutu na 24 hodín odteraz. PUT checkoutu s {} znova uplatní kódy, znova nacení dopravu a predĺži ho; PUT košíka vždy potrebuje jeho položky.

Peniaze, súčty a daň

Každá suma je celé číslo v najmenších jednotkách meny currency, ktorá je pri nej, podľa ISO 4217:

Sumy sa zaokrúhľujú tak, že polovica sa zaokrúhli smerom od nuly. Sú s DPH: item.price je jednotková cena s DPH, súčty položiek sú s DPH a prirážky obchodu sú už v nich. Samostatný riadok dane ani suma bez DPH neexistuje.

Položky pred total dajú v súčte vždy presne total. Zľava sa na položky nerozpočítava: súčty položiek zostávajú bez zľavy.

Tri pravidlá sa správajú rovnako ako pokladňa obchodu a môžu prekvapiť:

• Percentuálny kód je percentom zo sumy bez DPH, odpočíta sa však od sumy s DPH. Bicykel za 699,00 € a dve fľaše po 9,90 € dajú medzisúčet 718,80 €; pri 23 % DPH je medzisúčet bez DPH 584,39 €, takže 10 % kód odpočíta 58,44 €, nie 71,88 €.
• Hranica dopravy zadarmo sa porovnáva s medzisúčtom bez DPH, pred odpočítaním zľavy — ak ju však obchod pri spôsobe dopravy nastavil vrátane DPH a beží na Storefront v2, s medzisúčtom s DPH (subtotal relácie). Na klasickom storefronte sa aj vtedy porovnáva medzisúčet bez DPH.
• Minimálna hodnota objednávky pri kóde sa tiež porovnáva s medzisúčtom bez DPH, pred odpočítaním zľavy. Košík za 718,80 € z príkladu vyššie má medzisúčet bez DPH 584,39 €, takže kód s minimálnou hodnotou objednávky 600 € sa odmietne s discount_code_user_ineligible.

Nenacení sa: príplatok za spôsob platby, ktorý si kupujúci vyberie v obchode. Kupujúci tam môže zmeniť aj položky či dopravu, takže konečná objednávka sa môže od posledného súčtu z UCP líšiť.

Jazyk a mena

Jazyk relácie určuje preklady (názvy produktov, spôsobov dopravy, právnych odkazov) a menu každej ceny. Vyberie sa pri vytvorení relácie:

1. context.language z tela požiadavky, ak je to jazyková značka v tvare sk alebo en-GB (najviac 35 znakov; reťazec v inom tvare sa potichu zahodí);
2. potom značky z Accept-Language v poradí hlavičky — prvých 10, váhy q sa ignorujú, * sa preskočí.

Vyhrá prvý kandidát, ktorý obchod ponúka: presná značka (bez ohľadu na veľkosť písmen), inak prvý jazyk obchodu s rovnakou hlavnou časťou (en-US → en alebo en-GB). Ak sa nič nezhoduje, použije sa prvý jazyk obchodu. Obchod bez vlastného zoznamu jazykov vezme hlavnú časť prvého kandidáta (en-GB → en) a bez kandidáta odpovedá v predvolenom jazyku firmy; jazyk, ktorý firma nemá nastavený, sa nacení ako predvolený. Relácia vytvorená v takom obchode bez kandidáta si jazyk neuloží: kým ho niektorá požiadavka neurčí, odpovedá sa na každú ďalšiu v jazyku, ktorý vyberie jej vlastná hlavička Accept-Language, a iný výber položky pridá znova (nové id, prípadne iná mena). Pri vytvorení preto posielajte context.language.

• Mena. Každý jazyk obchodu má svoju menu. context.currency menu cien nikdy nemení: v košíku a checkoute sa iba vráti späť a v katalógu určuje menu filters.price (bez neho sú hranice v mene odpovede). Ak chcete ceny v inej mene, žiadajte jazyk, v ktorom obchod v tej mene predáva.
• Jazyk zostáva. Keď relácia jazyk raz má, vyberá sa znova iba vtedy, keď telo požiadavky pošle context.language odlišný (bez ohľadu na veľkosť písmen) od context.language uloženého v relácii. Výber potom prebehne ako vyššie, s Accept-Language tejto požiadavky. Samotná hlavička Accept-Language jazyk nikdy neprepne a opätovné poslanie toho istého jazyka nie je zmena. Checkout vytvorený z košíka si ponechá jazyk košíka.
• Prepnutie všetko prepočíta. Keď výber určí iný jazyk, položky sa pridajú znova v novom jazyku a mene: dostanú nové id aj aktuálne ceny obchodu a kódy sa uplatnia znova.
• Jazyk sa nevracia. context.language zopakuje, čo ste poslali, aj jazyk, ktorý obchod neponúka. Skutočný jazyk prezradí iba currency a preložené názvy.

context.language pošlite pri vytvorení relácie a držte sa ho. Ak kupujúci jazyk zmení, počítajte s novými id položiek a novými cenami.

Keď sa zmení sklad alebo cena

Reláciu nacení košík obchodu, no nie každé volanie všetko znova preverí:

• Položka odstránená ako vypredaná v relácii už nie je: keď sa tovar vráti na sklad, pošlite ju znova v ďalšom PUT.
• Správy k položkám sú iba v odpovedi na zápis, ktorý ich spôsobil. Namiesto čakania na správu porovnávajte totals medzi odpoveďami.
• Checkout, ktorý dlho udržiavate otvorený cez PUT, si ponechá ceny z chvíle, keď doň položky prišli. Ak chcete položku naceniť znova, vynechajte ju v jednom PUT a v ďalšom ju pošlite znova (dostane nové id), alebo začnite nový checkout: z line_items alebo z košíka, keď zrušíte jeho otvorený checkout.
• Odovzdanie pridá položky do košíka kupujúceho za ceny obchodu platné v tej chvíli, preto je záväzná cena v pokladni obchodu.

Tesne pred odovzdaním checkoutu pošlite PUT s jeho aktuálnymi line_items: odpoveď už má znova preverený sklad aj zľavový kód (jednotkové ceny iba v obchode so živými cenami). Kupujúcemu ukážte tieto súčty.

Katalógový režim

Obchodník môže obchod prevádzkovať ako katalóg: produkty a ceny sú viditeľné, ale nič sa nedá kúpiť. Pre UCP to platí, keď je obchod v katalógovom režime a beží na Storefront v2. Taký obchod uvádza iba dev.ucp.shopping.catalog.search a dev.ucp.shopping.catalog.lookup:

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

• Vyhľadávanie, vyhľadanie podľa identifikátorov (lookup) aj detail produktu fungujú ako zvyčajne; dostupnosť stále zodpovedá skladu.
• Na každú operáciu košíka a checkoutu vrátane GET obchod odpovie HTTP 200 capabilities_incompatible a nič sa nevykoná. Relácie vytvorené pred zapnutím už cez API nedosiahnete.
• continue_url vydané pred zapnutím pošle kupujúceho na úvodnú stránku obchodu a do košíka mu nič nepridá.

Platnosť a jej uplynutie

GET, complete ani cancel reláciu nikdy nepredĺžia. expires_at je ISO 8601 v UTC s milisekundami, napríklad 2026-10-27T09:21:30.551Z. Predvolená platnosť checkoutu v špecifikácii je 6 hodín; v Monokaide je to 24 hodín. Uplynutie sa vyhodnocuje až pri ďalšej požiadavke: v samotnej chvíli termínu sa nič nedeje a checkout zruší až najbližšia požiadavka, ktorá sa ho dotkne.

Odovzdanie kupujúcemu

Monokaido cez UCP platbu neprijíma. Pripravený checkout sa odovzdá kupujúcemu, ktorý nákup dokončí na webe obchodu, spôsobmi platby obchodu.

Odkaz

continue_url vyzerá ako https://shop.example.com/ucp/continue/9bbd3ded…ec780b: primárna doména obchodu a 64-znakový hexadecimálny token.

• Token je samostatné tajomstvo, nikdy nie id relácie. Počas životnosti relácie sa nemení.
• Je v každej odpovedi košíka a v každej odpovedi otvoreného checkoutu; v checkoute completed a canceled chýba.
• Je to stránka pre prehliadač človeka. Odovzdajte ju kupujúcemu — ako odkaz alebo tlačidlo — vo chvíli, keď je checkout requires_escalation. Nevolajte ju zo svojho servera.
• Funguje pri každej otvorenej relácii vrátane checkoutu v stave incomplete a prvá položka, ktorá sa dostane do košíka kupujúceho, reláciu zmrazí v stave, ktorý má práve vtedy (pozri Po odovzdaní je relácia zmrazená). Príliš skoro ukázaný odkaz preto zanechá checkout incomplete, ktorý už nedokončíte. To isté platí pre odkaz košíka: keď z košíka vytvoríte checkout, continue_url košíka odovzdá tento checkout, preto odkaz košíka („pozrieť košík“) po prevode už neukazujte.

Čo sa stane, keď ho kupujúci otvorí

1. Obchod vráti malú stránku. Jej načítanie nič nemení, takže náhľad odkazu ani prednačítanie neuškodí.
2. Skript stránky pridá položky relácie a jej uplatnený zľavový kód do košíka kupujúceho v tomto prehliadači: do zákazníckeho košíka, ak je kupujúci v obchode prihlásený v tejto karte prehliadača, inak do košíka hosťa v tomto prehliadači. Bez JavaScriptu stránka ukáže iba odkaz do obchodu a nepridá nič.
3. Prehliadač pokračuje do pokladne obchodu (pri checkoute), do košíka obchodu (pri košíku) alebo na úvodnú stránku (obchod v katalógovom režime). Odkaz košíka, z ktorého vznikol otvorený checkout, odovzdá tento checkout.

Stránka potrebuje JavaScript a úložisko prehliadača pre doménu obchodu: košík hosťa obchod pozná iba podľa id uloženého v localStorage tohto prehliadača a prihlásenú kartu podľa prihlásenia v jej sessionStorage. Položky preto skončia v košíku toho prehliadača — a toho oddielu úložiska —, ktorý odkaz otvoril. Prehliadač vnútri aplikácie alebo WebView mobilnej aplikácie má vlastný košík, preto musí kupujúci nákup dokončiť v tom istom prehliadači, alebo odkaz otvoriť rovno v systémovom prehliadači. Kde je úložisko zablokované, položky skončia v košíku, ktorý žiadna stránka obchodu neukáže, a relácia sa aj tak zmrazí: vytvorte nový checkout.

Košík kupujúceho si ponechá všetko ostatné, čo v ňom bolo. Pri variante, ktorý v ňom už je, sa množstvá sčítajú (najviac do 999) a kód relácie, ak pre tento košík platí, nahradí kód, ktorý si kupujúci uplatnil sám. Položku, ktorú košík obchodu odmietne — medzičasom sa vypredala, na sčítané množstvo nie je dosť tovaru na sklade alebo by v košíku vznikla zmes tovaru s nulovou a nenulovou DPH, ktorú obchod nepovoľuje —, stránka bez upozornenia preskočí. Ak košík kupujúceho už obsahuje tovar v inej mene, položky sa pridajú v jazyku toho košíka, pokiaľ sa v ňom ceny v tej mene počítajú; inak sa nepridá nič a kupujúci skončí na stránke košíka.

Čo sa prenesie a čo nie

Kupujúci svoje údaje v pokladni obchodu zadá znova a môže tam objednávku aj zmeniť. Povedzte mu to: čo vaša platforma zozbierala, sa vopred nevyplní.

Viacnásobné otvorenie odkazu

• Opätovné načítanie stránky, druhé kliknutie alebo druhá karta v tom istom prehliadači nepridá nič ďalšie. Karta, v ktorej je kupujúci prihlásený, sa počíta ako iný košík.
• Iný prehliadač alebo zariadenie, ktoré odkaz otvorí, dostane položky ešte raz, do vlastného košíka. Kým je relácia otvorená, môže to urobiť ktokoľvek, kto odkaz má, preto ho zdieľajte iba s kupujúcim.
• Keď je relácia dokončená, zrušená alebo vypršaná, odkaz vráti 410; keď obchod UCP prestane poskytovať, odpovie 404.

Po odovzdaní je relácia zmrazená

Keď je v košíku kupujúceho aspoň jedna položka, relácia sa už nemení. Odovzdanie, ktoré nepridalo ani jednu položku, ju nechá tak, ako bola.

Jej expires_at sa už nedá predĺžiť. GET vám nepovie, či kupujúci odkaz otvoril; PUT áno (handed_off), no v relácii, ktorá odovzdaná nebola, reláciu zmení a predĺži.

Prihlásený kupujúci a hosť

Stránka vidí iba prihlásenie v tej karte prehliadača, v ktorej sa otvorí. Odkaz otvorený v novej karte — bežný prípad — naplní košík hosťa v tomto prehliadači, ktorý ukazuje aj táto karta obchodu. Ak sa kupujúci potom prihlási až v pokladni obchodu, obchod košík hosťa zlúči do zákazníckeho košíka a výsledná objednávka checkout UCP už dokončiť nemôže: checkout si ponechá stav, v ktorom bol odovzdaný (zvyčajne requires_escalation), kým nevyprší. Samotnú objednávku to neovplyvní.

Dokončenie objednávkou

Kedy sa checkout stane dokončeným

Checkout sa stane completed, keď kupujúci v pokladni obchodu vytvorí objednávku z košíka, ktorý naplnilo odovzdanie, a táto objednávka obsahuje aspoň jeden z variantov relácie. Na množstvách nezáleží. Ukáže to najbližšie čítanie; webhooky ani schopnosť pre objednávky neexistujú, takže to zistíte čítaním checkoutu.

• Dokončí sa iba checkout, košík nikdy. Ak chcete poznať výsledok, odovzdajte checkout.
• completed znamená, že objednávka bola vytvorená, nie zaplatená. Nastaví sa hneď, ako obchod začne platbu, pri akomkoľvek spôsobe platby, a na výsledok platby nečaká.
• Dokončenie nie je zaručené. Beží po uložení objednávky, keď obchod začal platbu a odovzdal objednávku do svojho ERP, takže môže za objednávkou zaostať o čas, ktorý tieto kroky zaberú. Ak zlyhá, chyba sa iba zapíše do logu na strane Monokaida a checkout si ponechá svoj stav: objednávka môže existovať aj pri checkoute, ktorý nikdy nebude completed.
• Obchod pošle svoj bežný e-mail s potvrdením objednávky na adresu, ktorú kupujúci zadal v jeho pokladni.

Čo odpoveď obsahuje

Odpoveď je posledná, ktorú ste pred odovzdaním dostali, so status: "completed", messages: [], bez continue_url a s order:

line_items a totals sú stále vaša posledná ponuka, nie objednávka: kupujúci mohol v obchode zmeniť množstvá, dopravu aj platbu. Ponuku nikdy nevydávajte za súčet objednávky.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "3d7b9e2a-6f14-4c58-9b3e-8a2f1c6d4e97",
  "buyer": {
    "email": "jana.novakova@example.com",
    "last_name": "Nováková",
    "first_name": "Jana",
    "phone_number": "+421 905 123 456"
  },
  "links": [
    {
      "url": "https://shop.example.com/obchodne-podmienky",
      "type": "terms_of_service",
      "title": "Obchodné podmienky"
    },
    {
      "url": "https://shop.example.com/ochrana-osobnych-udajov",
      "type": "privacy_policy",
      "title": "Ochrana osobných údajov"
    }
  ],
  "status": "completed",
  "totals": [
    {
      "type": "subtotal",
      "amount": 71880
    },
    {
      "type": "discount",
      "amount": -5844,
      "display_text": "JESEN10"
    },
    {
      "type": "fulfillment",
      "amount": 490
    },
    {
      "type": "total",
      "amount": 66526
    }
  ],
  "context": {
    "language": "sk",
    "address_country": "SK"
  },
  "currency": "EUR",
  "messages": [],
  "discounts": {
    "codes": [
      "JESEN10"
    ],
    "applied": [
      {
        "code": "JESEN10",
        "title": "JESEN10",
        "amount": 5844,
        "method": "across"
      }
    ]
  },
  "expires_at": "2026-10-27T09:21:30.551Z",
  "line_items": [
    {
      "id": "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
      "item": {
        "id": "1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47",
        "price": 69900,
        "title": "Trek Marlin 5",
        "image_url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp"
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 69900
        },
        {
          "type": "total",
          "amount": 69900
        }
      ],
      "quantity": 1
    },
    {
      "id": "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49",
      "item": {
        "id": "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25",
        "price": 990,
        "title": "Fľaša na vodu 750 ml"
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 1980
        },
        {
          "type": "total",
          "amount": 1980
        }
      ],
      "quantity": 2
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "shipping",
        "type": "shipping",
        "groups": [
          {
            "id": "default",
            "options": [
              {
                "id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75",
                "title": "GLS kuriér",
                "totals": [
                  {
                    "type": "total",
                    "amount": 490
                  }
                ],
                "description": "Doručenie na adresu do 1–2 pracovných dní"
              },
              {
                "id": "6b2d9f4e-3a17-4c68-9d5b-1f8e3a7c2b40",
                "title": "Packeta – výdajné miesto",
                "totals": [
                  {
                    "type": "total",
                    "amount": 290
                  }
                ],
                "description": "Delivery in 2–3 business days"
              }
            ],
            "line_item_ids": [
              "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
              "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
            ],
            "selected_option_id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75"
          }
        ],
        "destinations": [
          {
            "id": "destination",
            "last_name": "Nováková",
            "first_name": "Jana",
            "postal_code": "811 01",
            "street_address": "Hlavná 12",
            "address_country": "SK",
            "address_locality": "Bratislava"
          }
        ],
        "line_item_ids": [
          "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
          "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
        ],
        "selected_destination_id": "destination"
      }
    ]
  },
  "order": {
    "id": "8e1c4f7a-2d95-4b36-a7e8-5c3f9b1d6a24",
    "label": "SK2600417",
    "permalink_url": "https://shop.example.com/order-confirmation?orderNumber=SK2600417&orderId=8e1c4f7a-2d95-4b36-a7e8-5c3f9b1d6a24"
  }
}

Kedy objednávka checkout nedokončí

Uplynutie platnosti súťaží s objednávkou. Dokončenie na expires_at neprihliada, ale akákoľvek vaša požiadavka, ktorá sa checkoutu dotkne po expires_at, ho najprv zruší. Po termíne preto rozhodne jediný GET: completed, ak objednávka prišla skôr, inak canceled.

Zisťovanie stavu

• Stav zisťujte cez GET /ucp/v1/checkout-sessions/{id} s bežnou hlavičkou UCP-Agent. Každé čítanie checkoutu čaká, kým sa pri relácii dostane na rad, preto majte na reláciu naraz rozpracovanú najviac jednu požiadavku; pri 503 dodržte Retry-After.
• Server interval neurčuje. Rozumné je pýtať sa každých 5–10 sekúnd počas prvej štvrťhodiny od chvíle, keď kupujúci dostal odkaz, potom raz za minútu.
• Stav zisťujte pri akomkoľvek otvorenom stave checkoutu: aj checkout odovzdaný v stave incomplete sa objednávkou kupujúceho dokončí. Prestaňte pri completed alebo canceled. Po expires_at rozhodne ešte jedno čítanie.
• „Nikdy nedokončené“ berte ako bežný výsledok: kupujúci mohol objednať spôsobom, ktorý sa nedá spätne spárovať (pozri tabuľku vyššie). Kupujúci vždy vidí vlastné potvrdenie obchodu.

Ako to celé do seba zapadá

1. Objavenie

   GET /.well-known/ucp. Uložte si endpoint a overte, že obsahuje schopnosti, ktoré potrebujete. V cache ho držte najviac päť minút.

2. Čítanie katalógu

   POST /ucp/v1/catalog/search, /ucp/v1/catalog/lookup alebo /ucp/v1/catalog/product na hostiteľovi z endpoint, zakaždým s UCP-Agent a context.language. Zapamätajte si id variantov.

3. Košík, alebo rovno checkout

   POST /ucp/v1/carts s line_items, alebo POST /ucp/v1/checkout-sessions. Ku každému zápisu pošlite Idempotency-Key. Čítajte správy v každej odpovedi a položky párujte podľa item.id.

4. Príprava checkoutu

   Ak máte košík, preveďte ho cez cart_id, potom cez PUT doplňte kupujúceho (celého), cieľ doručenia a spôsob dopravy, kým nie je status requires_escalation.

5. Odovzdanie

   Pošlite ešte raz PUT s line_items checkoutu, ukážte kupujúcemu súčty z tej odpovede a odovzdajte mu continue_url. Povedzte mu, že nákup dokončí a zaplatí v obchode.

6. Zistenie výsledku

   Čítajte GET /ucp/v1/checkout-sessions/<id>, kým nedostanete completed (ukážte order.label a order.permalink_url) alebo canceled.

Ten istý postup ako spustiteľný kód v curl, JavaScripte a Pythone nájdete v Rýchlom štarte pre vývojárov. Kde sa toto správanie drží špecifikácie a kde sa od nej odchyľuje, opisuje kapitola Zhoda so špecifikáciou UCP.