Skip to main content
Once the server is connected, you drive the whole shopping lifecycle in conversation. This guide covers the workflows and how to read what comes back.

​
Finding a product

If you don’t have a product URL, ask for one:
“Find me a stainless steel French press under $40.”
“Search for a USB-C hub with at least three ports.”
The results card lists products across Amazon, Walmart, Target, Best Buy, and more, ranked by rating and review volume. Every result carries an orderable URL — pick one and keep going in the same conversation.
Search is metered against your wallet at $0.01 per search. The assistant is instructed to search once with your best query rather than fanning out over variations, and to tell you rather than silently retry if a search fails for want of funds.
Already have a URL? Skip search entirely and paste it — that path is free.

​
Placing an order

To prepare an order the assistant needs three things:
  • A product URL from a supported retailer
  • A shipping address
  • A maximum price — the ceiling on the total, including tax and shipping
“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.”
A review card appears with the items, the destination, your price ceiling, and — if you granted wallet:read — whether your balance covers it. Nothing has been spent at this point. The order is placed only when you click Place order in that card.
max_price is the ceiling on the total, not the item price. Below a retailer’s free-shipping threshold, shipping is added on top, so leave room for it or the order trips max_price_exceeded.
The assistant cannot click the button for you and cannot place the order on its own — see how confirmation works.

​
Variants, quantity, and condition

  • Variants — “Order the Nike Dri-FIT tee in Large, blue.”
  • Multiple items — “Order two packs of AA batteries and one USB-C cable together, shipped to…”
  • Trial runs — a max price of $0.00 asks the retailer to validate the order without placing it. Nothing is charged. The result is recorded as order_failed with error_type: max_price_exceeded, which is the expected outcome, not a problem.

​
Checking status and tracking

Orders are asynchronous and usually take 5–10 minutes to reach the retailer.
“What’s the status of my last order?”
“Where’s order <id>? Any tracking yet?”
The order list renders as cards you can expand in place for live carrier checkpoints; get-order gives one order in full detail, with the retailer’s price breakdown and the shipment timeline.
order_placed is a terminal order status, not a delivery signal. Whether a package has shipped or arrived lives on the tracking rows, so ask for tracking rather than reading the order status.

​
Managing your wallet

“What’s my Zinc balance?”
The balance card shows your balance, your spendable balance, your per-order fee, and your saved payment methods.
Spendable is the number that matters. It sits below your raw balance while Stripe Connect holds are in flight, and it’s what an order is checked against.
To add funds:
“Add $50 to my Zinc wallet.”
A deposit card shows the amount credited, the processing fee for that payment method, the total you’ll be charged, and your projected balance. As with orders, nothing is charged until you click Add funds.
  • The self-serve minimum deposit is $15.00, so a smaller shortfall still needs a $15.00 top-up.
  • Card deposits credit immediately; bank transfers take a few business days to settle, and the card tells you which applies.
  • Adding a new payment method isn’t possible over MCP — by design, those routes are closed to MCP connections. Add a card in the dashboard first.
See Wallet for the full fee schedule.

​
Reading the cards

A few things about Zinc’s data model that the cards surface honestly rather than guessing at:
  • Money is exact. Every amount is a cent-precise value with a preformatted display string; nothing is rounded on the way to you.
  • There are no product titles. Zinc stores the retailer URL, not a product name, so line items are identified by URL. A title derived from the URL path was a guess and often wrong.
  • The retailer is inferred from those URLs — Zinc has no retailer field.
  • A price breakdown appears only once the retailer order is placed. Pending and failed orders have no total.
  • Order lists omit totals. The list endpoint doesn’t return them; ask for a specific order to see what was actually charged.

​
When something goes wrong

Order placement is the one moment where the failure matters, so it’s reported precisely:
If an outcome is uncertain, re-submitting the same confirmation card is always safe — it carries the same idempotency key and cannot create a second order. Running a new prepare-order is not: a new confirmation is a new order.
Common order failures are the same ones the API reports — max_price_exceeded, product_out_of_stock, invalid_shipping_address, product_variant_required, retailer_unavailable. See Error Handling for the full list.

​
Not available over MCP

Some Zinc operations aren’t exposed as MCP tools yet. Use the dashboard or the API for:

​
Tips

  • Set the max price to cover the full cost — item plus tax plus shipping.
  • Paste a product URL when you have one. Search costs money; ordering from a URL doesn’t.
  • Use direct product URLs, not category or search-result pages.
  • Reading is free and safe. Order lists, detail, tracking, and balance never spend anything.
  • Only your click spends money. If no card with a button appeared, nothing was bought.