Skip to main content
POST
/
tax
/
merchants
curl -X POST https://api.numeralhq.com/tax/merchants \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

{
  "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
}

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.

Creates a new merchant for platform/marketplace calculations. Merchants represent sellers on your platform.

​
Headers

​
Authorization
string
required
Bearer token authentication. Example: Bearer sk_test_xxx
​
X-API-Version
string
required
Must be 2026-03-01 for merchant endpoints.

​
Request Body

​
reference_merchant_id
string
Your external ID for this merchant. Must be unique per client and testmode. You can use this ID to look up merchants later.
​
name
string
The merchant’s business name.
​
email
string
The merchant’s email address.
​
default_address
object
The merchant’s default business address. Used as the origin address in platform calculations if not overridden.
​
tax_ids
array
Array of tax identification numbers for this merchant.
​
metadata
object
Arbitrary key-value pairs for storing additional information (max 50 keys).

​
Response

​
id
string
The internal merchant ID (e.g., merch_1765503753979c37c5f24).
​
object
string
Always tax.merchant.
​
reference_merchant_id
string
Your external ID for this merchant.
​
name
string
The merchant’s business name.
​
email
string
The merchant’s email address.
​
default_address
object
The merchant’s default business address.
​
tax_ids
array
Array of tax IDs.
​
status
string
Either active or deleted.
​
testmode
boolean
Whether this merchant was created in test mode.
​
created_at
number
Unix timestamp of creation.
curl -X POST https://api.numeralhq.com/tax/merchants \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

{
  "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
}

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

API version. Must be 2026-01-01 for merchant endpoints.

Available options:
2026-01-01

Body

application/json

Request body for creating a merchant

​
reference_merchant_id
string

Your external ID for this merchant. Must be unique per client+testmode.

Example:

"my-seller-123"

​
name
string

The merchant's business name

Example:

"Acme Seller Co"

​
email
string

The merchant's email address

Example:

"seller@example.com"

​
default_address
object

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

​
tax_ids
object[]

Tax identification numbers for this merchant

​
metadata
object

You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.

Response

Merchant created successfully

​
id
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"

​
email
string
Example:

"seller@example.com"

​
default_address
object

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

​
tax_ids
object[]
​
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. Any valid JSON object whose values are less than 255 characters long is accepted.