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

# Cross-Retailer Search

> Search every retailer Zinc supports in a single API call to compare products and prices (beta).

> [!WARNING]
>
> **Beta** — this endpoint is in active development and may change without notice. Field names, ranking, and coverage are still evolving. We'd love your feedback: [**book a 30-minute customer interview**](https://cal.com/zinc-ian/customer-interview) and help shape the v1 — **we'll send you a \$50 Amazon gift card** as a thank-you.

`GET /search` returns a single ranked list of buyable products across every supported retailer — Amazon, Walmart, Target, Best Buy, Home Depot, Lowe's, Costco, Wayfair, Macy's, and more — in one call.

Each result's `url` is the orderable retailer URL: pass it directly to [Create order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md). Results from retailers with live product data also carry a `product_id` for checking the current price before you order; see [Live details and offers](#live-details-and-offers).

This is distinct from the per-retailer [`/products/search`](https://www.zinc.com/docs/v2/api-reference/products/search), which searches one retailer at a time. Use `/search` when you want breadth.

**On this page:** [Pricing](#pricing) · [Ranking](#ranking) · [Filtering and sorting](#filtering-and-sorting) · [Live details and offers](#live-details-and-offers) · [Beta limits](#beta-limits) · [Help shape the beta](#help-shape-the-beta)

## Pricing

| | |
| - | - |
| **Price** | \$0.01 per call, drawn from your [wallet](https://www.zinc.com/docs/v2/wallet.md) |
| **Charged** | On each successful search, before any order is placed |
| **Empty wallet** | `402` with `{"detail": "Insufficient wallet balance for data API call"}` |
| **Sandbox** | Free — `zn_test_` keys are never metered |

> [!WARNING]
>
> Search is billed whether or not you go on to order. A retry loop bills every attempt: check [`GET /wallet/me`](https://www.zinc.com/docs/v2/api-reference/wallet/get-wallet) rather than retrying into a 402.

The MPP counterpart [`POST /agent/search`](https://www.zinc.com/docs/v2/api-reference/agent/search) is the same search at the same price, paid per request instead of from a wallet.

## Ranking

Results are ranked by a quality signal that combines rating and review volume, with price as a tiebreaker for unrated items. The list is then woven across retailers so a single retailer doesn't dominate the top — typically you'll see two or three different retailers in the first few results.

## Filtering and sorting

All three parameters are optional. With none set, a search behaves exactly as described above.

| Parameter | Description |
| - | - |
| `retailer` | Search only these retailers. Repeat it for several: `?retailer=amazon&retailer=target`. Accepts the slugs listed in the parameter reference below, `etsy`, and up to 3 Shopify stores (see below). |
| `sort` | `relevance` (default), `price_asc`, `price_desc`, or `rating`. |
| `limit` | Return at most this many results, 1–50. |

The explicit sorts don't reorder every result. They take the 20 most relevant results (or `limit`, if larger) that match at least half the query, then sort those, so a cheap accessory that merely names the product can't lead a `price_asc` page. Results with no price (or no rating, for `rating`) sort last.

A search costs one billed call whatever `limit` you set.

### Named retailers

Naming retailers searches only those retailers, rather than narrowing a search of every retailer, so you get a full page from the ones you named. Name several and they're searched together, so results come from each one that carries the item. A retailer with nothing matching the query has no results; the others still return theirs.

> [!NOTE]
>
> **Costco** is accepted but currently returns no results: the search source doesn't list Costco's products. **Newegg** results are sparse for the same reason.

### Shopify stores

`retailer` also takes up to 3 Shopify stores, by their retailer slug (e.g. `retailer=yetch`) or domain. [`GET /retailers/check?url=`](https://www.zinc.com/docs/v2/api-reference/retailers/check-retailer) returns a store's slug.

* A store in the filter is searched directly, using the store's own search. A filter of only stores (`?retailer=yetch`) searches just those stores; mix in other retailers (`?retailer=amazon&retailer=yetch`) and the results are ranked together.
* Each result's `url` is on the store's public domain, so it goes straight to [Create order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md). `retailer` is the store's slug.
* With a live key, a store not yet in Zinc's catalog is checked and added the first time you name it by domain, exactly as on [Search Products](https://www.zinc.com/docs/v2/api-reference/products/search.md#new-shopify-stores), with the same `422`, `503` and `429` answers when it can't be. In test mode and on `POST /agent/search`, an uncatalogued store returns `422`.
* More than 3 stores returns `422`. If one store's search fails, the others' results are still returned.
* It's still one billed call, however many stores the filter names.

### Etsy

`retailer=etsy` (or `etsy.com`) searches Etsy directly, the same way a store is searched. Etsy can be combined with other retailers and stores, and it doesn't count toward the 3-store limit.

* Each result's `url` is the Etsy listing. `retailer` is `etsy`.
* Results have no `stars` or `num_reviews`. Etsy publishes no product-level rating, so `sort=rating` puts Etsy results last.
* Only listings priced in US dollars are returned.
* `has_variants` says whether a listing has options, such as size or color, that must be chosen before it can be ordered. `false` means it can be ordered as is. When it's `true`, the API can't tell you what the options are: Etsy shares them only with the listing's own shop. Read them from the listing page, then pass the buyer's choice as `variant` when you [create the order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md): one `{label, value}` pair per option, using the option name and choice as the listing shows them (e.g. `{"label": "Size", "value": "Large"}`). Etsy won't cart a listing with options until one is chosen, so expect an order without `variant` to fail. `has_variants` is `null` on other retailers' results.

```bash theme={null}
curl "https://api.zinc.com/search?q=cast+iron+skillet&retailer=amazon&retailer=target&sort=price_asc&limit=10" \
  -H "Authorization: Bearer <your_api_key>"
```

## Live details and offers

Search prices come from the search source and can lag the retailer's page. To check a result before ordering, pass its `product_id` and `retailer` to the product endpoints:

```bash theme={null}
curl "https://api.zinc.com/products/B00006JSUC?retailer=amazon" \
  -H "Authorization: Bearer <your_api_key>"
```

| Result's `retailer` | `product_id` | [Get Product](https://www.zinc.com/docs/v2/api-reference/products/get-product.md) | [Get Product Offers](https://www.zinc.com/docs/v2/api-reference/products/get-product-offers.md) |
| - | - | - | - |
| `amazon` | ASIN | Yes | Yes |
| `walmart` | Item id | Yes | Yes |
| `etsy` | Listing id | Yes | No (`400`): price is on details |
| A Shopify store's slug | Product handle | Yes | No (`400`): per-variant prices are on details |
| Any other retailer | `null` | — | — |

* Pass `retailer` exactly as the result has it. A result with `product_id: null` can still be ordered by its `url`.
* Each call is billed like a search: \$0.01 from your [wallet](https://www.zinc.com/docs/v2/wallet.md), free in test mode. Test-mode results come back from these endpoints with matching synthetic data.
* On the MPP rail, use [`POST /agent/products/details`](https://www.zinc.com/docs/v2/api-reference/agent/product-details) and [`POST /agent/products/offers`](https://www.zinc.com/docs/v2/api-reference/agent/product-offers) with the same `product_id` and `retailer`.

## Beta limits

> [!WARNING]
>
> These will change before v1:
>
> * No condition filter — used / marketplace listings may appear when the source doesn't expose condition.
> * Coverage varies by query; some long-tail and DTC retailers may not appear.
> * `retailer` is the only filter; there's no brand, category, or rating filter yet.
> * Shopify stores and Etsy appear only when named in `retailer`; an unfiltered search doesn't include them.
> * Response shape may add fields (e.g. condition, shipping ETA). Existing fields won't be removed without notice.

## Help shape the beta

> [card] [Customer interview — 30 minutes · \$50 Amazon gift card](https://cal.com/zinc-ian/customer-interview)
>
> We're actively iterating on `/search`. Tell us what queries you're running, what coverage you need, and what's missing. As a thank-you we'll send you a **\$50 Amazon gift card**.

```bash cURL theme={null}
curl https://api.zinc.com/search?q=cast+iron+skillet \
  -H "Authorization: Bearer <your_api_key>"
```

```python Python theme={null}
import requests

res = requests.get(
    "https://api.zinc.com/search",
    params={"q": "cast iron skillet"},
    headers={"Authorization": "Bearer <your_api_key>"},
)
res.raise_for_status()
results = res.json()["results"]
```

```javascript Node theme={null}
const res = await fetch(
  "https://api.zinc.com/search?q=" + encodeURIComponent("cast iron skillet"),
  { headers: { Authorization: "Bearer <your_api_key>" } }
);
const { results } = await res.json();
```

```json 200 OK theme={null}
{
  "status": "completed",
  "query": "cast iron skillet",
  "results": [
    {
      "url": "https://www.wayfair.com/cookware/pdp/lodge-cast-iron-skillet-6-5-...",
      "retailer": "wayfair",
      "product_id": null,
      "title": "Lodge Cast Iron Skillet 6.5\" Black/Gray, Pre-Seasoned",
      "image": "https://thf.bing.com/th?id=OPHS.DO%2fNmrRBpgF0sA474C474&w=220&h=220",
      "brand": null,
      "price": 1890,
      "stars": 4.7,
      "num_reviews": 1000,
      "available": null
    },
    {
      "url": "https://www.homedepot.com/p/10-5-in-Cast-Iron-Skillet-In-Black/...",
      "retailer": "homedepot",
      "product_id": null,
      "title": "10.5 in. Cast Iron Skillet In Black",
      "image": "https://thf.bing.com/th/id/OPHS.Jv2SxDM0Y6PO8g474C474?w=220&h=220",
      "brand": null,
      "price": 2490,
      "stars": 4.7,
      "num_reviews": 1000,
      "available": null
    },
    {
      "url": "https://www.target.com/p/lodge-12-cast-iron-skillet/-/A-...",
      "retailer": "target",
      "product_id": null,
      "title": "Lodge 12\" Cast Iron Skillet: Preseasoned, Non-Stick, Scratch-Resistant",
      "image": "https://thf.bing.com/th/id/OPHS.W0Kf0gUKdW1yoA474C474?w=220&h=220",
      "brand": null,
      "price": 2999,
      "stars": 4.7,
      "num_reviews": 1000,
      "available": null
    },
    {
      "url": "https://www.amazon.com/dp/B00006JSUC",
      "retailer": "amazon",
      "product_id": "B00006JSUC",
      "title": "Lodge L8SK3 10.25-inch Pre-Seasoned Cast Iron Skillet",
      "image": "https://m.media-amazon.com/images/I/81ysMDr2VgL._AC_UL320_.jpg",
      "brand": "Lodge",
      "price": 2497,
      "stars": 4.8,
      "num_reviews": 132840,
      "available": true
    }
  ]
}
```

```json 401 Unauthorized theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "details": null
  }
}
```

```json 402 Payment Required theme={null}
{
  "detail": "Insufficient wallet balance for data API call"
}
```


## OpenAPI

````yaml versions/latest.json GET /search
openapi: 3.1.0
info:
  title: Zinc
  summary: >-
    Zinc lets you search, buy, and return items from top online retailers with a
    single API.
  description: >-
    Search, buy, and return items from top online retailers with a single API.
    Supports AI agent ordering via MPP (HTTP 402) — no account required.
    Supported retailers include 1-800-Flowers, Ace Hardware, AliExpress, Amazon,
    Amazon AU, Amazon CA, Amazon DE, Amazon ES, Amazon FR, Amazon IT, Amazon MX,
    Amazon UK, and 23 more. Ships to the US and 7 other countries (CA, DE, ES,
    FR, GB, IT, MX). The listed retailers are the ones Zinc verifies with daily
    test orders, not the limit of what Zinc can buy from: checkout is attempted
    at most online stores, including Shopify-hosted ones. To ask about a
    specific store before ordering, call GET /retailers/check?url=... — it
    answers whether Zinc will attempt that URL.
  version: '2026-10-30'
  x-logo:
    url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
  contact:
    name: Zinc API Support
    email: support@zinc.com
    url: https://zinc.com/docs
  x-guidance: >-
    Zinc lets AI agents buy products from online retailers via a single API. Use
    POST /agent/orders to place an order — no Zinc account needed, payment is
    handled via MPP (HTTP 402 flow). Provide a product URL from a supported
    retailer, a shipping address, and max_price in cents. The API charges
    max_price + $1 API fee upfront and refunds the difference on completion. To
    find products first, the /agent/* data endpoints (search, products/search,
    products/offers, products/details) are MPP-paid at $0.01 per call;
    /agent/search returns orderable URLs to feed straight into /agent/orders.
    GET /retailers lists supported retailers for free (no payment or account).
    Authenticated equivalents (orders, products, managed-accounts) require a
    Bearer token (API key prefixed zn_); those orders are paid from a prefunded
    wallet — GET /wallet/me returns the spendable balance and per-order fee, so
    check it before POST /orders to avoid a 402. Orders are strict by default:
    if the gift option can't be applied or any item can't be bought, the whole
    order fails. When the user wants whatever can be shipped, send fulfillment:
    {"gift": "best_effort", "items": "best_effort"} and read
    fulfillment.concessions on the order to see what was relaxed. max_price is
    never relaxed. Docs: https://zinc.com/docs Supported retailers include
    1-800-Flowers, Ace Hardware, AliExpress, Amazon, Amazon AU, Amazon CA,
    Amazon DE, Amazon ES, Amazon FR, Amazon IT, Amazon MX, Amazon UK, and 23
    more, shipping to the US and 7 other countries (CA, DE, ES, FR, GB, IT, MX).
    The listed retailers are the ones Zinc verifies with daily test orders, not
    the limit of what Zinc can buy from: checkout is attempted at most online
    stores, including Shopify-hosted ones. To ask about a specific store before
    ordering, call GET /retailers/check?url=... — it answers whether Zinc will
    attempt that URL.
  x-supported-retailers:
    - 1-800-Flowers
    - Ace Hardware
    - AliExpress
    - Amazon
    - Amazon AU
    - Amazon CA
    - Amazon DE
    - Amazon ES
    - Amazon FR
    - Amazon IT
    - Amazon MX
    - Amazon UK
    - Barnes & Noble
    - Best Buy
    - Chewy
    - Gap
    - Grainger
    - IBS
    - Lowe's
    - Macys
    - McMaster-Carr
    - Partstown
    - Pokémon Center
    - Sephora
    - Shein
    - Temu
    - The Home Depot
    - TikTok
    - Uniqlo
    - Walmart
    - Wayfair
    - Zinc
    - eBay
    - libraccio
    - zazzle
  x-supported-countries:
    - US
    - CA
    - DE
    - ES
    - FR
    - GB
    - IT
    - MX
servers:
  - url: https://api.zinc.com
    description: Production
security:
  - BearerAuth: []
paths:
  /search:
    get:
      tags:
        - search
      summary: Search
      description: >-
        Search for products across retailers; returns orderable zn_sku_
        listings.


        **Billing.** This is a metered data call: $0.01 is drawn from your
        wallet per successful request, before any order is placed. An empty
        wallet gets `402` instead. Sandbox (`zn_test_`) calls are free, return
        synthetic sample data (marked `X-Zinc-Test-Data: synthetic`) and never
        touch the live wallet, up to 10,000 per account per UTC day; past that
        they get `429` until midnight UTC.
      operationId: search_search_get
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            description: Search term
            title: Q
          description: Search term
        - name: min_price
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            description: Cents. Drop results priced below this.
            title: Min Price
          description: Cents. Drop results priced below this.
        - name: max_price
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            description: >-
              Cents. Drop results priced above this. Pass the `max_price` you
              intend to send to POST /orders and every result returned fits it.
              Results with no known price are dropped when a clamp is set.
            title: Max Price
          description: >-
            Cents. Drop results priced above this. Pass the `max_price` you
            intend to send to POST /orders and every result returned fits it.
            Results with no known price are dropped when a clamp is set.
        - name: retailer
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only return results from these retailers. Repeat the param for
              several: `?retailer=amazon&retailer=target`. Takes the discovery
              retailers (amazon, bestbuy, bhphotovideo, chewy, costco,
              homedepot, kohls, lowes, macys, newegg, staples, target, walmart,
              wayfair), `etsy`, and up to 3 catalogued Shopify stores by their
              Zinc retailer slug (e.g. `retailer=yetch`; a store's domain also
              works). Etsy and stores are searched directly, and only when named
              here: an unfiltered search never includes them. Etsy results are
              listings: when `has_variants` is true the order needs a `variant`,
              and the options must be read from the listing page, because Etsy
              shares them only with the listing's own shop. With a live key, a
              Shopify store not yet catalogued is added on first use by its
              domain.
            title: Retailer
          description: >-
            Only return results from these retailers. Repeat the param for
            several: `?retailer=amazon&retailer=target`. Takes the discovery
            retailers (amazon, bestbuy, bhphotovideo, chewy, costco, homedepot,
            kohls, lowes, macys, newegg, staples, target, walmart, wayfair),
            `etsy`, and up to 3 catalogued Shopify stores by their Zinc retailer
            slug (e.g. `retailer=yetch`; a store's domain also works). Etsy and
            stores are searched directly, and only when named here: an
            unfiltered search never includes them. Etsy results are listings:
            when `has_variants` is true the order needs a `variant`, and the
            options must be read from the listing page, because Etsy shares them
            only with the listing's own shop. With a live key, a Shopify store
            not yet catalogued is added on first use by its domain.
        - name: sort
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SearchSort'
            description: >-
              Result order. `relevance` (default) blends query match, source
              rank and rating, and mixes retailers. The explicit sorts order the
              20 most relevant results (or `limit`, if larger) that match at
              least half the query, so accessories that merely name the product
              don't lead; results with no price (or no rating, for `rating`)
              sort last.
            default: relevance
          description: >-
            Result order. `relevance` (default) blends query match, source rank
            and rating, and mixes retailers. The explicit sorts order the 20
            most relevant results (or `limit`, if larger) that match at least
            half the query, so accessories that merely name the product don't
            lead; results with no price (or no rating, for `rating`) sort last.
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 50
                minimum: 1
              - type: 'null'
            description: >-
              Return at most this many results (1-50). One search is one billed
              call either way.
            title: Limit
          description: >-
            Return at most this many results (1-50). One search is one billed
            call either way.
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '402':
          description: >-
            Insufficient wallet balance for the data-API fee. Fund the wallet
            (or check `GET /wallet/me`) and retry. Postpaid plan customers are
            never gated here.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                  - detail
              example:
                detail: Insufficient wallet balance for data API call
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SearchSort:
      type: string
      enum:
        - relevance
        - price_asc
        - price_desc
        - rating
      title: SearchSort
      description: >-
        Result order for /search. Explicit sorts order only the most relevant

        on-topic results, so a cheap accessory that names the product can't lead
        a

        price-sorted page.
    SearchResponse:
      properties:
        status:
          type: string
          title: Status
        query:
          type: string
          title: Query
        results:
          items:
            $ref: '#/components/schemas/Sku'
          type: array
          title: Results
          default: []
        excluded_by_price:
          anyOf:
            - type: integer
            - type: 'null'
          title: Excluded By Price
          description: >-
            How many orderable results the min_price/max_price clamp removed;
            null when no clamp was set.
        hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Hint
          description: >-
            Set when the result list is empty for a reason the caller can act
            on.
      type: object
      required:
        - status
        - query
      title: SearchResponse
      description: Response from the cross-retailer search endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Sku:
      properties:
        url:
          type: string
          title: Url
        retailer:
          type: string
          title: Retailer
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
          description: >-
            The id to look this listing up by on /products/*: pass it with
            `retailer` to /products/{product_id} for live details, and to
            /products/{product_id}/offers (Amazon and Walmart) for live offers.
            ASIN on Amazon, item id on Walmart, listing id on Etsy, product
            handle on a Shopify store. Null when /products/* doesn't cover the
            retailer, or the listing's id isn't known.
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        image:
          anyOf:
            - type: string
            - type: 'null'
          title: Image
        brand:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand
        price:
          anyOf:
            - type: integer
            - type: 'null'
          title: Price
        stars:
          anyOf:
            - type: number
            - type: 'null'
          title: Stars
        num_reviews:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Reviews
        available:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Available
        free_shipping:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Free Shipping
          description: >-
            True when the retailer listing advertises free shipping; null when
            unknown (never false — providers only flag the free case).
        has_variants:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Variants
          description: >-
            Etsy only: true when the listing needs an option chosen (size,
            color...) before it can be ordered; pass the choice as `variant` on
            the order. The options themselves aren't listed. Null for other
            retailers.
      type: object
      required:
        - url
        - retailer
      title: Sku
      description: A cross-retailer buyable listing. Pass `url` to /orders to buy it.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Zinc API key (Bearer zn_...)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.