---
title: "Filter-based merchant search (NOT ranked; deterministic order)"
method: GET
path: "/v1/merchants"
---

# Filter-based merchant search (NOT ranked; deterministic order)

`GET /v1/merchants`

## Request

- Base URL: `https://mercantry.org`
- URL: `https://mercantry.org/v1/merchants`
- Auth: none declared

Order: merchant_id ASC by default; distance ASC (ties by merchant_id) when lat/lng given with order_by=distance. The registry never ranks (REQ-DATA-2).

## Query parameters

- `neighborhood` string
- `lat` number
- `lng` number
- `radius_km` number
- `cuisine_tags` string
- `attribute_tags` string
- `price_band_min` integer
- `price_band_max` integer
- `open_at` string
- `bookable_only` boolean
- `party_size` integer
- `sandbox` boolean
- `order_by` 'merchant_id' | 'distance'
- `limit` integer
- `offset` integer

## Response `200`

Deterministically ordered page of compact merchant records.

- object
  - `order` 'merchant_id' | 'distance'
  - `total` integer
  - `results` MerchantSummary[]
    - `merchant_id` string, uuid
    - `name` string
    - `cuisine_tags` string[]
    - `attribute_tags` string[]
    - `neighborhood` string
    - `address` string
    - `lat` number
    - `lng` number
    - `price_band` integer
    - `reservation_policy` 'walk_in_only' | 'phone_reservations' | 'accepts_reservations' | 'requires_deposit'
    - `bookable` boolean: Derived: phone-verified AND accepts phone reservations AND not opted out AND no deposit required.
    - `verification_status` 'unverified' | 'phone_verified' | 'transaction_verified'
    - `sandbox` boolean: Sandbox test merchant: books end-to-end and returns a SIMULATED confirmation, never dialing a real venue. Never present a sandbox confirmation to a user as a real reservation.
    - `distance_km` number: Present only when a geo filter was supplied.

## Other responses

- `400`: invalid_open_at — unparseable open_at value.
- `429`: rate_limited — wait Retry-After seconds (also in retry_after_s), then resume.

---

[API](https://skmtc.dev/mercantry/apis/registry-agent-native-merchant-registry-rest-mirror.md) · [All operations](https://skmtc.dev/mercantry/apis/registry-agent-native-merchant-registry-rest-mirror/llms.txt) · [OpenAPI document](https://skmtc.dev/mercantry/apis/registry-agent-native-merchant-registry-rest-mirror/revisions/0a9bf614fe96?raw)