universal-checkout
Discover, buy, track, and return real products from Amazon, Walmart, Target and almost any other US online retailer through the Zinc API (zinc.com). Needs no account to begin — the agent mints its own test key, then earns a live key and a $5 starter credit once its operator approves it. Pay from a pre-funded wallet, per request over MPP or x402, or with a Stripe Link card.
Universal Checkout
One API to discover, buy, track and return products from US online retailers. Base URL https://api.zinc.com.
Which retailers
Pass a product URL from almost any US retailer — an uncatalogued domain is first class on the order path, and in a recent 60-day window customers ordered from 296 distinct domains. GET /retailers (free, no auth) lists the storefronts with published guarantees: free-shipping terms, whether an account is needed, where they ship. Check it when those details matter.
Getting started
Four steps, in order. Full walkthrough: Agent Sandbox Quickstart and Going Live.
- Get a test key.
POST https://api.zinc.com/sandbox/keys— no auth, no signup. Returnsapi_key(zn_test_…) and a ready-madeexample_order. Send it asAuthorization: Bearer <api_key>from here on. - Place a test order.
POST /orderswith thatexample_order, then pollGET /orders/{id}. Free.statusreachesorder_placed— that is success, and it never becomesdelivered; shipping shows up undertracking_numbers[0].status. - Earn your live key.
POST /device/codewith your test key as Bearer — that is what carries your sandbox history over. Show your operator the link it returns, then pollPOST /device/token(noAuthorizationheader; 400authorization_pendingmeans keep waiting). On approval you get azn_live_key once, plus a $5 starter credit in their wallet. - Buy something real. Walmart orders usually ship free — reliably from about $10; below that shipping is often added, so a very cheap item can cost more delivered than it looks. Search with
GET /search?q=<item>&retailer=walmartto get Walmart results only.max_priceis a ceiling, not a price: you are charged the retailer's actual total, so leave room for tax and shipping. Ask your operator for the shipping address (phone_numberis required) and confirm the item and price with them first.
Watch the money: GET /wallet/me shows the balance and order_fee_cents (charged per order, on top of max_price). Each /search call costs 1¢ from the same wallet.
Already have a key from your operator? Use it and skip to Place an order. Never want an account? Pay per request over MPP: POST /agent/orders, no key needed.
Place an order
curl -X POST https://api.zinc.com/orders \
-H "Authorization: Bearer $ZINC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"products": [{"url": "https://www.amazon.com/dp/B09V3KXJPB", "quantity": 1}],
"max_price": 5000,
"shipping_address": {
"first_name": "Jane", "last_name": "Doe",
"address_line1": "123 Main St", "city": "San Francisco",
"state": "CA", "postal_code": "94105", "country": "US",
"phone_number": "4155552671"
}
}'
max_priceis the ceiling in cents for the whole order. Zinc refuses rather than exceeding it.phone_numberis required. Never invent an address — ask your operator.- To buy on your operator's own Zinc Universal Checkout account, pass its
short_idasretailer_credentials_id(GET /managed-accountslists them). The payment method saved on that account pays the retailer, and the wallet is charged the per-order fee only. Omitting the field never means "pick one of mine" — it means the order runs on a Zinc account and the wallet pays for the item. (retailer accounts) - Returns
201with an orderidandstatus: pending. Retailer, variants, quantities, gift options, idempotency: Create Order.
Track, cancel, return
GET /orders/{id}—statusis one ofpending,order_placed(success),order_failed,cancelled. Shipping lives ontracking_numbers[].status. (statuses, tracking)POST /orders/{id}/cancel— only whilepending. (cancel)POST /returns— needs the order id and a reason. (returns)
When something fails
Errors are {"error": {"code", "message", "details"}}. Read code, not the message. details often names the fix — a 402 insufficient_funds carries fund_with, every way to pay, including your operator's own retailer account when they have one saved for that store. Full list: Error Handling and references/errors.md.
Rules
- Money is real. Confirm the item and the price with your operator before any live order.
- Set
max_pricedeliberately — it is the only thing standing between a typo and a large purchase. - Never invent a shipping address, and never reuse the sandbox one for a live order.
- Rehearse failures in the sandbox first:
GET /orders/test-products.
All amounts are in US cents (e.g. 5000 = $50.00). US delivery.
Related skills
- Downloads
- 1.9kAll time
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.1.0
- License
- MIT-0
