---
title: "List Merchants"
method: GET
path: "/tax/merchants"
---

# List Merchants

`GET /tax/merchants`

Retrieve a paginated list of all merchants for your account.

## Query parameters

- `limit` integer
- `cursor` string

## Headers

- `X-API-Version` '2026-01-01', required

## Response `200`

List of merchants

- MerchantListResponse
  - `merchants` MerchantResponse[]
    - `id` string — The internal merchant ID
    - `object` string
    - `reference_merchant_id` string — Your external ID for this merchant
    - `name` string
    - `email` string
    - `default_address` MerchantAddress — Merchant's default business address. Uses address_ prefix for field names.
      - `address_line_1` string, required
      - `address_line_2` string
      - `address_city` string, required
      - `address_province` string, required — State/province code (2-letter ISO 3166-2)
      - `address_postal_code` string, required
      - `address_country` string, required — Country code (2-letter ISO 3166-1)
    - `tax_ids` TaxId[]
      - `type` string, required — Country-specific Stripe-style tax ID type (e.g., `us_ein`, `eu_vat`, `gb_vat`, `au_abn`, `ca_gst_hst`). See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
      - `value` string, required — The tax ID value (1-100 characters).
    - `status` 'active' | 'deleted'
    - `testmode` boolean — Whether this merchant was created in test mode
    - `created_at` number — Unix timestamp of creation
    - `updated_at` number — Unix timestamp of last update
    - `metadata` Metadata — You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).
      - `example_key` string — Storing things like an order number may be useful for reporting and reconciliation.
  - `has_more` boolean — Whether there are more merchants to fetch
  - `last_merchant_id` string — Use as cursor for next page

## Other responses

- `400` — Unexpected error

---

[API](https://skmtc.net/numeral-com/apis/numeral-api.md) · [All operations](https://skmtc.net/numeral-com/apis/numeral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral-com/numeral-api/revisions/f0af51c3f9b9/schema)