Creates a new merchant for platform/marketplace calculations. Merchants represent sellers on your platform.
Bearer token authentication. Example: Bearer sk_test_xxx
Must be 2026-01-01 for merchant endpoints.
Request Body
Your external ID for this merchant. Must be unique per client and testmode. You can use this ID to look up merchants later.
The merchant’s business name.
The merchant’s email address.
The merchant’s default business address. Used as the origin address in platform calculations if not overridden.
Street address line 2 (optional).
State/province code (2-letter ISO 3166-2).
Country code (2-letter ISO 3166-1).
Array of tax identification numbers for this merchant.
The type of tax ID (e.g., us-ein, fr-vat, de-vat, gb-vat).
Arbitrary key-value pairs for storing additional information (max 50 keys).
Response
The internal merchant ID (e.g., merch_1765503753979c37c5f24).
Your external ID for this merchant.
The merchant’s business name.
The merchant’s email address.
The merchant’s default business address.
Either active or deleted.
Whether this merchant was created in test mode.
Unix timestamp of creation.
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": "[email protected]",
"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": "[email protected]",
"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
}
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
API version. Must be 2026-01-01 for merchant endpoints.
Available options:
2026-01-01
Request body for creating a merchant
Your external ID for this merchant. Must be unique per client+testmode.
The merchant's business name
The merchant's email address
Merchant's default business address. Uses address_ prefix for field names.
Tax identification numbers for this merchant
You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
Merchant created successfully
Example:"merch_1765503753979c37c5f24"
Your external ID for this merchant
Merchant's default business address. Uses address_ prefix for field names.
Available options:
active,
deleted
Whether this merchant was created in test mode
Unix timestamp of creation
Unix timestamp of last update
You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
