> ## 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

> Store the sellers on your platform

A merchant is a seller on your platform. Create one per seller, then pass it on a [platform calculation](https://docs.numeral.com/v2026-11-01/objects/platform.md) 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.

```text Where merchants fit theme={null}
Platform sale
├─ POST /tax/merchants               → merchant id   (once per seller)
└─ POST /tax/platform/calculations
      send: merchant.merchant_id + products + customer
```

| | Merchant | [Customer](https://docs.numeral.com/v2026-11-01/objects/customers.md) |
| - | - | - |
| Role | Seller on your platform | Buyer of goods or services |
| 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](#create-a-merchant)
[Update a merchantPOST/tax/merchants/:id](#update-a-merchant)
[Retrieve a merchantGET/tax/merchants/:id](#retrieve-a-merchant)
[List all merchantsGET/tax/merchants](#list-all-merchants)
[Delete a merchantDELETE/tax/merchants/:id](#delete-a-merchant)

## The Merchant object

### Attributes

**id** `string`

The ID of the merchant, `merch_…`.

**object** `string, value is "tax.merchant"`

String representing the object's type.

**reference\_merchant\_id** `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](#your-own-merchant-ids).

**name** `string`

The merchant's business name.

**email** `string`

The merchant's email address.

**default\_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.

**default\_address.address\_line\_1** `string`

**default\_address.address\_line\_2** `string`

Optional second address line.

**default\_address.address\_city** `string`

**default\_address.address\_province** `string`

ISO 3166-2 subdivision code.

**default\_address.address\_postal\_code** `string`

**default\_address.address\_country** `string`

ISO 3166-1 alpha-2 country code.

**tax\_ids** `array of objects`

The merchant's tax IDs. They identify the selling entity for documentation and reporting. A platform calculation can override them with `merchant.tax_ids`.

**tax\_ids\[].type** `string`

Tax ID type, e.g. `us_ein`, `eu_vat`, or `gb_vat`. See [tax IDs](https://docs.numeral.com/essentials/tax-ids.md) for every type.

**tax\_ids\[].value** `string`

The tax ID, 1–100 characters.

**status** `enum`

`active` or `deleted`.

**testmode** `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.

**created\_at** `timestamp`

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

**metadata** `object`

Key-value pairs from the request.

```json The Merchant object theme={null}
{
  "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" }`.

> [!WARNING]
>
> `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`.

```text Using your own ID theme={null}
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](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/merchants).

### Parameters

**reference\_merchant\_id** `string`

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

**name** `string`

The merchant's business name.

**email** `string`

The merchant's email address.

**default\_address** `object`

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

**default\_address.address\_line\_1** `string` *required*

**default\_address.address\_line\_2** `string`

**default\_address.address\_city** `string` *required*

**default\_address.address\_province** `string` *required*

ISO 3166-2 subdivision code.

**default\_address.address\_postal\_code** `string` *required*

**default\_address.address\_country** `string` *required*

ISO 3166-1 alpha-2 country code.

**tax\_ids** `array of objects`

The merchant's tax IDs.

**tax\_ids\[].type** `string` *required*

Tax ID type, e.g. `us_ein` or `eu_vat`. See [tax IDs](https://docs.numeral.com/essentials/tax-ids.md).

**tax\_ids\[].value** `string` *required*

The tax ID, 1–100 characters.

**metadata** `object`

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

### Returns

A [Merchant object](#the-merchant-object).

```bash POST /tax/merchants theme={null}
curl https://api.numeralhq.com/tax/merchants \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-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"
    }
  }'
```

```json Response theme={null}
{
  "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](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/update_merchant).

You can't change `reference_merchant_id`.

### Parameters

**merchant\_id** `string` *required*

The merchant's `id` or your `reference_merchant_id`.

**name** `string`

The merchant's business name.

**email** `string`

The merchant's email address.

**default\_address** `object`

The merchant's business address. If you send it, send every required address field. Same fields as on [create](#create-a-merchant).

**tax\_ids** `array of objects`

Replaces all of the merchant's existing tax IDs. Same fields as on [create](#create-a-merchant).

**metadata** `object`

String key-value pairs.

### Returns

The updated [Merchant object](#the-merchant-object).

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

```json Response theme={null}
{
  "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](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/get_merchant).

**merchant\_id** `string` *required*

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

### Returns

A [Merchant object](#the-merchant-object).

```bash GET /tax/merchants/:id theme={null}
curl https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

## List all merchants

Returns your merchants, one page at a time. Deleted merchants aren't included. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/list_merchants).

**limit** `integer` (default: 10)

Maximum number of merchants to return. Up to 100.

**cursor** `string`

The `last_merchant_id` from the previous page.

### Returns

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

```bash GET /tax/merchants theme={null}
curl 'https://api.numeralhq.com/tax/merchants?limit=10' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

```json Response theme={null}
{
  "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. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/delete_merchant).

* 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.

**merchant\_id** `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).

```bash DELETE /tax/merchants/:id theme={null}
curl -X DELETE https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

```json Response theme={null}
{
  "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](https://docs.numeral.com/api-reference/v2026-11-01/error-codes.md).

| 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). |

```json 404 theme={null}
{
  "code": 404,
  "type": "MERCHANT_NOT_FOUND",
  "message": "Merchant not found or belongs to different testmode"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.