Merchants

Understanding the Merchant object in Numeral API

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": "[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": [
    { "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:

1. Create merchants with your ID: POST /tax/merchants with reference_merchant_id
2. Retrieve by your ID: GET /tax/merchants/my-seller-123
3. Update by your ID: POST /tax/merchants/my-seller-123
4. Delete by your ID: DELETE /tax/merchants/my-seller-123
5. 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" }
  ]
}

Common tax ID types:

• us-ein - US Employer Identification Number
• fr-vat - France VAT number
• de-vat - Germany VAT number
• gb-vat - UK VAT number

For a full list of supported tax ID types, see the Tax IDs reference.

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

Related Endpoints

• Create Merchant
• Get Merchant
• List Merchants
• Update Merchant
• Delete Merchant
• Platform Calculations