> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Merchants
> Retrieve a paginated list of all merchants
Retrieve a paginated list of all merchants for your account. Deleted merchants are not included.
## Headers
Bearer token authentication.
Must be `2026-03-01`.
## Query Parameters
Maximum number of merchants to return. Maximum value is 100.
Pagination cursor from a previous response. Use the `last_merchant_id` from the previous response.
## Response
Array of merchant objects.
Whether there are more merchants to fetch.
The ID of the last merchant in this response. Use as `cursor` for the next page.
```bash cURL theme={null}
curl "https://api.numeralhq.com/tax/merchants?limit=10" \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2026-03-01"
```
```bash cURL (with pagination) theme={null}
curl "https://api.numeralhq.com/tax/merchants?limit=10&cursor=merch_abc123" \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2026-03-01"
```
```json 200 - Success theme={null}
{
"merchants": [
{
"id": "merch_1765503753979c37c5f24",
"object": "tax.merchant",
"reference_merchant_id": "my-seller-123",
"name": "Test Seller",
"email": "seller@example.com",
"default_address": {
"address_line_1": "123 Main St",
"address_city": "San Francisco",
"address_province": "CA",
"address_postal_code": "94105",
"address_country": "US"
},
"tax_ids": [],
"status": "active",
"testmode": true,
"created_at": 1735689600
},
{
"id": "merch_9876543210abcdef",
"object": "tax.merchant",
"reference_merchant_id": "eu-seller-456",
"name": "European Seller",
"email": "eu@example.com",
"default_address": {
"address_line_1": "10 Rue de Commerce",
"address_city": "Paris",
"address_province": "75",
"address_postal_code": "75001",
"address_country": "FR"
},
"tax_ids": [
{ "type": "fr_vat", "value": "FR123456789" }
],
"status": "active",
"testmode": true,
"created_at": 1735689700
}
],
"has_more": true,
"last_merchant_id": "merch_9876543210abcdef"
}
```
## OpenAPI
````yaml GET /tax/merchants
openapi: 3.0.1
info:
title: Numeral API
description: >-
API for sales tax calculations - Version 2026-01-01. This version introduces
Merchant management and Platform Calculations for marketplace and payment
processor scenarios.
license:
name: MIT
version: '2026-01-01'
servers:
- url: https://api.numeralhq.com/
security:
- bearerAuth: []
paths:
/tax/merchants:
get:
summary: List Merchants
description: Retrieve a paginated list of all merchants for your account.
operationId: listMerchants_v20260101
parameters:
- name: X-API-Version
in: header
required: true
schema:
type: string
enum:
- '2026-01-01'
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
default: 10
description: Maximum number of merchants to return (max 100)
- name: cursor
in: query
required: false
schema:
type: string
description: Pagination cursor from previous response
responses:
'200':
description: List of merchants
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantListResponse'
'400':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
MerchantListResponse:
type: object
properties:
merchants:
type: array
items:
$ref: '#/components/schemas/MerchantResponse'
has_more:
type: boolean
description: Whether there are more merchants to fetch
last_merchant_id:
type: string
description: Use as cursor for next page
Error:
type: object
description: Standard error response format for API version 2026-01-01
properties:
code:
type: integer
description: HTTP status code
example: 400
type:
type: string
description: Machine-readable error type
example: MISSING_FIELD
message:
type: string
description: Human-readable error message
example: Required field 'address_country' is missing
required:
- code
- type
- message
MerchantResponse:
type: object
properties:
id:
type: string
description: The internal merchant ID
example: merch_1765503753979c37c5f24
object:
type: string
example: tax.merchant
reference_merchant_id:
type: string
description: Your external ID for this merchant
example: my-seller-123
name:
type: string
example: Acme Seller Co
email:
type: string
example: seller@example.com
default_address:
$ref: '#/components/schemas/MerchantAddress'
tax_ids:
type: array
items:
$ref: '#/components/schemas/TaxId'
status:
type: string
enum:
- active
- deleted
example: active
testmode:
type: boolean
description: Whether this merchant was created in test mode
created_at:
type: number
description: Unix timestamp of creation
updated_at:
type: number
description: Unix timestamp of last update
metadata:
$ref: '#/components/schemas/Metadata'
MerchantAddress:
type: object
description: >-
Merchant's default business address. Uses address_ prefix for field
names.
properties:
address_line_1:
type: string
example: 123 Main St
address_line_2:
type: string
example: Suite 100
address_city:
type: string
example: San Francisco
address_province:
type: string
description: State/province code (2-letter ISO 3166-2)
example: CA
address_postal_code:
type: string
example: '94105'
address_country:
type: string
description: Country code (2-letter ISO 3166-1)
example: US
required:
- address_line_1
- address_city
- address_province
- address_postal_code
- address_country
TaxId:
type: object
properties:
type:
type: string
description: >-
Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the
full list of supported types.
example: us_ein
value:
type: string
description: The tax ID value
example: 12-3456789
required:
- type
- value
Metadata:
type: object
description: >-
You can store arbitrary keys and values in the metadata. Any valid JSON
object whose values are less than 255 characters long is accepted.
properties:
example_key:
type: string
description: >-
Storing things like an order number may be useful for reporting and
reconciliation.
example: example_value
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````