> ## Documentation Index
> Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Guide

> Discover products, place orders, track them, and handle returns through your AI agent.

Once the Universal Checkout Skill is [installed and configured](/v2/agent-skills/setup), 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.

<Tip>
  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.
</Tip>

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

<Info>
  `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`.
</Info>

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

<Info>
  `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.
</Info>

## 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](https://app.zinc.com), 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.                                   |

For the complete list, see the [Error Handling](/v2/api-reference/introduction/error-handling) reference.

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