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

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

<Note>
  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.
</Note>

## The Merchant Object

```json 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
}
```

## 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" } }`

<Warning>
  `reference_merchant_id` must be unique per client and testmode combination. You cannot change it after creation.
</Warning>

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

```json theme={null}
{
  "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](/essentials/tax-ids).

## 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](/api-reference/v2026-03-01/endpoint/merchants)
* [Get Merchant](/api-reference/v2026-03-01/endpoint/get_merchant)
* [List Merchants](/api-reference/v2026-03-01/endpoint/list_merchants)
* [Update Merchant](/api-reference/v2026-03-01/endpoint/update_merchant)
* [Delete Merchant](/api-reference/v2026-03-01/endpoint/delete_merchant)
* [Platform Calculations](/api-reference/v2026-03-01/endpoint/platform_calculations)