Merchants
Merchants represent sellers on your platform. They are used in platform calculations to provide seller context for tax calculations.
Merchants are available starting with API version 2026-01-01. You must include the X-API-Version: 2026-01-01 header to use merchant endpoints.
The Merchant Object
{
"id": "merch_1765503753979c37c5f24",
"object": "tax.merchant",
"reference_merchant_id": "my-seller-123",
"name": "Acme Seller Co",
"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": [
{ "type": "us-ein", "value": "12-3456789" }
],
"status": "active",
"testmode": true,
"created_at": 1735689600,
"updated_at": 1735689600
}
Attributes
| Attribute | Type | Description |
|---|
id | string | Unique identifier for the merchant (e.g., merch_xxx). |
object | string | Always tax.merchant. |
reference_merchant_id | string | Your external ID for this merchant. Must be unique per client and testmode. |
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 identification numbers. |
status | string | Either active or deleted. |
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 | Arbitrary key-value pairs. |
Merchant vs Customer
It’s important to understand the difference between merchants and customers:
| Merchant | Customer |
|---|
| Role | Seller on your platform | Buyer of goods/services |
| Created by | Platform (you) | Platform (you) |
| Used in | Platform calculations | All calculations |
| Tax treatment | Origin address for tax sourcing | Destination address for tax calculation |
| Tax exemption | N/A | Can be marked as tax exempt |
Using reference_merchant_id
You can use your own ID system by providing a reference_merchant_id when creating a merchant. This allows you to:
- Create merchants with your ID:
POST /tax/merchants with reference_merchant_id
- Retrieve by your ID:
GET /tax/merchants/my-seller-123
- Update by your ID:
POST /tax/merchants/my-seller-123
- Delete by your ID:
DELETE /tax/merchants/my-seller-123
- Calculate using your ID:
{ "merchant": { "merchant_id": "my-seller-123" } }
reference_merchant_id must be unique per client and testmode combination. You cannot change it after creation.
Testmode Isolation
Merchants created with a test API key are completely isolated from merchants created with a live API key:
- Test merchants are only visible with test API keys
- Live merchants are only visible with live API keys
- A
merchant_not_found error is returned when trying to access a merchant from the wrong mode
Default Address
The merchant’s default_address is used as the origin address in platform calculations when determining tax sourcing rules. Some jurisdictions (like origin-based states in the US) use the seller’s location to determine tax rates.
Tax IDs
Store merchant tax IDs for B2B scenarios:
{
"tax_ids": [
{ "type": "us-ein", "value": "12-3456789" },
{ "type": "fr-vat", "value": "FR123456789" }
]
}
us-ein - US Employer Identification Numberfr-vat - France VAT numberde-vat - Germany VAT numbergb-vat - UK VAT number
Soft Delete
When you delete a merchant, it’s soft-deleted (the discarded_at timestamp is set):
- The merchant no longer appears in
GET or LIST operations
- The merchant cannot be used in new platform calculations
- Historical data is preserved for reporting
