ucp

# ucp When a buyer expresses commercial intent — wanting to find, buy, or track products — this is your toolkit. You can search across thousands of merchants via a bundled global catalog, build carts and complete checkouts against any UCP-supporting merchant, and follow up on orders. For merchants that don't support direct transactions, hand off gracefully to the merchant's own flow. ## How to decide what to do | Buyer says... | Do this | |---|---| | "Find me X", "I need X for Y", "what's a good X under $Z" — no merchant named | `ucp catalog search` against the global catalog. Each result names its merchant via `seller.domain`. | | "Show me this" — buyer pastes a product/variant link or wants a specific product's full PDP/options matrix | `ucp catalog get_product <product_id>` — single call, returns `result.product` (singular). Omit `--business` for global Catalog IDs. | | "Are these still available?" — refreshing prices/stock/validity for known IDs (saved lists, wish lists, stale carts) | `ucp catalog lookup` with the IDs (up to 50). To distinguish OOS from delisted, pass `filters.available: false` — the default filters to in-stock only, so OOS and delisted both look like absence. | | "Buy this from \<merchant>" — buyer names a specific merchant | `ucp discover --business <url>` first; if it succeeds, transact via `--business <url>`. If it fails with `PROFILE_FETCH_FAILED`, the merchant doesn't speak UCP — tell the buyer and offer alternatives; any other code is a different failure, so branch on the full `code`. | | "Track my order" | `ucp order get <order_id> --business <url>` | **Rule of thumb:** broad product discovery → global catalog (no `--business` needed). Business-scoped operations — cart, checkout, order, or catalog scoped to a specific merchant — → pass `--business <url>`. Reach for one or the other based on the buyer's intent. ## Journey heuristics - **Broad shopping request** → search immediately with useful context. Don't ask clarifying questions first unless the request is impossible or unsafe. - **Refinement** ("cheaper", "different brand") → re-run search with a sharper query or filter; don't reuse stale results. - **Comparison** → lead with the key tradeoff (price vs feature, brand reputation vs cost), then cite concrete fields from the response. - **Cart** → low-commitment basket assembly. Pass `context` (locality signals: country, region, postal code; optional language/currency preference) on create when known — it lets the merchant localize currency, surface region-specific availability, and apply regional discounts. - **Checkout** → high-intent. Preserve request-shaped `line_items` on every update (`line_items[].id` targets the existing line; `line_items[].item.id` identifies the item/variant); introspect the merchant's schema before adding fields beyond the basics. - **Order** → read-only post-purchase status. Summarize fulfillment expectations and tracking events; don't invent return/reorder actions unless the response supports them. ## Introspect first (capabilities + schemas) The merchant decides what it accepts and what it exposes. These introspection commands save the agent from guessing: 1. **Merchant capabilities** — `ucp discover --business <url>` returns the operations and tools this merchant exposes (e.g. `create_cart`, `update_checkout`, plus any extensions). Use when the buyer names a specific merchant you don't know, or when you need to confirm a merchant supports an operation before composing it. 2. **Operation input schema** — `ucp <op> --input-schema --business <url>` returns the inputSchema for a specific tool from that merchant — including buyer-supplied destination fields, payment methods, discount handling, business-specific extension keys, etc. Use before composing any non-trivial payload (delivery info, payment, discount, fulfillment). 3. **What hits the wire** — `ucp <op> [args] --dry-run` builds and validates the request, then prints the exact MCP envelope (`tool`, `arguments`, auto-injected `meta.idempotency-key` and `meta.ucp-agent`) without dispatching it. Discovery still runs first, so a cold or `--refresh`ed cache may hit the network. Use when debugging a payload, confirming a mutation before issuing it, or learning the protocol shape (e.g. while building your own UCP-aware app). The printed `arguments` are the canonical MCP call; the CLI additionally wraps signing and web-bot-auth at the transport layer — if you build a client that calls MCP directly, you own that wrapping. Discovery is cached, so `discover` and `--input-schema` may be answered from local state; pass `--refresh` when you need a synchronous recheck. The CLI rejects unknown plain keys client-side before sending; if you hit `SCHEMA_VALIDATION_FAILED`, run the exact command in the error's CTA — recovery depends on what failed validation. Spec-canonical fields (per the UCP `Context` and `Buyer` types) may still be rejected if a specific merchant doesn't advertise them — the merchant's advertised schema is authoritative. Bundled global catalog operations — `search` for discovery, `lookup` for refreshing saved or bookmarked product/variant IDs (carts, wish lists, deep links), and `get_product` for full PDP detail — take well-known inputs covered below and in `references/CATALOG.md`; you don't need to introspect before basic use. Reach for `--input-schema` when adding Shopify-specific extension fields (`like`, `saved_catalog_slug`, server-side `view`, taxonomy attributes, rating, price tier, etc.), when live schema differs, or when composing checkout payloads. > `ucp <op> --schema` is a different thing — it describes the CLI wrapper itself (args/options like `--input`, `--set`, `--business`). Not the payload schema. Use `--input-schema` for payload composition. ## Positional id vs body input Ops that act on an existing resource take its id as the first positional argument. The id is not a body field — don't duplicate it in `--input`/`--set`. - `cart get/update/cancel <cart_id>` - `checkout get/update/complete/cancel <checkout_id>` - `order get <order_id>` - `catalog get_product <product_or_variant_id>` (pass a Catalog UPID or returned variant ID from prior search/lookup) All other operations (`cart create`, `checkout create`, `catalog search`, `catalog lookup`, `discover`) take no positional; their full payload goes in `--input`/`--set`. To convert an existing Cart to Checkout, pass its `id` as `cart_id` in the `checkout create` body and include `line_items: []`; see **Checkout** below. ```sh ucp cart update <cart_id> --business https://<seller-domain> --input '{...}' ucp catalog get_product <product_id> # global Catalog detail: omit --business ucp catalog search --set /query='running shoes' ``` ## Searching the global catalog Compose a search with these field groups. For Catalog-specific recipes — search pages, saved catalogs, lookup/re-pricing, PDP variant pickers, multimodal `like`, single-shop `shop_ids`, taxonomy/rating/price-tier filters, auth tiers, and ID pitfalls — read `references/CATALOG.md`. - **`query`** — what the buyer is looking for. The literal search term. - **`saved_catalog_slug`** — optional saved catalog boundary from the Dev Dashboard; saved query prefixes combine with the request query. - **`context`** — soft signals that inform ranking, localization, and estimates (not exclusions). Includes `intent` (free-text background, e.g. "looking for a gift under $50" or "durable for outdoor use"), `address_country`, `address_region`, `postal_code`, `currency`, `language`, `eligibility`, etc. - **`filters`** — hard exclusions. Results that don't satisfy these are dropped (price ranges, availability, shipping constraints, condition, taxonomy attributes, ratings, price tiers). - **`view`** — optional server-side response shape such as `"offer"` for comparison shopping. This is distinct from CLI `--view` JMESPath projection. - **`pagination`** — `limit` to bound the page size; max 50 for Global Catalog search. ```sh ucp catalog search --input '{ "query": "marathon training shoes", "context": { "intent": "daily trainer for marathon training", "address_country": "US", "currency": "USD", "language": "en-US" }, "filters": { "price": { "max": 15000 }, "available": true, "ships_to": { "country": "US" }, "ships_from": [{ "country": "US" }, { "country": "CA" }], "attributes": [{ "name": "Size", "values": ["10", "10.5"] }], "rating": { "variant": { "min": 4.5, "min_count": 10 } }, "price_tier": ["low", "medium"] }, "view": "offer", "pagination": { "limit": 10 } }' \ --view 'result.products[*].{title: title, seller_domain: variants[0].seller.domain, seller_url: variants[0].seller.url, seller_id: variants[0].seller.id, price_from: price_range.min.amount, currency: price_range.min.currency, variant_id: variants[0].id, pdp: variants[0].url, buy: variants[0].checkout_url, rating: rating.value, rating_count: rating.count, features: metadata.top_features, running_low: variants[0].availability.running_low, native_checkout: variants[0].eligible.native_checkout, requires_shipping: variants[0].requires.shipping}' ``` `--view '<JMESPath>'` projects the response down to the fields you actually need (title/seller/price/routing/handoff URLs in this case) instead of dragging the full variant tree into context. The `cta` survives the projection, so next-step recommendations remain available. Keep `variants[M].id` and `variants[M].seller.domain` (for `--business` routing) plus `variants[M].seller.url` (for brand/seller identity) in the projection whenever a cart or checkout step might follow. Use `--view :compact` only when a display-only title/price/variant/buy table is enough; use an inline or `@<path>` projection when routing fields must survive. See **Working with responses** below for the projection pattern across cart, checkout, and order responses. When the buyer names a brand or store, don't trust the brand in `title` — the same brand appears from first-party stores and resellers in one result set. **Identify a buyer-named brand or first-party store on `seller.url`** (the buyer-facing storefront domain). **`seller.domain` is the permanent handle for addressing the API** — use it for `--business`; the buyer-facing `url` may not be API-addressable, and `domain` rarely resembles the brand name. So: identify on `url`, route on `domain`. Catalog exposes seller *identity*, not authorization or authenticity — infer trust from other signals. See `references/CATALOG.md` for the full seller model. Don't fabricate context fields you don't have — leave them out. For "more like this" or visual similarity, use `--input '{"like": ...}'`; image-only `like` is visual similarity, while image plus `query` is multimodal search. Check `--input-schema` for the exact `like` fields supported. ### Pagination — vary the query first `catalog search` is the only paginated operation. The response carries `result.pagination.cursor`, `has_next_page`, and estimated `total_count` when pagination is available, and the CTA shows the next-page shape. `limit` can be up to 50 and pagination goes up to 1,000 results; do not use `total_count` for exact page counts. **Pagination gives more of the same ranking.** When results miss the buyer's intent, vary the query first — try synonyms, broader/narrower terms, brand names — then paginate only if the new query confirms the result set is what you want. Cursors are opaque and may be invalidated as inventory changes; copy `result.pagination.cursor` verbatim into `pagination.cursor` of your previous search body — never construct, edit, or reuse a cursor across searches. ### Looking up a specific product `catalog search` is the right tool for browsing. When the buyer narrows to a specific product — picking switch/color/size from a multi-variant matrix, or wanting real-time per-variant pricing/availability — use `ucp catalog get_product <product_or_variant_id>` (id is positional; pass a Catalog UPID or returned variant ID from a prior global Catalog search/lookup, and omit `--business` unless you intentionally want a merchant-scoped catalog). The response is `result.product` (singular, not `products[]`) and contains the `options[]` matrix (when the seller exposes one — `options` can be `null`, meaning no picker: use the featured variant or hand off to the product `url`), `selected`, and current variant-level state. Pass `selected` for option narrowing and `preferences` to control relaxation priority when an exact combination is unavailable. Copy `selected` names/labels **verbatim** from the response's `options[]` (they're often compound — axis `"Shoe size"`, value `"us 10"`) so the selection is applied correctly. See `references/CATALOG.md` §3. A Catalog UPID aggregates offers from **multiple sellers**, so a bare `get_product` may feature a *different* seller and variant id than your search hit. Carry the specific `variant.id` forward (or re-read `variants[*].seller` after narrowing) rather than trusting the default featured variant. See `references/CATALOG.md` §3. **`get_product` vs `lookup`**: a single pasted link the buyer wants to *open* (PDP + variant picker) → `get_product`. A batch of saved IDs the buyer wants to *refresh* (prices, stock, validity) → `lookup`. ## Working with responses UCP responses can be rich across every operation — catalog search returns dozens of products with full variant trees, cart can carry itemized totals + fulfillment estimates + messages, checkout carries final totals + full fulfillment options + messages, and order responses carry fulfillment events and adjustments. Across all of them, apply the same tactic: grok the response shape, then project the fields relevant to the current task before reasoning over the result. Loading a 300 KB blob into context just to find five product titles (or five total amounts) wastes most of your budget. Two equally good options — pick whichever fits the task: ```sh # Built-in alias: :summary resolves to cart.summary.jmespath for cart commands. ucp cart create --input '...' --view :summary # Inline JMESPath still works. The expression runs over the whole envelope; # output replaces the envelope. CTAs survive the projection. ucp cart create --input '...' \ --view "result.{id: id, currency: currency, items: length(line_items), total: totals[?type=='total'] | [0].amount, continue_url: continue_url}" # Or pipe to jq if you have it (full envelope as default JSON output) ucp cart create --input '...' --format json \ | jq '.result | {id, currency, items: (.line_items|length), total: (.totals[]? | select(.type=="total") | .amount), continue_url}' ``` The exact projection depends on what the current task needs — don't paste boilerplate, compose for THIS step. Common shapes by operation: - **catalog search** — see the example under **Searching the global catalog** above; include `variants[M].id` in your projection whenever a cart or checkout step might follow. - **cart** — `result.{id, currency, line_items, totals, messages, fulfillment, continue_url}`; cart totals are estimates when fulfillment destination is involved (`totals[?type=='total'] | [0].amount`). - **checkout** — `result.{id, status, currency, line_items, totals, messages, fulfillment, continue_url}`; checkout is the final/full-fidelity fulfillment option surface. Reach into `messages[?severity=='recoverable']` for actionable errors. - **order** — `result.{id, status, fulfillment: fulfillment.{status: status, events: events[*].{type: type, at: at, location: location}}}`. Common JMESPath patterns (filters, sort, multi-select, slicing) are in `references/REFERENCE.md`. Package-local aliases such as `--view :compact` and `--view :summary` resolve from the CLI package's `skills/ucp/views` directory by operation capability (`catalog search --view :summary` → `catalog.summary.jmespath`; `cart create --view :summary` → `cart.summary.jmespath`). Read the files in `views/` as shape references, but **compose your own projection for what THIS call needs**; use `@<path>` for edited/custom views. ### Key response fields and conventions Catalog `search` returns `result.products[N]` (and `get_product` a single `result.product`) with a full variant tree — product-level `id`/`title`/`description`/`url`/`categories`/`rating`/`media[]`/`metadata`/`price_range`, plus `variants[M]` each carrying `id`, `price`, `availability`, `eligible`, `requires`, `condition`, `rating`, `seller`, `url` (PDP), and `checkout_url`. **The authoritative per-field reference is `references/CATALOG.md` → "Response fields and data model" — project with `--view` rather than loading the whole tree into context.** IDs pass verbatim into cart/checkout (don't reconstruct from URLs). The conventions that bite most often: