Get Merchant

curl https://api.numeralhq.com/tax/merchants/merch_1765503753979c37c5f24 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01"

curl https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01"

{
  "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,
  "updated_at": 1735689600
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

GET

tax

merchants

{merchant_id}

curl https://api.numeralhq.com/tax/merchants/merch_1765503753979c37c5f24 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01"

curl https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01"

{
  "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,
  "updated_at": 1735689600
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

Retrieve a merchant by internal ID (merch_xxx) or your external reference_merchant_id.

Headers

string

required

Bearer token authentication.

string

required

Must be 2026-01-01.

Path Parameters

string

required

The merchant ID (e.g., merch_1765503753979c37c5f24) or your reference_merchant_id (e.g., my-seller-123).

Response

string

The internal merchant ID.

string

Always tax.merchant.

string

Your external ID for this merchant.

string

The merchant’s business name.

string

The merchant’s email address.

object

The merchant’s default business address.

array

Array of tax IDs.

string

Either active or deleted.

boolean

Whether this merchant was created in test mode.

number

Unix timestamp of creation.

number

Unix timestamp of last update.

curl https://api.numeralhq.com/tax/merchants/merch_1765503753979c37c5f24 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01"

curl https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01"

{
  "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,
  "updated_at": 1735689600
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

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

Path Parameters

merchant_id

string

required

The merchant ID (merch_xxx) or your reference_merchant_id

Response

Merchant details

string

The internal merchant ID

Example:

"merch_1765503753979c37c5f24"

object

string

Example:

"tax.merchant"

reference_merchant_id

string

Your external ID for this merchant

Example:

"my-seller-123"

name

string

Example:

"Acme Seller Co"

string

Example:

"seller@example.com"

default_address

object

Merchant's default business address. Uses address_ prefix for field names.

Show child attributes

tax_ids

object[]

Show child attributes

status

enum<string>

Available options:

active,

deleted

Example:

"active"

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

object

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).

Show child attributes

Getting Started

API Reference

Headers

Path Parameters

Response

Authorizations

Headers

Path Parameters

Response