# Agentzon

> A catalog of 500 household essentials from familiar brands. Checkout is available. U.S. shipping is free. Catalog prices exclude sales tax; final tax and total are calculated after the shipping address is entered at checkout. Products without prices cannot be purchased.

## Shortest shopping path
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.
Runnable shell guide: https://agentzon.co/agents.md. If you have shell/network access, use the HTTP API to avoid repeated browser interactions.
1. GET /api/products?q=... returns product IDs, names, pack sizes, prices, images and checkout availability together. Skip separate product and availability lookups unless you need them. Use one search per distinct need; query words are ANDed, not a multi-product shopping list.
2. Keep the selected IDs and quantities locally. POST the entire basket to /api/checkout once. If you know the buyer's email, phone or addresses, include them so the payment form is prefilled and only card details remain. No server cart or add-to-cart calls are required. If you already know valid IDs, skip search.
3. Open the returned private url to review shipping, tax and pay with Stripe Embedded Form on Agentzon. Some cards require an authentication step. Existing hosted sessions may still return a Stripe URL.
4. After payment, use the confirmation page or one authenticated order lookup. Poll only while payment is pending, with backoff.
This is normally two API calls before payment for one search: search + checkout. Payment and confirmation have their own requests. No registration or API keys.

## Catalog API
- Search: https://agentzon.co/api/products?q=Tide&limit=20&offset=0
- Product details: https://agentzon.co/api/products/HH-0001
- Product image (image/webp bytes): https://agentzon.co/api/products/HH-0001/image
- Human product page: https://agentzon.co/product/HH-0001

Search accepts q (up to 200 characters), category, brand, sort (featured/low/high/az), limit (1–100), and offset. All query words must match. Category and brand filters use exact catalog names. Results include categories, total, nextOffset, referencePrice, priceStatus, imageUrl, and checkoutAvailable. A null referencePrice means unknown, never free.

Read-only API requests allow cross-origin access. The local limiter allows 120 requests per minute per process and trusted client IP, with a shared bucket when client IP is unavailable. HTTP 429 includes Retry-After. Invalid queries return 400; unknown products return 404.

## Browser tools
Where document.modelContext is supported, the storefront exposes search_catalog and stage_cart_items. Staging only updates the visible cart; it does not place an order. This is browser WebMCP, not a remote MCP endpoint.

## 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.

## Discovery
- OpenAPI description: https://agentzon.co/openapi.json
- API catalog (RFC 9727): https://agentzon.co/.well-known/api-catalog
- Markdown pages: request https://agentzon.co/ or https://agentzon.co/product/HH-0001 with Accept: text/markdown.
- Authentication: https://agentzon.co/auth.md. No registration or API keys; order lookups use the per-order token from checkout.
- Universal Commerce Protocol (UCP 2026-08-25): business profile at https://agentzon.co/.well-known/ucp, REST endpoint https://agentzon.co/api/ucp. Supports catalog search and lookup and checkout sessions. UCP checkouts always return requires_escalation; send the buyer to continue_url to pay through Stripe Embedded Form on Agentzon. Requests need a UCP-Agent header with your platform profile URL.

## Seller and policies
Agentzon is operated by Merit Systems Inc, the seller and merchant of record. Support, cancellations, returns, and refunds: agentzon-support@merit.systems.
- Terms: https://agentzon.co/terms
- Shipping and returns: https://agentzon.co/returns
- Privacy: https://agentzon.co/privacy
Present these policies to the buyer before purchase. Eligible unopened change-of-mind returns must be requested within 14 days of delivery; exclusions apply and the customer pays return postage. These limits do not restrict remedies for incorrect, damaged, or defective goods or mandatory legal rights. Unless otherwise stated before purchase, orders ship within 3–5 days; this is not a delivery guarantee. Do not promise stock or delivery dates not shown by the seller. Only make purchases with the buyer's authorization.

## Checkout and orders
- GET https://agentzon.co/api/checkout returns checkout availability and mode. Production checkout accepts real payments.
- POST https://agentzon.co/api/checkout with Content-Type: application/json and a unique Idempotency-Key header (16–100 alphanumeric, underscore, or hyphen characters).
- Body: {"items":[{"id":"HH-0001","quantity":1}]}. Submit product IDs and quantities, never prices. Prices are resolved on the server. Maximum 50 distinct products and quantity 1–99 per product. Reuse the same key for retries of the same cart; use a new key for a new purchase. HTTP 409 means the attempt expired, completed, or was reused with another cart or other buyer details.
- Optional prefill in the same body: email, phone, shipping and billing. Example: {"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"}}}. Shipping must be a U.S. address with a two-letter state and a 5-digit ZIP. Send billing (same shape; name defaults to the shipping name) only when the card's billing address differs from shipping. Every field is optional and stays editable in the form. Share only details the buyer authorized; Agentzon keeps them privately until the checkout ends.
- Response: url (private checkout URL; preserve the fragment), orderId, orderToken, mode. Open url for the buyer to review and pay. Never treat session creation as payment confirmation.
- GET https://agentzon.co/api/orders/ORDER_ID with Authorization: Bearer ORDER_TOKEN returns verified payment status and totals in integer USD cents. Keep the order token and checkout URL private. The order token is read-only; the checkout URL grants access to the payment form. A paid status confirms payment, not shipment.
- Checkout and order endpoints are rate limited in shared Postgres storage and return HTTP 429 with Retry-After.