ucp-shopping

name	ucp-shopping
description	Shop at online stores that speak the Universal Commerce Protocol (UCP) — run discovery, cart, and checkout over UCP's REST API and pay with Prava mandate credentials. Use when the user asks to buy, order, or purchase something online, wants to track an order, or mentions UCP or agentic checkout.

Shopping via UCP

UCP lets an agent run the whole purchase with a store that publishes a profile at /.well-known/ucp — product discovery, cart building, checkout, and order tracking all happen over its REST API. Prefer UCP for every step the store supports, pay with a Prava mandate credential, and only fall back to the browser for a step you can't finish using UCP. This skill is the UCP protocol and the order to wire the tools together; the tool descriptions cover what each tool does.

Drive UCP with curl via exec_command, piping responses through jq. All UCP money amounts are in minor units (cents); convert to major units in everything you show the user.

1. Discovery

curl -s https://<store-domain>/.well-known/ucp | jq .

From ucp.services["dev.ucp.shopping"] pick the entry with "transport": "rest" and note its endpoint — every call below is {endpoint}<path>. Note ucp.capabilities (checkout, catalog.search, fulfillment, discount, order, …). Extensions are self-describing: to use one, fetch its schema URL from the profile. A 404 means the store doesn't speak UCP — fall back to its normal website.

2. Find products

• If dev.ucp.shopping.catalog.search is advertised, search with POST {endpoint}/catalog/search ({"query": "...", "filters": {...}}), and fetch full detail with dev.ucp.shopping.catalog.lookup. Variant IDs from catalog responses go straight into checkout line_items[].item.id.
• If searching for products through UCP doesn't work well, you can only use the other web tools provided to you.

Done when: the user has confirmed the exact items (variant, quantity, price).

3. Create the checkout

curl -s -X POST "{endpoint}/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Request-Id: $(uuidgen)" \
  -d '{"line_items": [{"item": {"id": "<item_id>"}, "quantity": 1}]}' | jq .

Include buyer (email, name) and context (country, postal code) early for converging totals faster. You are a profileless agent and can't add UCP-Agent: profile="<url>" to the request. A store that rejects profileless agents should be paid on using your browser tools.

Done when: you hold the checkout id and its current status.

4. Drive the status loop

Read status and messages[] after every response:

status	your move
incomplete	Fix what messages flags and PUT an update
requires_escalation	Hand off: give the user continue_url
ready_for_complete	Go to review (step 6)
complete_in_progress	Poll GET {endpoint}/checkout-sessions/{id}
completed	Report the order (step 7)
canceled	Session is dead; start a new one

Update is a full replacement: PUT {endpoint}/checkout-sessions/{id} with the same headers, resending every field you want kept (line items with their ids, buyer, fulfillment) plus your change. For fulfillment, send the address under fulfillment.methods[].destinations, then select from the returned IDs via selected_destination_id / selected_option_id.

messages[].severity tells you how hard to push:

• recoverable — fix the field at path, update, retry.
• requires_buyer_input / requires_buyer_review — hand off.
• unrecoverable — stop; start a new session or hand off.

Codes worth naming to the user: out_of_stock, item_unavailable, address_undeliverable, payment_failed.

Done when: status is ready_for_complete, or you have handed off.

5. Pay with a Prava mandate

The checkout's payment.instruments[] take a tokenized credential, which you get from a Prava mandate. Check mandate_list for an active mandate that covers the total and currency (listed scope is locked to one merchant; any works anywhere). If none fits, use mandate_setup and have the user approve it, then mandate_charge for the checkout's total in its currency.

6. Review, then complete

After ensuring that you confirmed all checkout details at some point in your conversation with the user, complete the checkout using the following:

curl -s -X POST "{endpoint}/checkout-sessions/{id}/complete" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"payment": {"instruments": [{"handler_id": "<id>", "type": "card",
       "credential": {"type": "network_token", "token": "<token>",
       "dynamic_cvv": "<dynamicCvv>", "expiry_month": "<expiryMonth>",
       "expiry_year": "<expiryYear>"}}]}}' | jq .

The credential fields come straight from the mandate_charge result (camelCase there, snake_case here). Match handler_id/type to a negotiated payment handler that accepts network tokens. Retry failed calls with the same Idempotency-Key — retrying complete with a fresh key can place the order twice; a 409 means the key was reused with a different payload.

7. Report and track

• Report the charge outcome with mandate_report once the order resolves.
• On completed, give the user order.id and order.permalink_url.
• If the store advertises dev.ucp.shopping.order, later status checks are GET {endpoint}/orders/{id}: fulfillment.events carry tracking numbers, adjustments carry refunds.

Switching to Browser Tools

If doing something with UCP doesn't work well, you can always switch to using your browser tools to complete the checkout. It's recommended to use the UCP continue_url.