Create Merchant

Create a new merchant for platform/marketplace calculations

POST /tax/merchants

cURL

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": "[e-mail]",
    "default_address": {
      "address_line_1": "123 Main St",
      "address_city": "San Francisco",
      "address_province": "CA",
      "address_postal_code": "94105",
      "address_country": "US"
    }
  }'

const response = await fetch('https://api.numeralhq.com/tax/merchants', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'X-API-Version': '2026-03-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
    }
  })
});

import requests

response = requests.post(
    'https://api.numeralhq.com/tax/merchants',
    headers={
        'Authorization': 'Bearer sk_test_xxx',
        'X-API-Version': '2026-03-01',
        'Content-Type': 'application/json'
    },
    json={
        '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'
        }
    }
)

200 - Success

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

{
  "error": {
    "error_code": "duplicate_reference_id",
    "error_message": "A merchant with this reference_merchant_id already exists"
  }
}

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.

Show Address Properties

address_line_1 · string · required

Street address line 1.

address_line_2 · string

Street address line 2 (optional).

address_city · string · required

City name.

address_province · string · required

State/province code (2-letter ISO 3166-2).

address_postal_code · string · required

Postal/ZIP code.

address_country · string · required

Country code (2-letter ISO 3166-1).

tax_ids · array

Array of tax identification numbers for this merchant.

Show Tax ID Object

type · string · required

The type of tax ID. See Tax IDs for the full list of supported types.

value · string · required

The tax ID value.

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

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": "[e-mail]",
    "default_address": {
      "address_line_1": "123 Main St",
      "address_city": "San Francisco",
      "address_province": "CA",
      "address_postal_code": "94105",
      "address_country": "US"
    }
  }'

const response = await fetch('https://api.numeralhq.com/tax/merchants', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'X-API-Version': '2026-03-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
    }
  })
});

import requests

response = requests.post(
    'https://api.numeralhq.com/tax/merchants',
    headers={
        'Authorization': 'Bearer sk_test_xxx',
        'X-API-Version': '2026-03-01',
        'Content-Type': 'application/json'
    },
    json={
        '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'
        }
    }
)

200 - Success

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

{
  "error": {
    "error_code": "duplicate_reference_id",
    "error_message": "A merchant with this reference_merchant_id already exists"
  }
}

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:

"[e-mail]"

default_address · object

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

Show child attributes

tax_ids · object[]

Tax identification numbers for this merchant

Show child attributes

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

Response

200

application/json

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:

"[e-mail]"

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