List Merchants

Retrieve a paginated list of all merchants

GET /tax/merchants

cURL

curl "https://api.numeralhq.com/tax/merchants?limit=10" \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01"

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"

200 - Success

{
  "merchants": [
    {
      "id": "merch_1765503753979c37c5f24",
      "object": "tax.merchant",
      "reference_merchant_id": "my-seller-123",
      "name": "Test Seller",
      "email": "[e-mail]",
      "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": "[e-mail]",
      "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"
}

Retrieve a paginated list of all merchants for your account. Deleted merchants are not included.

Headers

Authorization · string · required

Bearer token authentication.

X-API-Version · string · required

Must be 2026-03-01.

Query Parameters

limit · integer · default: "10"

Maximum number of merchants to return. Maximum value is 100.

cursor · string

Pagination cursor from a previous response. Use the last_merchant_id from the previous response.

Response

merchants · array

Array of merchant objects.

has_more · boolean

Whether there are more merchants to fetch.

last_merchant_id · string

The ID of the last merchant in this response. Use as cursor for the next page.

cURL

curl "https://api.numeralhq.com/tax/merchants?limit=10" \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01"

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"

200 - Success

{
  "merchants": [
    {
      "id": "merch_1765503753979c37c5f24",
      "object": "tax.merchant",
      "reference_merchant_id": "my-seller-123",
      "name": "Test Seller",
      "email": "[e-mail]",
      "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": "[e-mail]",
      "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"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version · enum<string> · required

Available options: 2026-01-01

Query Parameters

limit · integer · default: 10

Maximum number of merchants to return (max 100)

Required range: x <= 100

cursor · string

Pagination cursor from previous response

Response

200

application/json

List of merchants

merchants · object[]

Show child attributes

has_more · boolean

Whether there are more merchants to fetch

last_merchant_id · string

Use as cursor for next page