Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.numeral.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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": "seller@example.com",
  "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

AttributeTypeDescription
idstringUnique identifier for the merchant (e.g., merch_xxx).
objectstringAlways tax.merchant.
reference_merchant_idstringYour external ID for this merchant. Must be unique per client and testmode.
namestringThe merchant’s business name.
emailstringThe merchant’s email address.
default_addressobjectThe merchant’s default business address.
tax_idsarrayArray of tax identification numbers.
statusstringEither active or deleted.
testmodebooleanWhether this merchant was created in test mode.
created_atnumberUnix timestamp of creation.
updated_atnumberUnix timestamp of last update.
metadataobjectArbitrary key-value pairs.

​
Merchant vs Customer

It’s important to understand the difference between merchants and customers:
MerchantCustomer
RoleSeller on your platformBuyer of goods/services
Created byPlatform (you)Platform (you)
Used inPlatform calculationsAll calculations
Tax treatmentOrigin address for tax sourcingDestination address for tax calculation
Tax exemptionN/ACan 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