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

# Check a Retailer

> Ask whether Zinc can buy from a given store URL and ship it to a country — no authentication required.

The question [`GET /retailers`](/docs/v2/api-reference/retailers/list-retailers) cannot answer. That endpoint returns the curated catalog, but the order path accepts any reachable store — so a caller holding an arbitrary product URL finds nothing in the list and has no way to tell whether an order would go through. Pass the URL here instead.

**No authentication required.** Read-only: asking never adds a store to the catalog.

```bash theme={null}
curl "https://api.zinc.com/retailers/check?url=https://www.amazon.com/dp/B08N5WRWNW&country=US"
```

`orderable` is the answer. `support` grades how much evidence Zinc has behind it.

## Support tiers

| Tier | Meaning | `orderable` |
| - | - | - |
| `verified` | Curated, and its daily test order is passing. | `true` |
| `active` | Real customer orders succeeded here in the last 90 days. | `true` |
| `observed` | Zinc has attempted orders here. | `true` |
| `untested` | Never seen — and Zinc will still attempt it. | `true` |
| `unsupported` | Zinc refuses; `unsupported_reason` says why. | `false` |

Four of the five tiers mean "go ahead". `untested` is not a refusal — it means no one has asked for that store yet.

<Tip>
  Don't branch on `support` yourself. `support_detail` spells out what the tier means and whether to proceed, and `how_to_order` gives the next step — both are written for this purpose and stay correct if a tier is added.
</Tip>

`support_detail` distinguishes cases the tier alone hides. An `observed` store that has completed an order before reads *"Real customer orders have succeeded at this store before, though none within the last 90 days"*, while one that never has says so plainly — most `observed` stores have never completed an order, and attempts also fail for ordinary reasons like the item being out of stock or over the price cap.

## `orderable` is about the store, not your request

<Warning>
  `orderable: true` does not promise a credential-less order. Where `checkout.guest_checkout` is `false`, the store still requires a linked account, and [`POST /orders`](/docs/v2/api-reference/orders/create-order) will refuse unless you pass `retailer_credentials_id`. Read both fields to predict a credential-less order.
</Warning>

| Field | Meaning |
| - | - |
| `checkout.guest_checkout` | Zinc can check out without a customer account — the store allows guests, or Zinc holds a shared account for it. |
| `checkout.use_your_account` | The customer can supply their own retailer login. |

`checkout` is `null` when Zinc has no catalog row for the domain (an `untested` store). That is an absence of information, not `false` — a null there would read as a refusal if you treated it as one.

## Checking a destination country

`country` takes an ISO 3166-1 alpha-2 code (`US`, `GB`), case-insensitive. Longer spellings such as `USA` are rejected, and the error names the code to use. Omit it — or send it blank — to skip the shipping check rather than invent a refusal.

This applies the same two gates in the same order as [`POST /orders`](/docs/v2/api-reference/orders/create-order), so a check and an order can never disagree about the same URL.

<Warning>
  `ships_to: null` means the store makes no claim either way — **not** that it is US-only. Auto-catalogued stores carry no country list precisely so the long tail stays orderable everywhere. Only a populated array is a statement about destinations.
</Warning>

## Refusals

When `orderable` is `false`, `unsupported_reason` carries the same error code [`POST /orders`](/docs/v2/api-reference/orders/create-order) would reject with — see [error handling](/docs/v2/api-reference/introduction/error-handling).

| `unsupported_reason` | Meaning |
| - | - |
| `retailer_not_supported` | The store is marked unsupported or retired. |
| `retailer_country_not_supported` | The store ships, but not to the country you asked about. The store itself is fine. |
| `invalid_product_url` | The URL has no registrable domain (an IP, `localhost`, a bare path). |

## Other fields

* `platform` is a hostname heuristic, not a fetch. A Shopify-hosted store is unambiguous from a `*.myshopify.com` domain; a custom domain running Shopify reports `null` rather than paying for a page load. Treat `null` as "not determined", not "not Shopify".
* `evidence` is deliberately coarse — whether Zinc has ever placed an order here, and the date of the last one. Success *rates* are not exposed. It is `null` for a store with no catalog row.
* `retailer.retailer` is the storefront slug (e.g. `amazon-de`); `retailer.brand` is the brand slug (e.g. `amazon`).

<ResponseExample>
  ```json 200 OK — ?url=amazon.com/dp/...&country=US theme={null}
  {
    "url": "https://www.amazon.com/dp/B08N5WRWNW",
    "domain": "amazon.com",
    "orderable": true,
    "support": "verified",
    "retailer": {
      "retailer": "amazon",
      "brand": "amazon",
      "display_name": "Amazon",
      "country": "US"
    },
    "platform": null,
    "checkout": {
      "guest_checkout": true,
      "use_your_account": true
    },
    "ships_to": ["US"],
    "evidence": {
      "orders_placed": true,
      "last_order_at": "2026-09-18"
    },
    "support_detail": "Zinc curates this retailer and places a test order here every day; the most recent one succeeded. Order normally.",
    "unsupported_reason": null,
    "how_to_order": "POST /orders with this URL in products[]; Zinc resolves the retailer from the URL."
  }
  ```

  ```json 200 OK — a store Zinc has never seen theme={null}
  {
    "url": "https://www.hodinkee.com/products/xyz",
    "domain": "hodinkee.com",
    "orderable": true,
    "support": "untested",
    "retailer": null,
    "platform": null,
    "checkout": null,
    "ships_to": null,
    "evidence": null,
    "support_detail": "Zinc has never ordered from this store, but that is not a refusal: go ahead and submit the order, and Zinc will attempt checkout exactly as it does for any other store. Most stores are untested only because no one has asked for them yet — Zinc's catalog lists the retailers it verifies, not the limit of what it can buy from.",
    "unsupported_reason": null,
    "how_to_order": "POST /orders with this URL in products[]; Zinc resolves the retailer from the URL."
  }
  ```

  ```json 200 OK — same store, &country=IT theme={null}
  {
    "url": "https://www.amazon.com/dp/B08N5WRWNW",
    "domain": "amazon.com",
    "orderable": false,
    "support": "unsupported",
    "retailer": {
      "retailer": "amazon",
      "brand": "amazon",
      "display_name": "Amazon",
      "country": "US"
    },
    "platform": null,
    "checkout": {
      "guest_checkout": true,
      "use_your_account": true
    },
    "ships_to": ["US"],
    "evidence": {
      "orders_placed": true,
      "last_order_at": "2026-09-18"
    },
    "support_detail": "Zinc can order from this store, but not to the country you asked about — it has declared the destinations in `ships_to` and yours is not among them. Re-check with a country it ships to, or ship there instead; the store itself is fine.",
    "unsupported_reason": "retailer_country_not_supported",
    "how_to_order": "Do not submit this order — `POST /orders` would reject it. See `unsupported_reason` and `support_detail`."
  }
  ```
</ResponseExample>


## OpenAPI

````yaml versions/latest.json GET /retailers/check
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, Amazon, Amazon CA,
    Amazon DE, Amazon FR, Amazon MX, Amazon UK, Barnes & Noble, Best Buy, Chewy,
    Gap, and 18 more. Ships to the US and 6 other countries (CA, DE, 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-09'
  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, Amazon, Amazon CA, Amazon DE, Amazon FR, Amazon
    MX, Amazon UK, Barnes & Noble, Best Buy, Chewy, Gap, and 18 more, shipping
    to the US and 6 other countries (CA, DE, 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
    - Amazon
    - Amazon CA
    - Amazon DE
    - Amazon FR
    - Amazon MX
    - Amazon UK
    - Barnes & Noble
    - Best Buy
    - Chewy
    - Gap
    - Grainger
    - IBS
    - Lowe's
    - Macys
    - McMaster-Carr
    - Partstown
    - Pokémon Center
    - Sephora
    - Target
    - The Home Depot
    - TikTok
    - Uniqlo
    - Walmart
    - Wayfair
    - Zinc
    - eBay
    - libraccio
    - zazzle
  x-supported-countries:
    - US
    - CA
    - DE
    - FR
    - GB
    - IT
    - MX
servers:
  - url: https://api.zinc.com
    description: Production
security:
  - BearerAuth: []
paths:
  /retailers/check:
    get:
      tags:
        - retailers
      summary: Check Retailer
      description: >-
        Can Zinc buy from this store, and ship it to this country?


        No authentication. This is the question `GET /retailers` cannot answer:
        the

        list is the curated set, while the order path accepts most stores, so a

        caller holding an arbitrary URL has no way to find out from the list
        alone.


        `orderable` is the answer. `support` says how much we know:


        | tier | meaning |

        |---|---|

        | `verified` | curated, and its daily test order is passing |

        | `active` | real orders succeeded here in the last 90 days |

        | `observed` | Zinc has attempted orders here |

        | `untested` | never seen — and Zinc will still attempt it |

        | `unsupported` | Zinc refuses; `unsupported_reason` says why |


        Read-only: asking never adds a store to the catalog.
      operationId: check_retailer_retailers_check_get
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            maxLength: 2048
            description: A product or store URL, e.g. https://shop.aloyoga.com/products/x
            title: Url
          description: A product or store URL, e.g. https://shop.aloyoga.com/products/x
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 64
              - type: 'null'
            description: >-
              Destination country as an ISO 3166-1 alpha-2 code (e.g. 'US',
              'GB'). Case-insensitive. Longer spellings such as 'USA' are
              rejected — the error names the code to use. Omit to skip the
              shipping check. Runs the same gate `POST /orders` applies, so the
              two cannot disagree.
            title: Country
          description: >-
            Destination country as an ISO 3166-1 alpha-2 code (e.g. 'US', 'GB').
            Case-insensitive. Longer spellings such as 'USA' are rejected — the
            error names the code to use. Omit to skip the shipping check. Runs
            the same gate `POST /orders` applies, so the two cannot disagree.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailerCheckResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
components:
  schemas:
    RetailerCheckResponse:
      properties:
        url:
          type: string
          title: Url
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Canonical registrable domain, or null if the URL has none.
        orderable:
          type: boolean
          title: Orderable
          description: >-
            Zinc will attempt an order here, given whatever the store requires.
            True for every support tier except `unsupported` — including
            `untested`, a store Zinc has never seen. It is a fact about the
            store, not about one request: where `checkout.guest_checkout` is
            false the store still needs a linked account, so pass
            `retailer_credentials_id` to POST /orders or it will refuse. Check
            both fields to predict a credential-less order.
        support:
          type: string
          title: Support
          description: >-
            verified: curated, daily test order passing. active: real orders
            succeeded in the last 90 days. observed: Zinc has attempted orders
            here. untested: never seen, and Zinc will still try. unsupported:
            Zinc refuses; see `unsupported_reason`.
        retailer:
          anyOf:
            - $ref: '#/components/schemas/RetailerCheckRetailer'
            - type: 'null'
          description: Null when Zinc has no catalog row for the domain.
        platform:
          anyOf:
            - type: string
            - type: 'null'
          title: Platform
          description: Detected storefront platform, e.g. 'shopify'.
        checkout:
          anyOf:
            - $ref: '#/components/schemas/RetailerCheckCheckout'
            - type: 'null'
        ships_to:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Ships To
          description: >-
            Declared destination countries. Null means no claim either way — the
            order path enforces nothing, so do not read it as 'US only'.
        evidence:
          anyOf:
            - $ref: '#/components/schemas/RetailerCheckEvidence'
            - type: 'null'
        support_detail:
          type: string
          title: Support Detail
          description: >-
            What `support` means for this store, in prose, and whether to go
            ahead. Every orderable tier says so explicitly — `untested` in
            particular means 'never seen it, try anyway', which the tier name
            alone does not convey.
        unsupported_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Unsupported Reason
          description: Error code Zinc would refuse with, matching POST /orders.
        how_to_order:
          type: string
          title: How To Order
          description: >-
            What to do next. Carries the ordering instruction when `orderable`
            is true, and tells you not to submit when it is false.
      type: object
      required:
        - url
        - orderable
        - support
        - support_detail
        - how_to_order
      title: RetailerCheckResponse
      description: Can Zinc buy from this store, and ship it where the caller wants?
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RetailerCheckRetailer:
      properties:
        retailer:
          type: string
          title: Retailer
          description: Storefront slug, e.g. 'amazon-de'
        brand:
          type: string
          title: Brand
          description: Brand slug, e.g. 'amazon'
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: The market this storefront is, or null when unscoped.
      type: object
      required:
        - retailer
        - brand
      title: RetailerCheckRetailer
      description: The storefront a checked URL resolves to, when we have one.
    RetailerCheckCheckout:
      properties:
        guest_checkout:
          type: boolean
          title: Guest Checkout
          description: >-
            Zinc can check out without a customer account — the store allows
            guests, or Zinc holds a shared account for it. When false, an order
            here must carry `retailer_credentials_id`.
        use_your_account:
          type: boolean
          title: Use Your Account
          description: The customer can supply their own retailer login.
      type: object
      required:
        - guest_checkout
        - use_your_account
      title: RetailerCheckCheckout
      description: How a customer can pay at this store.
    RetailerCheckEvidence:
      properties:
        orders_placed:
          type: boolean
          title: Orders Placed
        last_order_at:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Last Order At
      type: object
      required:
        - orders_placed
      title: RetailerCheckEvidence
      description: |-
        What Zinc has actually done at this store.

        Deliberately coarse — a boolean and a date. Success *rates* are a
        competitive signal.
    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.