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

# API Versioning

> Understanding and using different versions of the Numeral API

# API Versioning

Numeral API supports multiple versions to ensure backward compatibility while introducing new features. This document explains how to specify API versions and the differences between them.

## Specifying an API Version

To specify which API version you want to use, include the `X-API-Version` header in your request:

```bash theme={null}
curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2026-11-01' \
  --data '{ ... }'
```

Your account also has a default API version. Requests without the header use the account default; the header overrides it for that request. Without either, requests use `2024-09-01`.

## Available Versions

### 2026-11-01 (Latest)

Explains every tax result:

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

**New features:**

* **Tax jurisdiction notes** - Every `tax_jurisdictions` row has a `note` saying why it came out the way it did (exempt customer, no registration, reverse charge, and so on)
* **Effective tax rate** - Calculations return `effective_tax_rate` for the order; platform calculations return one for the order and one for fees

No request, amount or error changes from `2026-03-01`.

### 2026-03-01

IP-based tax resolution:

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

**New features:**

* **IP-Based Tax Resolution** - Calculate taxes using customer IP address instead of full address
* **Resolution Modes** - `strict`, `zero`, `approximate`, `best_effort` strategies for handling insufficient IP data
* **Enhanced Response** - Includes `location_source`, `resolution_precision`, `address_used` fields

### 2026-01-01

Marketplace and platform support:

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

**New features:**

* **Merchant Management** - Full CRUD for marketplace sellers
* **Platform Calculations** - Tax calculations for marketplace/platform transactions
* **Per-Unit Pricing** - In platform calculations, `amount` is per-unit (total = amount × quantity)
* **Platform Roles** - Specify your role (marketplace\_provider, payment\_processor, merchant\_of\_record)
* **Fee Calculations** - Separate tax calculation for platform fees
* **Enhanced Response** - Includes tax\_authority\_name, tax\_authority\_type, tax\_type

> [!WARNING]
>
> **Important:** In `/platform/calculations`, the `amount` field is **per-unit**, not total.
> The taxable base = `amount × quantity`.

### 2025-05-12

Enhanced version with B2B support:

```bash theme={null}
--header 'X-API-Version: 2025-05-12'
```

This version includes:

* **Customer Types** - Support for business-to-business (B2B) and consumer transactions
* **Tax IDs** - VAT and GST identification support
* **Automatic Tax Settings** - Control over tax collection and registration (field is **required**)
* **Expanded Currency Support** - 32 currencies supported
* **Required Fields** - `origin_address` and `automatic_tax` are now required fields

### 2024-09-01 (Default)

If you don't send the header and your account has no default version set, your request will default to the `2024-09-01` version.

This is the base API version with core functionality.

## Version Differences

| Feature | 2024-09-01 | 2025-05-12 | 2026-01-01 | 2026-03-01 | 2026-11-01 |
| - | - | - | - | - | - |
| Customer Types | Not supported | BUSINESS/CONSUMER | BUSINESS/CONSUMER | BUSINESS/CONSUMER | BUSINESS/CONSUMER |
| Tax IDs | Not supported | VAT, GST, EIN | VAT, GST, EIN | VAT, GST, EIN | VAT, GST, EIN |
| Automatic Tax | Not configurable | auto/disabled (required) | auto/disabled (required) | auto/disabled (required) | auto/disabled (required) |
| Origin Address | Optional | Required | Required | Required | Required |
| Supported Currencies | 10 | 32 | 32 | 32 | 32 |
| Merchants | Not supported | Not supported | Full CRUD | Full CRUD | Full CRUD |
| Platform Calculations | Not supported | Not supported | Supported | Supported | Supported |
| Per-Unit Pricing | N/A | N/A | In platform calcs | In platform calcs | In platform calcs |
| Fee Calculations | Not supported | Not supported | Supported | Supported | Supported |
| IP-Based Tax Resolution | Not supported | Not supported | Not supported | Supported | Supported |
| Resolution Modes | N/A | N/A | N/A | strict, zero, approximate, best\_effort | strict, zero, approximate, best\_effort |
| Tax jurisdiction `note` | Internal method values | Internal method values | Not returned | Not returned | Reason codes |
| `effective_tax_rate` | Not returned | Not returned | Not returned | Not returned | Calculations and platform totals |

## New in 2026-11-01

### Tax jurisdiction notes and effective tax rate

Every `tax_jurisdictions` row has a `note`, and calculations return `effective_tax_rate`:

```json theme={null}
{
  "line_items": [
    {
      "tax_jurisdictions": [
        {
          "tax_rate": 0,
          "rate_type": "VAT",
          "tax_authority_name": "FR",
          "tax_type": "VAT",
          "note": "b2b_reverse_charge"
        }
      ]
    }
  ],
  "total_tax_amount": 0,
  "effective_tax_rate": 0
}
```

See [Calculations](https://docs.numeral.com/v2026-11-01/objects/calculations.md#notes) for every `note` value.

## New in 2026-03-01

### IP-Based Tax Resolution

Pass a customer IP address instead of a full address for tax calculations:

```json theme={null}
{
  "customer": {
    "ip": {
      "value": "217.217.113.167",
      "resolution": "strict"
    }
  }
}
```

Works with both `/tax/calculations` and `/tax/platform/calculations`. Supports IPv4 and IPv6 addresses.

## New in 2026-01-01

### Merchant Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/tax/merchants` | POST | Create a merchant |
| `/tax/merchants` | GET | List merchants |
| `/tax/merchants/:id` | GET | Get a merchant |
| `/tax/merchants/:id` | POST | Update a merchant |
| `/tax/merchants/:id` | DELETE | Delete a merchant |

### Platform Calculations

| Endpoint | Method | Description |
| - | - | - |
| `/tax/platform/calculations` | POST | Calculate taxes for platform transactions |

## Version Migration

All API versions will be maintained in parallel. We recommend:

* **New integrations**: Use `2026-11-01` for access to all features, including tax jurisdiction notes and the effective tax rate
* **Marketplace/platforms**: Use `2026-11-01` for merchant, platform calculation, IP resolution, and per-bucket effective rate support
* **Existing integrations**: Can continue using current version; upgrade when needed

For detailed changelog, see the [Changelog](https://docs.numeral.com/api-reference/v2026-11-01/changelog.md).


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