Once the Universal Checkout Skill is installed and configured, you can drive the full shopping lifecycle through natural language. This guide covers the key workflows.
Finding Products
Don’t have a product URL? The skill searches across retailers for you via the Zinc API — just ask:
“Search for a highly-rated French press coffee maker under $40.”
“Find me a USB-C hub with at least 3 ports.”
The agent calls GET /search, which returns directly orderable URLs across Amazon, Walmart, Target, Best Buy, Home Depot, and more. Pick one and continue to checkout in the same conversation. For Amazon and Walmart, the agent can also compare best-price offers before ordering.
No setup or separate search tool required — product discovery is built into
the skill. On the MPP rail, search and product-data calls are metered at
$0.01 each.
Placing an Order
To place an order, provide your agent with:
- A product URL from a supported retailer (or a search query, above)
- A shipping address
- A maximum price — the total ceiling including tax and shipping
Example prompts:
“Search for a French press coffee maker under $40, then order the best option. Ship it to Jane Doe, 123 Main St, San Francisco, CA 94105.”
“Buy this: https://www.amazon.com/dp/B0EXAMPLE — ship to Jane Doe, 123 Main St, San Francisco, CA 94105. Don’t spend more than $50.”
The agent constructs the request and asks for confirmation before submitting, since placing an order spends real money.
max_price is the total ceiling — item price plus tax and shipping.
Below a retailer’s free-shipping threshold, shipping is added to the total, so
leave room for it or the order trips max_price_exceeded.
Variants, quantity, and condition
- Variants — “Find a Nike Dri-FIT t-shirt in size Large and color Blue, then order it.”
- Multiple products / quantity — “Order 2 packs of AA batteries and 1 USB-C cable together. Ship to…”
- Condition — “Order this, but a used-like-new copy is fine if it’s cheaper.” (the agent allows used/refurbished conditions to find a cheaper offer)
Checking Order Status
Orders process asynchronously and typically take 5–10 minutes. Ask:
“What’s the status of my last order?”
“Where’s order <id>? Any tracking yet?”
The agent returns the status plus tracking — including the carrier, tracking number, current shipment status, and the full checkpoint timeline of carrier scans.
Order Statuses
| Status | Meaning |
|---|
pending | Order received, not yet processing |
in_progress | Order is being placed with the retailer |
order_placed | Order completed successfully |
order_failed | Order could not be completed |
cancelled | Cancelled by you |
cancelled_by_retailer | Cancelled by the retailer |
order_placed, order_failed, cancelled, and cancelled_by_retailer are
terminal. If the status is pending or in_progress, check again in a few
minutes.
Cancelling an Order
“Cancel order <id>.”
An order can be cancelled only while it’s still pending (queued). Once it’s in_progress or complete, it can’t be cancelled.
Returns
Open a return against a placed order:
“Return the coffee maker from order <id> — it arrived damaged.”
The agent submits the return with a reason and gives you back the prepaid shipping label URLs. Return status moves open → approved | denied | credited.
Listing Orders
“List my recent Zinc orders.”
Returns a summary with IDs, statuses, and timestamps. Tracking status is included by default.
Error Handling
If something fails, the agent reports the error. Common ones:
| Error | What to Do |
|---|
max_price_exceeded | Total (incl. tax + shipping) exceeds your max price. Raise the limit or pick another item. |
product_out_of_stock | The product is unavailable. Try again later or choose an alternative. |
invalid_shipping_address | Check the address fields (state must be 2-letter, country ISO alpha-2). |
insufficient_funds | Deposit more funds in your Zinc account, or check your MPP balance. |
product_variant_required | The product has variants (size, color, etc.) that must be specified. |
retailer_unavailable | The retailer is temporarily unavailable. Try again later. |
Tips
- Set
max_price to cover the full cost — item + tax + shipping — not just the item.
- Use direct product URLs (or let the agent search), not category or search-results pages.
- Check status after a few minutes — orders are asynchronous.
- Reading is always safe. Search, status checks, and listing never spend money. Only placing an order or opening a return needs confirmation.
