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

# Introduction v2026-01-01

> Complete API reference for Numeral API version 2026-01-01

# API Reference

Welcome to the Numeral API v2026-01-01 reference documentation. This version introduces **Merchant Management** and **Platform Calculations** for marketplace and payment processor scenarios.

## What's New in 2026-01-01

<CardGroup cols={2}>
  <Card title="Merchant Management" icon="store" href="/api-reference/v2026-01-01/endpoint/merchants">
    Create and manage merchants (sellers) on your platform with full CRUD operations.
  </Card>

  <Card title="Platform Calculations" icon="calculator" href="/api-reference/v2026-01-01/endpoint/platform_calculations">
    Calculate taxes for marketplace transactions with per-unit pricing and fee support.
  </Card>
</CardGroup>

## Key Changes

<Warning>
  **Breaking Change: Amount is Per-Unit in Platform Calculations**

  In `/platform/calculations`, the `amount` field represents the **per-unit price**. The taxable base is calculated as:

  ```
  taxable_base = amount × quantity
  ```

  For example, for a \$25.00 item with quantity 3:

  * `amount`: 2500 (in cents)
  * `quantity`: 3
  * **Taxable base**: \$75.00
</Warning>

## Authentication

All API requests require a Bearer token in the Authorization header:

```bash theme={null}
curl -X POST https://api.numeralhq.com/tax/calculations \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json"
```

## API Version Header

To use this version, include the `X-API-Version` header:

```bash theme={null}
X-API-Version: 2026-01-01
```

<Note>
  The merchant and platform calculation endpoints **require** the `2026-01-01` version header.
</Note>

## Base URL

```
https://api.numeralhq.com
```

## Endpoints Overview

### New in 2026-01-01

| Endpoint                     | Method   | Description              |
| ---------------------------- | -------- | ------------------------ |
| `/tax/merchants`             | `POST`   | Create a new merchant    |
| `/tax/merchants`             | `GET`    | List all merchants       |
| `/tax/merchants/:id`         | `GET`    | Get a merchant           |
| `/tax/merchants/:id`         | `POST`   | Update a merchant        |
| `/tax/merchants/:id`         | `DELETE` | Delete a merchant        |
| `/tax/platform/calculations` | `POST`   | Calculate platform taxes |

### Existing Endpoints

| Endpoint            | Method        | Description          |
| ------------------- | ------------- | -------------------- |
| `/tax/calculations` | `POST`        | Calculate taxes      |
| `/tax/transactions` | `POST`        | Record a transaction |
| `/tax/refunds`      | `POST`        | Create a refund      |
| `/tax/products`     | `POST`, `GET` | Manage products      |
| `/tax/customers`    | `POST`, `GET` | Manage customers     |