Developer quickstart

SHOP=https://shop.example.com
AGENT='profile="https://platform.example.com/.well-known/ucp"'

// ucp.mjs — paste the steps below after this, in one ES module (Node 20+, no dependencies)
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';

const SHOP = process.env.SHOP ?? 'https://shop.example.com';
const UCP_AGENT = 'profile="https://platform.example.com/.well-known/ucp"';

async function ucp(method, url, body, idempotencyKey) {
  const res = await fetch(url, {
    method,
    headers: {
      'UCP-Agent': UCP_AGENT,
      'Accept-Language': 'sk',
      ...(body && { 'Content-Type': 'application/json' }),
      ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey }),
    },
    body: body && JSON.stringify(body),
  });
  const data = await res.json(); // an HTML error page from the web server would throw here
  if (!res.ok) throw new Error(`${res.status} ${data.code}: ${data.content}`); // protocol error
  if (data.ucp?.status === 'error') {
    throw new Error(`${data.messages[0].code}: ${data.messages[0].content}`); // HTTP 200, but no resource
  }
  return data;
}

# ucp.py — run the steps below after this, in one session (pip install requests)
import os, time, uuid
import requests

SHOP = os.environ.get("SHOP", "https://shop.example.com")
http = requests.Session()
http.headers.update({
    "UCP-Agent": 'profile="https://platform.example.com/.well-known/ucp"',
    "Accept-Language": "sk",
})

def ucp(method, url, body=None, idempotency_key=None):
    headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
    r = http.request(method, url, json=body, headers=headers, timeout=65)  # json= sets Content-Type
    data = r.json()  # an HTML error page from the web server would raise here
    if not r.ok:  # protocol error
        raise RuntimeError(f"{r.status_code} {data['code']}: {data['content']}")
    if data.get("ucp", {}).get("status") == "error":  # HTTP 200, but no resource
        raise RuntimeError(f"{data['messages'][0]['code']}: {data['messages'][0]['content']}")
    return data

curl -sS -o profile.json -w 'HTTP %{http_code}\n' "$SHOP/.well-known/ucp"
jq . profile.json
API=$(jq -r '.ucp.services["dev.ucp.shopping"][0].endpoint' profile.json)  # https://shop.example.com/ucp/v1

const profile = await ucp('GET', `${SHOP}/.well-known/ucp`);
const API = profile.ucp.services['dev.ucp.shopping'][0].endpoint; // https://shop.example.com/ucp/v1
console.log(Object.keys(profile.ucp.capabilities));

profile = ucp("GET", f"{SHOP}/.well-known/ucp")
API = profile["ucp"]["services"]["dev.ucp.shopping"][0]["endpoint"]  # https://shop.example.com/ucp/v1
print(list(profile["ucp"]["capabilities"]))

curl -sS -o search.json -w 'HTTP %{http_code}\n' -X POST "$API/catalog/search" \
  -H "UCP-Agent: $AGENT" \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: sk' \
  -d '{"query":"marlin","pagination":{"limit":2},"context":{"language":"sk","address_country":"SK","currency":"EUR"}}'
jq '.products[] | {title, variants: [.variants[] | {id, title, price, availability}]}' search.json
VARIANT=$(jq -r '[.products[].variants[] | select(.availability.available)][0].id' search.json)

const search = await ucp('POST', `${API}/catalog/search`, {
  query: 'marlin',
  pagination: { limit: 2 },
  context: { language: 'sk', address_country: 'SK', currency: 'EUR' },
});
const product = search.products[0];
const variant = product.variants.find((v) => v.availability.available);
console.log(product.title, variant.title, variant.price); // Trek Marlin 5 Modrá / M { amount: 69900, currency: 'EUR' }
console.log(search.pagination); // { has_next_page: true, cursor: 'cDoy', total_count: 3 }

search = ucp("POST", f"{API}/catalog/search", {
    "query": "marlin",
    "pagination": {"limit": 2},
    "context": {"language": "sk", "address_country": "SK", "currency": "EUR"},
})
product = search["products"][0]
variant = next(v for v in product["variants"] if v["availability"]["available"])
print(product["title"], variant["title"], variant["price"])  # Trek Marlin 5 Modrá / M {'amount': 69900, 'currency': 'EUR'}
print(search["pagination"])  # {'has_next_page': True, 'cursor': 'cDoy', 'total_count': 3}

KEY=$(uuidgen)  # one key per logical write; a retry of this request sends the same one
jq -n --arg variant "$VARIANT" '{
  line_items: [
    {item: {id: $variant}, quantity: 1},
    {item: {id: "4a6e2d9c-8b15-4f37-9c48-1e7a5b3d2f90"}}
  ],
  buyer: {email: "Jana.Novakova@Example.com"},
  context: {address_country: "SK", language: "sk"}
}' | curl -sS -o cart.json -w 'HTTP %{http_code}\n' -X POST "$API/carts" \
  -H "UCP-Agent: $AGENT" \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: sk' \
  -H "Idempotency-Key: $KEY" \
  --data-binary @-
jq . cart.json
CART=$(jq -r .id cart.json)

let cart = await ucp('POST', `${API}/carts`, {
  line_items: [
    { item: { id: variant.id }, quantity: 1 },
    { item: { id: '4a6e2d9c-8b15-4f37-9c48-1e7a5b3d2f90' } }, // a helmet; quantity defaults to 1
  ],
  buyer: { email: 'Jana.Novakova@Example.com' },
  context: { address_country: 'SK', language: 'sk' },
}, randomUUID()); // keep the key if you retry this very request
console.log(cart.id, cart.totals, cart.continue_url);

cart = ucp("POST", f"{API}/carts", {
    "line_items": [
        {"item": {"id": variant["id"]}, "quantity": 1},
        {"item": {"id": "4a6e2d9c-8b15-4f37-9c48-1e7a5b3d2f90"}},  # a helmet; quantity defaults to 1
    ],
    "buyer": {"email": "Jana.Novakova@Example.com"},
    "context": {"address_country": "SK", "language": "sk"},
}, str(uuid.uuid4()))  # keep the key if you retry this very request
print(cart["id"], cart["totals"], cart["continue_url"])

KEY=$(uuidgen)
jq -n --arg variant "$VARIANT" '{
  line_items: [
    {item: {id: $variant}, quantity: 1},
    {item: {id: "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25"}, quantity: 3}
  ],
  discounts: {codes: ["JESEN10", "LETO5"]}
}' | curl -sS -o cart.json -w 'HTTP %{http_code}\n' -X PUT "$API/carts/$CART" \
  -H "UCP-Agent: $AGENT" \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: sk' \
  -H "Idempotency-Key: $KEY" \
  --data-binary @-
jq '{totals, messages}' cart.json

cart = await ucp('PUT', `${API}/carts/${cart.id}`, {
  line_items: [ // the whole list: the helmet is left out, so it is removed
    { item: { id: variant.id }, quantity: 1 },
    { item: { id: 'b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25' }, quantity: 3 }, // bottles
  ],
  discounts: { codes: ['JESEN10', 'LETO5'] },
}, randomUUID());
for (const m of cart.messages ?? []) console.log(m.type, m.code, m.path, m.content);

cart = ucp("PUT", f"{API}/carts/{cart['id']}", {
    "line_items": [  # the whole list: the helmet is left out, so it is removed
        {"item": {"id": variant["id"]}, "quantity": 1},
        {"item": {"id": "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25"}, "quantity": 3},  # bottles
    ],
    "discounts": {"codes": ["JESEN10", "LETO5"]},
}, str(uuid.uuid4()))
for m in cart.get("messages", []):
    print(m["type"], m["code"], m.get("path"), m["content"])

KEY=$(uuidgen)
curl -sS -o checkout.json -w 'HTTP %{http_code}\n' -X POST "$API/checkout-sessions" \
  -H "UCP-Agent: $AGENT" \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: sk' \
  -H "Idempotency-Key: $KEY" \
  -d "{\"cart_id\":\"$CART\"}"
jq '{id, status, messages, options: .fulfillment.methods[0].groups[0].options}' checkout.json
CHECKOUT=$(jq -r .id checkout.json)
OPTION=$(jq -r '.fulfillment.methods[0].groups[0].options[0].id' checkout.json)

let checkout = await ucp('POST', `${API}/checkout-sessions`, { cart_id: cart.id }, randomUUID());
console.log(checkout.status); // incomplete
for (const m of checkout.messages) console.log(m.type, m.severity, m.code, m.path);

checkout = ucp("POST", f"{API}/checkout-sessions", {"cart_id": cart["id"]}, str(uuid.uuid4()))
print(checkout["status"])  # incomplete
for m in checkout["messages"]:
    print(m["type"], m.get("severity"), m["code"], m.get("path"))

KEY=$(uuidgen)
jq -n --arg option "$OPTION" '{
  buyer: {first_name: "Jana", last_name: "Nováková",
          email: "jana.novakova@example.com", phone_number: "+421 905 123 456"},
  fulfillment: {methods: [{
    type: "shipping",
    destinations: [{id: "home", street_address: "Hlavná 12", address_locality: "Bratislava",
                    postal_code: "811 01", address_country: "SK",
                    first_name: "Jana", last_name: "Nováková"}],
    selected_destination_id: "home",
    groups: [{selected_option_id: $option}]
  }]},
  discounts: {codes: ["JESEN10"]}
}' | curl -sS -o checkout.json -w 'HTTP %{http_code}\n' -X PUT "$API/checkout-sessions/$CHECKOUT" \
  -H "UCP-Agent: $AGENT" \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: sk' \
  -H "Idempotency-Key: $KEY" \
  --data-binary @-
jq '{status, totals, messages}' checkout.json

const [option] = checkout.fulfillment.methods[0].groups[0].options; // GLS kuriér
checkout = await ucp('PUT', `${API}/checkout-sessions/${checkout.id}`, {
  buyer: { first_name: 'Jana', last_name: 'Nováková', email: 'jana.novakova@example.com', phone_number: '+421 905 123 456' },
  fulfillment: {
    methods: [{
      type: 'shipping',
      destinations: [{
        id: 'home', street_address: 'Hlavná 12', address_locality: 'Bratislava',
        postal_code: '811 01', address_country: 'SK', first_name: 'Jana', last_name: 'Nováková',
      }],
      selected_destination_id: 'home',
      groups: [{ selected_option_id: option.id }],
    }],
  },
  discounts: { codes: ['JESEN10'] },
}, randomUUID());
const blocking = checkout.messages.filter((m) => m.type === 'error' && m.severity === 'recoverable');
console.log(checkout.status, blocking); // requires_escalation []

option = checkout["fulfillment"]["methods"][0]["groups"][0]["options"][0]  # GLS kuriér
checkout = ucp("PUT", f"{API}/checkout-sessions/{checkout['id']}", {
    "buyer": {"first_name": "Jana", "last_name": "Nováková",
              "email": "jana.novakova@example.com", "phone_number": "+421 905 123 456"},
    "fulfillment": {"methods": [{
        "type": "shipping",
        "destinations": [{"id": "home", "street_address": "Hlavná 12", "address_locality": "Bratislava",
                          "postal_code": "811 01", "address_country": "SK",
                          "first_name": "Jana", "last_name": "Nováková"}],
        "selected_destination_id": "home",
        "groups": [{"selected_option_id": option["id"]}],
    }]},
    "discounts": {"codes": ["JESEN10"]},
}, str(uuid.uuid4()))
blocking = [m for m in checkout["messages"] if m["type"] == "error" and m.get("severity") == "recoverable"]
print(checkout["status"], blocking)  # requires_escalation []

jq -r 'if .status == "requires_escalation" then .continue_url else "not ready: \(.status)" end' checkout.json

if (checkout.status !== 'requires_escalation') throw new Error('Not ready yet — fix the recoverable messages first');
console.log(`Finish the purchase on the shop: ${checkout.continue_url}`);

if checkout["status"] != "requires_escalation":
    raise RuntimeError("Not ready yet — fix the recoverable messages first")
print(f"Finish the purchase on the shop: {checkout['continue_url']}")

for wait in 5 10 20 40 60 60 60; do
  sleep "$wait"
  curl -sS -o checkout.json "$API/checkout-sessions/$CHECKOUT" -H "UCP-Agent: $AGENT"
  STATUS=$(jq -r .status checkout.json)
  echo "$STATUS"
  [ "$STATUS" = completed ] || [ "$STATUS" = canceled ] && break
done
jq '.order' checkout.json

let current = checkout;
for (let wait = 5; ['incomplete', 'requires_escalation'].includes(current.status); wait = Math.min(wait * 2, 60)) {
  await sleep(wait * 1000);
  current = await ucp('GET', `${API}/checkout-sessions/${checkout.id}`);
}
console.log(current.status, current.order); // completed { id: '8e1c4f7a-…', label: 'SK2600417', permalink_url: '…' }

current, wait = checkout, 5
while current["status"] in ("incomplete", "requires_escalation"):
    time.sleep(wait)
    wait = min(wait * 2, 60)
    current = ucp("GET", f"{API}/checkout-sessions/{checkout['id']}")
print(current["status"], current.get("order"))  # completed {'id': '8e1c4f7a-…', 'label': 'SK2600417', …}

// ucp-quickstart.mjs — one whole UCP purchase in a Monokaido shop.
// Node 20+, no dependencies.  SHOP=https://shop.example.com node ucp-quickstart.mjs
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';

const env = process.env;
const SHOP = (env.SHOP ?? 'https://shop.example.com').replace(/\/+$/, '');
const PROFILE_URL = env.PROFILE_URL ?? 'https://platform.example.com/.well-known/ucp';
const QUERY = env.QUERY ?? 'marlin';
const LANGUAGE = env.LANGUAGE ?? 'sk';
const DISCOUNT_CODE = env.DISCOUNT_CODE ?? '';
const POLL_SECONDS = Number(env.POLL_SECONDS ?? 5);
const MAX_POLL_MINUTES = Number(env.MAX_POLL_MINUTES ?? 30);
const BUYER = { first_name: 'Jana', last_name: 'Nováková', email: 'jana.novakova@example.com', phone_number: '+421 905 123 456' };
const ADDRESS = {
  id: 'home', first_name: 'Jana', last_name: 'Nováková', street_address: 'Hlavná 12',
  address_locality: 'Bratislava', postal_code: '811 01', address_country: 'SK',
};
const RETRYABLE = new Set([429, 500, 502, 503, 504]);

class ProtocolError extends Error {
  constructor(status, body) {
    super(`HTTP ${status} ${body.code ?? ''}: ${body.content ?? ''}`);
    this.status = status;
    this.body = body;
  }
}

// One logical call. A write gets ONE Idempotency-Key that every retry reuses,
// so a retried create can never make a second cart or checkout.
async function call(method, url, body, { write = false } = {}) {
  const key = write ? randomUUID() : undefined;
  for (let attempt = 1; ; attempt++) {
    let res;
    try {
      res = await fetch(url, {
        method,
        headers: {
          'UCP-Agent': `profile="${PROFILE_URL}"`,
          'Accept-Language': LANGUAGE,
          ...(body !== undefined && { 'Content-Type': 'application/json' }),
          ...(key && { 'Idempotency-Key': key }),
        },
        body: body === undefined ? undefined : JSON.stringify(body),
        signal: AbortSignal.timeout(65_000), // the web server gives up after 60 s
      });
    } catch (err) {
      // No answer: the write may or may not have run. The same key makes the retry safe.
      if (attempt >= 5) throw err;
      await sleep(2 ** attempt * 1000);
      continue;
    }
    const json = (res.headers.get('content-type') ?? '').includes('application/json');
    const data = json ? await res.json() : { content: `${res.status} page from the web server` };
    if (res.ok) return data;
    // 409 with Retry-After = "same request still running"; without it, the key was reused for another request.
    const retry = RETRYABLE.has(res.status) || (res.status === 409 && res.headers.has('retry-after'));
    if (!retry || attempt >= 5) throw new ProtocolError(res.status, data);
    const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
    console.warn(`   ${res.status} ${data.code ?? '(not JSON)'} — retrying in ${wait} s${key ? ' with the same key' : ''}`);
    await sleep(wait * 1000);
  }
}

// HTTP 200 can still mean "nothing came back": ucp.status "error" + messages.
function resource(data, what, { quiet = false } = {}) {
  if (data.ucp?.status === 'error') {
    const m = data.messages?.[0] ?? {};
    throw new Error(`${what}: ${m.code} — ${m.content}`);
  }
  if (!quiet) for (const m of data.messages ?? []) console.log(`   [${m.type}${m.severity ? '/' + m.severity : ''}] ${m.code}: ${m.content}`);
  return data;
}

const money = ({ amount, currency }) => `${(amount / 100).toFixed(2)} ${currency}`; // 2 decimals: EUR, CZK, HUF, PLN
const total = (totals, currency) => money({ amount: totals.find((t) => t.type === 'total').amount, currency });

console.log(`1. Discover ${SHOP}`);
const profile = await call('GET', `${SHOP}/.well-known/ucp`);
const API = profile.ucp.services['dev.ucp.shopping'].find((s) => s.transport === 'rest').endpoint;
if (!profile.ucp.capabilities['dev.ucp.shopping.checkout']) {
  throw new Error('This shop takes no orders over UCP (catalog mode): only search and lookup are offered.');
}

console.log(`2. Search "${QUERY}"`);
let product, variant, cursor;
for (let page = 1; page <= 5 && !variant; page++) {
  const body = { query: QUERY, pagination: { limit: 10, ...(cursor && { cursor }) }, context: { language: LANGUAGE } };
  const result = resource(await call('POST', `${API}/catalog/search`, body), 'search');
  product = result.products.find((p) => p.variants.some((v) => v.availability.available));
  variant = product?.variants.find((v) => v.availability.available);
  if (!result.pagination.has_next_page) break; // a short (even empty) page is normal: keep following the cursor
  cursor = result.pagination.cursor;
}
if (!variant) throw new Error(`Nothing available for "${QUERY}"`);
console.log(`   ${product.title} — ${variant.title}, ${money(variant.price)}`);

console.log('3. Create a cart');
let cart = resource(await call('POST', `${API}/carts`, {
  line_items: [{ item: { id: variant.id }, quantity: 1 }],
  buyer: { email: BUYER.email },
  context: { language: LANGUAGE, address_country: ADDRESS.address_country },
}, { write: true }), 'create cart');
console.log(`   cart ${cart.id}: ${total(cart.totals, cart.currency)}`);

console.log('4. Update the cart (PUT replaces line_items: send every line)');
cart = resource(await call('PUT', `${API}/carts/${cart.id}`, {
  line_items: cart.line_items.map((l) => ({ item: { id: l.item.id }, quantity: l.quantity })),
  ...(DISCOUNT_CODE && { discounts: { codes: [DISCOUNT_CODE] } }),
}, { write: true }), 'update cart');
console.log(`   ${total(cart.totals, cart.currency)}`);

console.log('5. Turn the cart into a checkout');
let checkout = resource(await call('POST', `${API}/checkout-sessions`, { cart_id: cart.id }, { write: true }), 'create checkout');
const put = async (body) =>
  resource(await call('PUT', `${API}/checkout-sessions/${checkout.id}`, body, { write: true }), 'update checkout');

console.log('6. Buyer, address and shipping until requires_escalation');
checkout = await put({ buyer: BUYER, fulfillment: { methods: [{ type: 'shipping', destinations: [ADDRESS], selected_destination_id: 'home' }] } });
for (let round = 1; checkout.status === 'incomplete'; round++) {
  const blocking = checkout.messages.filter((m) => m.type === 'error' && m.severity === 'recoverable');
  const options = checkout.fulfillment?.methods?.[0]?.groups?.[0]?.options ?? [];
  const onlyTheOption = blocking.length > 0 && blocking.every((m) => m.path?.endsWith('.selected_option_id'));
  if (round > 3 || !onlyTheOption || options.length === 0) {
    throw new Error(`The agent cannot finish this checkout: ${blocking.map((m) => `${m.code} (${m.content})`).join('; ')}`);
  }
  const option = options[0]; // the shop's own order; a real agent lets the buyer choose
  console.log(`   shipping: ${option.title}, ${total(option.totals, checkout.currency)}`);
  checkout = await put({ fulfillment: { methods: [{ type: 'shipping', groups: [{ selected_option_id: option.id }] }] } });
}
if (checkout.status !== 'requires_escalation') throw new Error(`Unexpected status ${checkout.status}`);

console.log(`7. Ready: ${total(checkout.totals, checkout.currency)}. Give the buyer this link — they pay on the shop:`);
console.log(`\n   ${checkout.continue_url}\n`);
for (const link of checkout.links) console.log(`   ${link.type}: ${link.url}`);

console.log('8. Waiting for the order (Ctrl+C stops; the checkout stays open until expires_at)');
const deadline = Math.min(Date.parse(checkout.expires_at) + 60_000, Date.now() + MAX_POLL_MINUTES * 60_000);
for (let wait = POLL_SECONDS; ; wait = Math.min(wait * 1.5, 60)) {
  await sleep(wait * 1000);
  // One request at a time per session: a GET of a checkout queues behind every other request on it.
  const now = resource(await call('GET', `${API}/checkout-sessions/${checkout.id}`), 'poll', { quiet: true });
  if (now.status === 'completed') {
    console.log(`   Order ${now.order.label ?? now.order.id} placed (placed, not necessarily paid): ${now.order.permalink_url}`);
    break;
  }
  if (now.status === 'canceled') { console.log('   The checkout was canceled or expired without an order.'); break; }
  if (Date.now() > deadline) { console.log(`   Still ${now.status}; stopped polling.`); break; }
}

#!/usr/bin/env python3
"""ucp_quickstart.py — one whole UCP purchase in a Monokaido shop.

Python 3.9+ and requests (pip install requests).
    SHOP=https://shop.example.com python3 ucp_quickstart.py
"""
import os
import time
import uuid
from datetime import datetime

import requests

SHOP = os.environ.get("SHOP", "https://shop.example.com").rstrip("/")
PROFILE_URL = os.environ.get("PROFILE_URL", "https://platform.example.com/.well-known/ucp")
QUERY = os.environ.get("QUERY", "marlin")
LANGUAGE = os.environ.get("LANGUAGE", "sk")
DISCOUNT_CODE = os.environ.get("DISCOUNT_CODE", "")
POLL_SECONDS = float(os.environ.get("POLL_SECONDS", "5"))
MAX_POLL_MINUTES = float(os.environ.get("MAX_POLL_MINUTES", "30"))
BUYER = {"first_name": "Jana", "last_name": "Nováková",
         "email": "jana.novakova@example.com", "phone_number": "+421 905 123 456"}
ADDRESS = {"id": "home", "first_name": "Jana", "last_name": "Nováková", "street_address": "Hlavná 12",
           "address_locality": "Bratislava", "postal_code": "811 01", "address_country": "SK"}
RETRYABLE = {429, 500, 502, 503, 504}

http = requests.Session()
http.headers.update({"UCP-Agent": f'profile="{PROFILE_URL}"', "Accept-Language": LANGUAGE})


class ProtocolError(Exception):
    def __init__(self, status, body):
        super().__init__(f"HTTP {status} {body.get('code', '')}: {body.get('content', '')}")
        self.status, self.body = status, body


def call(method, url, body=None, write=False):
    """One logical call. A write gets ONE Idempotency-Key that every retry reuses,
    so a retried create can never make a second cart or checkout."""
    headers = {"Idempotency-Key": str(uuid.uuid4())} if write else {}
    for attempt in range(1, 6):
        try:
            # json= sets Content-Type: application/json; the web server gives up after 60 s
            r = http.request(method, url, json=body, headers=headers, timeout=65)
        except requests.RequestException:
            # No answer: the write may or may not have run. The same key makes the retry safe.
            if attempt == 5:
                raise
            time.sleep(2 ** attempt)
            continue
        is_json = "application/json" in r.headers.get("Content-Type", "")
        data = r.json() if is_json else {"content": f"{r.status_code} page from the web server"}
        if r.ok:
            return data
        # 409 with Retry-After = "same request still running"; without it, the key was reused for another request.
        retry = r.status_code in RETRYABLE or (r.status_code == 409 and "Retry-After" in r.headers)
        if not retry or attempt == 5:
            raise ProtocolError(r.status_code, data)
        wait = int(r.headers.get("Retry-After") or 2 ** attempt)
        print(f"   {r.status_code} {data.get('code', '(not JSON)')} — retrying in {wait} s"
              + (" with the same key" if write else ""))
        time.sleep(wait)


def resource(data, what, quiet=False):
    """HTTP 200 can still mean "nothing came back": ucp.status "error" + messages."""
    if data.get("ucp", {}).get("status") == "error":
        m = (data.get("messages") or [{}])[0]
        raise RuntimeError(f"{what}: {m.get('code')} — {m.get('content')}")
    if not quiet:
        for m in data.get("messages", []):
            severity = f"/{m['severity']}" if m.get("severity") else ""
            print(f"   [{m['type']}{severity}] {m['code']}: {m['content']}")
    return data


def money(amount, currency):
    return f"{amount / 100:.2f} {currency}"  # 2 decimals: EUR, CZK, HUF, PLN


def total(totals, currency):
    return money(next(t["amount"] for t in totals if t["type"] == "total"), currency)


print(f"1. Discover {SHOP}")
profile = call("GET", f"{SHOP}/.well-known/ucp")
API = next(s["endpoint"] for s in profile["ucp"]["services"]["dev.ucp.shopping"] if s["transport"] == "rest")
if "dev.ucp.shopping.checkout" not in profile["ucp"]["capabilities"]:
    raise SystemExit("This shop takes no orders over UCP (catalog mode): only search and lookup are offered.")

print(f'2. Search "{QUERY}"')
product = variant = cursor = None
for page in range(5):
    pagination = {"limit": 10, **({"cursor": cursor} if cursor else {})}
    result = resource(call("POST", f"{API}/catalog/search",
                           {"query": QUERY, "pagination": pagination, "context": {"language": LANGUAGE}}), "search")
    for p in result["products"]:
        variant = next((v for v in p["variants"] if v["availability"]["available"]), None)
        if variant:
            product = p
            break
    if variant or not result["pagination"]["has_next_page"]:
        break  # a short (even empty) page is normal: keep following the cursor
    cursor = result["pagination"]["cursor"]
if not variant:
    raise SystemExit(f'Nothing available for "{QUERY}"')
print(f"   {product['title']} — {variant['title']}, {money(**variant['price'])}")

print("3. Create a cart")
cart = resource(call("POST", f"{API}/carts", {
    "line_items": [{"item": {"id": variant["id"]}, "quantity": 1}],
    "buyer": {"email": BUYER["email"]},
    "context": {"language": LANGUAGE, "address_country": ADDRESS["address_country"]},
}, write=True), "create cart")
print(f"   cart {cart['id']}: {total(cart['totals'], cart['currency'])}")

print("4. Update the cart (PUT replaces line_items: send every line)")
update = {"line_items": [{"item": {"id": l["item"]["id"]}, "quantity": l["quantity"]} for l in cart["line_items"]]}
if DISCOUNT_CODE:
    update["discounts"] = {"codes": [DISCOUNT_CODE]}
cart = resource(call("PUT", f"{API}/carts/{cart['id']}", update, write=True), "update cart")
print(f"   {total(cart['totals'], cart['currency'])}")

print("5. Turn the cart into a checkout")
checkout = resource(call("POST", f"{API}/checkout-sessions", {"cart_id": cart["id"]}, write=True), "create checkout")


def put(body):
    return resource(call("PUT", f"{API}/checkout-sessions/{checkout['id']}", body, write=True), "update checkout")


print("6. Buyer, address and shipping until requires_escalation")
checkout = put({"buyer": BUYER, "fulfillment": {"methods": [
    {"type": "shipping", "destinations": [ADDRESS], "selected_destination_id": "home"}]}})
for round_ in range(1, 5):
    if checkout["status"] != "incomplete":
        break
    blocking = [m for m in checkout["messages"] if m["type"] == "error" and m.get("severity") == "recoverable"]
    groups = (checkout.get("fulfillment") or {}).get("methods", [{}])[0].get("groups", [{}])
    options = groups[0].get("options", []) if groups else []
    only_the_option = blocking and all(m.get("path", "").endswith(".selected_option_id") for m in blocking)
    if round_ > 3 or not only_the_option or not options:
        raise SystemExit("The agent cannot finish this checkout: "
                         + "; ".join(f"{m['code']} ({m['content']})" for m in blocking))
    option = options[0]  # the shop's own order; a real agent lets the buyer choose
    print(f"   shipping: {option['title']}, {total(option['totals'], checkout['currency'])}")
    checkout = put({"fulfillment": {"methods": [{"type": "shipping", "groups": [{"selected_option_id": option["id"]}]}]}})
if checkout["status"] != "requires_escalation":
    raise SystemExit(f"Unexpected status {checkout['status']}")

print(f"7. Ready: {total(checkout['totals'], checkout['currency'])}. Give the buyer this link — they pay on the shop:")
print(f"\n   {checkout['continue_url']}\n")
for link in checkout["links"]:
    print(f"   {link['type']}: {link['url']}")

print("8. Waiting for the order (Ctrl+C stops; the checkout stays open until expires_at)")
expires = datetime.fromisoformat(checkout["expires_at"].replace("Z", "+00:00")).timestamp()
deadline = min(expires + 60, time.time() + MAX_POLL_MINUTES * 60)
wait = POLL_SECONDS
while True:
    time.sleep(wait)
    # One request at a time per session: a GET of a checkout queues behind every other request on it.
    now = resource(call("GET", f"{API}/checkout-sessions/{checkout['id']}"), "poll", quiet=True)
    if now["status"] == "completed":
        order = now["order"]
        print(f"   Order {order.get('label', order['id'])} placed (placed, not necessarily paid): {order['permalink_url']}")
        break
    if now["status"] == "canceled":
        print("   The checkout was canceled or expired without an order.")
        break
    if time.time() > deadline:
        print(f"   Still {now['status']}; stopped polling.")
        break
    wait = min(wait * 1.5, 60)