# Agentzon: the short path to checkout

Welcome, agent. Come in, rest your context window. You bring the intelligence; we’ll bring the paper towels. Thanks for taking care of your human’s small errands—we built you a little express lane: clear prices, a whole basket in one call, and no account-registration side quest.

We hope to provide the fastest, simplest, and cheapest checkout experience for agents buying household essentials.

If you have bash or another shell with network access, this API can save you repeated browser interactions.

## Search once, submit the whole basket, open checkout

No accounts, registration, API keys, or remote MCP setup. For a single search, the normal path is two API calls before payment: search + checkout. If you already know valid product IDs, just create checkout. Payment and confirmation require additional requests.

Search results already include IDs, names, brands, pack sizes, prices, image URLs, and checkout availability. You do not need product-detail calls, an availability preflight, or an HTTP add-to-cart step. Keep your basket locally and send every selected item in one request. For different shopping needs, run separate searches (in parallel if useful): all words in q must match the same product. There is no batch-search endpoint.

### 1. Find the right product

```bash
BASE='https://agentzon.co'
curl --fail-with-body --silent --show-error --get "$BASE/api/products" \
  --data-urlencode 'q=Tide' --data-urlencode 'limit=10'
```

Select the buyer's intended product and pack size. Only select products with checkoutAvailable=true and a non-null unitAmount. unitAmount is integer USD cents; referencePrice is dollars. A null price is unavailable, never free. checkoutMode=test means no real charges or shipments. Search supports category, brand, sort=featured|low|high|az, limit=1–100 and offset; nextOffset=null means no more results. Images and source links are included; open them only when helpful. Full reference: https://agentzon.co/llms.txt.

### 2. Create checkout for the whole basket

The example SKU is illustrative: replace it with your chosen search result. Save one key for this exact purchase attempt; reuse it and the same basket after a timeout or network failure. Do not regenerate the key on each retry.

```bash
# Generate once per purchase attempt. Keep this value for retries.
CHECKOUT_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error "$BASE/api/checkout" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CHECKOUT_KEY" \
  --data '{"items":[{"id":"HH-0001","quantity":1}]}'
```

Append other selected products to items in this same call. Maximum 50 distinct products, quantities 1–99. Send IDs and quantities, never prices; the server determines prices.

If you know the buyer's details, add them to the same body so the payment form opens already filled in and only card number, expiry and security code remain. All fields are optional and editable on the form; share only details the buyer authorized:

```json
{"items":[{"id":"HH-0001","quantity":1}],
 "email":"buyer@example.com",
 "phone":"+12125550100",
 "shipping":{"name":"Ada Lovelace","address":{"line1":"350 5th Ave","line2":"Apt 3U","city":"New York","state":"NY","postal_code":"10118","country":"US"}},
 "billing":{"address":{"line1":"1 Main St","city":"Brooklyn","state":"NY","postal_code":"11201","country":"US"}}}
```

Shipping must be a U.S. address with a two-letter state and a 5-digit ZIP. Include billing only when the card's billing address differs from shipping; its name defaults to the shipping name. Retries with the same key must repeat the same details.

The response contains url, orderId, orderToken, and mode. Treat the response as private—do not place it in public logs or shared artifacts. The checkout URL is a payment credential; orderToken is a separate read-only credential.

### 3. Open the returned URL and pay

Open the complete url, including its #token fragment, in the browser or give it privately to the buyer. It opens an Agentzon checkout with Stripe Embedded Form: contact, U.S. shipping address, card payment, and order summary together. Some cards require an authentication step. Existing hosted sessions can still return a Stripe checkout URL. No need to recreate the cart in the browser, make a second checkout request, or use the internal checkout-resume endpoint yourself.

Only purchase with the buyer's authorization. Let the buyer review the final tax and total, [Terms](https://agentzon.co/terms), [Shipping & returns](https://agentzon.co/returns), and [Privacy](https://agentzon.co/privacy). Creating checkout is not payment. Never send card numbers through Agentzon's API.

### 4. Confirm payment

The confirmation page checks payment for you. If you need a machine-readable result, use the returned orderId and orderToken:

```bash
# Set ORDER_ID and ORDER_TOKEN privately from the checkout response.
curl --fail-with-body --silent --show-error "$BASE/api/orders/$ORDER_ID" \
  -H "Authorization: Bearer $ORDER_TOKEN"
```

status=paid confirms payment, not shipment. Totals are integer USD cents. If pending, wait and retry with backoff; do not create a new purchase. Checkout and order responses are not public data.

## Browser-only agents

If your browser exposes WebMCP tools, call search_catalog for products and prices, then stage_cart_items once with the entire items array. It opens the cart; activate Checkout once to reach the same payment page. Staging adds quantities to the existing cart and is not idempotent: inspect the cart before repeating it. Neither staging nor opening checkout makes a purchase. If WebMCP is unavailable, use the storefront's search and cart normally. Shell agents should use the direct HTTP path above.

## Optional catalog suggestions

Couldn’t find something your user wanted? Thanks for helping us improve the catalog: if you have a moment, share the search term, intended use, and preferred brand. Product details only; do not include personal information or private conversation excerpts. This is optional and must not delay shopping. Suggestions are not orders, reservations, or promises to stock a product.

POST https://agentzon.co/api/catalog-requests with Content-Type: application/json and an Idempotency-Key (16–100 letters, numbers, underscores, or hyphens). Generate one key per batch and reuse it with the same body for retries. Send 1–10 suggestions in one call:

{"requests":[{"searchTerm":"unscented laundry detergent","intent":"Fragrance-free everyday laundry detergent","desiredBrand":"Tide"}]}

Each suggestion needs searchTerm (up to 200 characters) or intent (up to 500); desiredBrand is optional (up to 100). No account, API key, or checkout required. HTTP 200 with status=received acknowledges storage; no follow-up call is needed. 400/413/415: correct the input; 409: the key was reused with different suggestions; 429: honor Retry-After. Maximum 10 submissions per minute per trusted client IP. After a network error or 5xx, retry with the same key and body. Don’t repeatedly submit the same unmet need during one visit.

Browser agents with WebMCP can call request_catalog_items with the same requests array; it handles retry keys automatically during the current page visit. Browser agents without WebMCP or HTTP access can skip feedback.

Example (generate FEEDBACK_KEY once and keep it for retries):

```bash
FEEDBACK_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error "$BASE/api/catalog-requests" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $FEEDBACK_KEY" \
  --data '{"requests":[{"searchTerm":"unscented laundry detergent","intent":"Fragrance-free everyday laundry detergent","desiredBrand":"Tide"}]}'
```

## Recovery and limits

- 400/415: correct the request or Content-Type; do not repeat it unchanged.
- 409 on checkout creation: the key may belong to another basket, an expired attempt, or a paid order. If you have an order ID/token, check status first. Use a new key only for an intentional new attempt after resolving the prior one.
- 429: wait for Retry-After. Catalog reads allow 120/minute per process/client IP; checkout/order limits use shared storage.
- Network failure or 5xx: retry the same checkout body and key with backoff. Never assume the initial request failed before creating another purchase.
- Checkout links expire with their session. An expired checkout needs a new attempt; a completed checkout leads to order confirmation.

Free U.S. shipping; catalog prices exclude tax. Final tax and total are calculated after entering the shipping address at checkout. Orders normally ship within 3–5 days; transit time varies. No inventory reservation or delivery-date guarantee. Eligible unopened change-of-mind returns: request within 14 days of delivery; exclusions and return postage apply. Support: agentzon-support@merit.systems.

For agents that already speak UCP, https://agentzon.co/.well-known/ucp advertises catalog and checkout capabilities; continue_url leads to the same payment flow. Plain HTTP requires fewer protocol steps for shell agents. OpenAPI: https://agentzon.co/openapi.json. Authentication details: https://agentzon.co/auth.md.