> ## 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 supported retailer in one call — 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.
</Warning>

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

Each result's `url` is the orderable retailer URL: pass it directly to [Create order](/v2/api-reference/orders/create-order). There is no opaque sku id and no separate ASIN / item-id field — the URL is the contract.

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

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

## 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.
  * No `limit`, `sort`, or `filter` parameters yet.
  * Response shape may add fields (e.g. condition, shipping ETA). Existing fields won't be removed without notice.
</Warning>

## Help shape the beta

<Card title="Customer interview — 30 minutes · $50 Amazon gift card" icon="calendar" href="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**.
</Card>

<RequestExample>
  ```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();
  ```
</RequestExample>

<ResponseExample>
  ```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",
        "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",
        "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",
        "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",
        "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"
  }
  ```
</ResponseExample>


## 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.
  version: '2026-06-11'
  x-logo:
    url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
  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 (e.g. Amazon),
    shipping address, and max_price in cents. The API charges max_price + $1 API
    fee upfront and refunds the difference on completion. Authenticated
    endpoints (orders, products, managed-accounts) require a Bearer token (API
    key prefixed zn_). Docs: https://zinc.com/docs
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.
      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: 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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SearchResponse:
      properties:
        status:
          type: string
          title: Status
        query:
          type: string
          title: Query
        results:
          items:
            $ref: '#/components/schemas/Sku'
          type: array
          title: Results
          default: []
      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
        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
      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_...)

````