Merchants

A merchant is a seller on your platform. Create one per seller, then pass it on a platform calculation to give the calculation the seller’s context. Its default_address is the origin address for tax sourcing. Merchants are available from API version 2026-01-01. Send X-API-Version on every request.

Where merchants fit

Platform sale
├─ POST /tax/merchants               → merchant id   (once per seller)
└─ POST /tax/platform/calculations
      send: merchant.merchant_id + products + customer

	Merchant	Customer
Role	Seller on your platform	Buyer of goods or services
Created by	You (the platform)	You (the platform)
Used in	Platform calculations	All calculations
Address	Origin address for tax sourcing	Destination address for the tax
Tax exemption	Not applicable	Can be marked tax exempt

Endpoints

Create a merchantPOST/tax/merchants Update a merchantPOST/tax/merchants/:id Retrieve a merchantGET/tax/merchants/:id List all merchantsGET/tax/merchants Delete a merchantDELETE/tax/merchants/:id

The Merchant object

Attributes

string

The ID of the merchant, merch_….

string, value is "tax.merchant"

String representing the object’s type.

string

Your ID for this merchant. Unique among your merchants in the same mode (test or live). Can’t be changed after creation. See Your own merchant IDs.

string

The merchant’s business name.

string

The merchant’s email address.

object

The merchant’s business address. Used as the origin address in platform calculations unless the calculation overrides it. Some jurisdictions, like origin-based US states, use the seller’s location to set the rate.

string

Optional second address line.

string

ISO 3166-2 subdivision code.

string

ISO 3166-1 alpha-2 country code.

array of objects

The merchant’s tax IDs, for B2B scenarios. They identify the selling entity for documentation and reporting. A platform calculation can override them with merchant.tax_ids.

string

Tax ID type, e.g. us_ein, eu_vat, gb_vat, fr_vat, or de_vat. See tax IDs for every type.

string

The tax ID, 1–100 characters.

enum

active or deleted.

boolean

true if made with a test API key. Test and live merchants are separate: each is only visible with keys from its own mode.

timestamp

Unix seconds when the merchant was created. updated_at follows the same pattern.

object

Key-value pairs from the request.

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
}

Your own merchant IDs

Send a reference_merchant_id when you create a merchant, and you can use it anywhere the merchant’s id works:

Retrieve, update, and delete it: /tax/merchants/my-seller-123.
Calculate with it: "merchant": { "merchant_id": "my-seller-123" }.

reference_merchant_id must be unique among your merchants in the same mode (test or live). You can’t change it after creation.

Merchants made with a test API key are only visible with test keys, and live merchants only with live keys. Using a merchant from the other mode returns MERCHANT_NOT_FOUND.

Using your own ID

POST   /tax/merchants                 { "reference_merchant_id": "my-seller-123", ... }
GET    /tax/merchants/my-seller-123
POST   /tax/merchants/my-seller-123
DELETE /tax/merchants/my-seller-123
POST   /tax/platform/calculations     { "merchant": { "merchant_id": "my-seller-123" }, ... }

Create a merchant

Creates a merchant. Every field is optional. Try it in the API reference.

Parameters

string

Your ID for this merchant. Must be unique among your merchants in the same mode (test or live).

string

The merchant’s business name.

string

The merchant’s email address.

object

The merchant’s business address, used as the origin address in platform calculations.

string

required

string

required

string

required

ISO 3166-2 subdivision code.

string

required

string

required

ISO 3166-1 alpha-2 country code.

array of objects

The merchant’s tax IDs.

string

required

Tax ID type, e.g. us_ein or eu_vat. See tax IDs.

string

required

The tax ID, 1–100 characters.

object

String key-value pairs. At most 50 keys. Keys and values up to 255 characters.

Returns

A Merchant object.

POST /tax/merchants

curl https://api.numeralhq.com/tax/merchants \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-03-01' \
  -d '{
    "reference_merchant_id": "my-seller-123",
    "name": "Test Seller",
    "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"
    }
  }'

Response

{
  "id": "merch_1765503753979c37c5f24",
  "object": "tax.merchant",
  "reference_merchant_id": "my-seller-123",
  "name": "Test Seller",
  "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": [],
  "status": "active",
  "testmode": true,
  "created_at": 1735689600
}

Update a merchant

Updates a merchant. Send only the fields you want to change. Try it in the API reference.You can’t change reference_merchant_id.

Parameters

string

required

The merchant’s id or your reference_merchant_id.

string

The merchant’s business name.

string

The merchant’s email address.

object

The merchant’s business address. If you send it, send every required address field. Same fields as on create.

array of objects

Replaces all of the merchant’s existing tax IDs. Same fields as on create.

object

String key-value pairs.

Returns

The updated Merchant object.

POST /tax/merchants/:id

curl https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-03-01' \
  -d '{
    "name": "Updated Seller Name",
    "email": "new-email@example.com"
  }'

Response

{
  "id": "merch_1765503753979c37c5f24",
  "object": "tax.merchant",
  "reference_merchant_id": "my-seller-123",
  "name": "Updated Seller Name",
  "email": "new-email@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": [],
  "status": "active",
  "testmode": true,
  "created_at": 1735689600,
  "updated_at": 1735690000
}

Retrieve a merchant

Returns a merchant by its id or your reference_merchant_id. Try it in the API reference.

string

required

The merchant’s id (e.g. merch_1765503753979c37c5f24) or your reference_merchant_id (e.g. my-seller-123).

Returns

A Merchant object.

GET /tax/merchants/:id

curl https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-03-01'

List all merchants

Returns your merchants, one page at a time. Deleted merchants aren’t included. Try it in the API reference.

integer

default:"10"

Maximum number of merchants to return. Up to 100.

string

The last_merchant_id from the previous page.

Returns

An object with a merchants array of Merchant objects, has_more (whether there are more to fetch), and last_merchant_id (the cursor for the next page).

GET /tax/merchants

curl 'https://api.numeralhq.com/tax/merchants?limit=10' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-03-01'

Response

{
  "merchants": [
    {
      "id": "merch_1765503753979c37c5f24",
      "object": "tax.merchant",
      "reference_merchant_id": "my-seller-123",
      "...": "see The Merchant object"
    },
    {
      "id": "merch_9876543210abcdef",
      "object": "tax.merchant",
      "reference_merchant_id": "eu-seller-456",
      "...": "see The Merchant object"
    }
  ],
  "has_more": true,
  "last_merchant_id": "merch_9876543210abcdef"
}

Delete a merchant

Deletes a merchant. It’s a soft delete. Try it in the API reference.

The merchant no longer appears in retrieve or list calls.
It can’t be used in new platform calculations. Its ID returns MERCHANT_NOT_FOUND.
Historical data is kept for reporting.

string

required

The merchant’s id or your reference_merchant_id.

Returns

The merchant’s id, object, deleted (always true), and deleted_at (Unix seconds).

DELETE /tax/merchants/:id

curl -X DELETE https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-03-01'

Response

{
  "id": "merch_1765503753979c37c5f24",
  "object": "tax.merchant",
  "deleted": true,
  "deleted_at": 1735690500
}

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.

HTTP	`type`	When
400	`MISSING_FIELD`	A required field is missing, e.g. a required `default_address` field.
400	`INCORRECT_TYPE`	A field has the wrong type.
400	`DUPLICATE_MERCHANT`	A merchant with this `reference_merchant_id` already exists.
404	`MERCHANT_NOT_FOUND`	The merchant doesn’t exist, was deleted, or belongs to the other mode (test or live).

404

{
  "code": 404,
  "type": "MERCHANT_NOT_FOUND",
  "message": "Merchant not found or belongs to different testmode"
}

Getting Started

API Reference

The Merchant object

Attributes

Your own merchant IDs

Create a merchant

Parameters

Returns

Update a merchant

Parameters

Returns

Retrieve a merchant

Returns

List all merchants

Returns

Delete a merchant

Returns

Errors