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-01-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"
    }
  }'

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
}

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-01-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 (e.g., us-ein, fr-vat, de-vat, gb-vat).

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-01-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"
    }
  }'

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
}

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

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

Show child attributes