---
title: "Batch merchant search"
method: POST
path: "/v1/merchants/search"
tags: ["Merchants"]
---

# Batch merchant search

`POST /v1/merchants/search`

Search for merchants by name (fuzzy) or domain (exact match). Up to 20 queries per request. Each query carries its own `query_id` that is echoed back so callers can correlate responses. Each result contains an `items` array with matched merchants. Name queries return up to `limit` items per result (default 5, max 20). Misses return a single item with `id: null` — there are no 404s.

## Request body

- MerchantSearchRequest
  - `queries` MerchantSearchQuery[], required — Batch of search queries (1–50). Each query returns a result with an `items` array. Name queries with `limit > 1` may yield multiple items. Misses return an `items` array with a single entry where `id` is null.
    - `query_id` string, required — Caller-supplied opaque identifier correlated back in results
    - `type` 'name' | 'domain', required — "name" triggers fuzzy search; "domain" is an exact-match lookup
    - `value` string, required — Search term: merchant name fragment or bare domain
    - `region` string — Optional ISO 3166-1 alpha-2 region filter (name queries only)
    - `limit` integer — Maximum number of results to return for this query (name queries only, domain queries always return at most one result). Defaults to 5.

## Response `200`

Per-query results. Each result has an `items` array. A name query with limit > 1 may produce multiple items. Misses have id: null.

- MerchantSearchResponse
  - `results` MerchantSearchResult[], required
    - `query_id` string, required
    - `items` MerchantSearchItem[], required — Matched merchants for this query. Always contains at least one entry. Misses return a single entry with `id: null`; name queries with `limit > 1` may return multiple entries.
      - `id` string, nullable, required — Checkmate merchant ID, or null when not found
      - `name` string, nullable, required — Merchant display name, or null when no match
      - `domains` string[], required — Merchant domains
      - `estimated_shipping` EstimatedShipping, nullable, required — Estimated shipping time statistics, or null when unknown
        - `unit` 'days', required — Unit for all shipping time values in this object
        - `median` number, required — Median days to deliver
        - `q1` number, nullable, required — First quartile (25th percentile) days to deliver, or null when unknown
        - `q3` number, nullable, required — Third quartile (75th percentile) days to deliver, or null when unknown

## Other responses

- `400` — Invalid request body or query cap exceeded (max 50 queries)
- `401` — Missing or invalid API key
- `429` — Too many requests. Rate limits are determined on a per partner basis.

---

[API](https://skmtc.dev/openstock/apis/openstock-api.md) · [All operations](https://skmtc.dev/openstock/apis/openstock-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openstock/openstock-api/revisions/26bc3de53c39/schema)