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

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

# API Reference

Welcome to the Numeral API v2026-11-01 reference documentation. This version explains every tax result: each tax jurisdiction row gets a `note`, and calculations get a single `effective_tax_rate` for the order.

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

> **[Tax jurisdiction notes](https://docs.numeral.com/v2026-11-01/objects/calculations.md#notes)**
>
> Every `tax_jurisdictions` row has a `note` that says why it came out the way it did: exempt customer, no registration, reverse charge, and so on.

> **[Effective tax rate](https://docs.numeral.com/v2026-11-01/objects/calculations.md#effective-tax-rate)**
>
> Calculations return one blended `effective_tax_rate` for the order, including flat fees. Platform calculations return one for the order and one for fees.

Nothing else changes. Requests, tax amounts and errors are the same as `2026-03-01`. See the [changelog](https://docs.numeral.com/api-reference/v2026-11-01/changelog.md) for the migration steps.

### Inherited from earlier versions

> **[IP-Based Tax Resolution](https://docs.numeral.com/v2026-11-01/objects/calculations.md#ip-based-tax-resolution)**
>
> Resolve customer location from an IP address without a full street address (from 2026-03-01).

> **[Platform Calculations](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/platform_calculations)**
>
> Calculate taxes for marketplace transactions with merchant and fee support (from 2026-01-01).

> [!WARNING]
>
> **Amount is per-unit.** On calculations and platform calculations, the `amount` field on line items is the **per-unit price**. The taxable base is `amount × quantity`. For a \$25.00 item with quantity 3, send `"amount": 2500, "quantity": 3`.

## 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-11-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-11-01
```

> [!NOTE]
>
> Your account has a default API version. The `X-API-Version` header overrides it for that request. See [Versioning](https://docs.numeral.com/api-reference/versioning.md).

## Base URL

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

## Endpoints Overview

### Changed in 2026-11-01

| Endpoint | Method | Change |
| - | - | - |
| `/tax/calculations` | `POST` | `note` on each tax jurisdiction row; `effective_tax_rate` added |
| `/tax/platform/calculations` | `POST` | `note` on each tax jurisdiction row; `effective_tax_rate` added to `totals.order` and `totals.fees` |
| `/tax/transactions` | `POST` | `note` on each tax jurisdiction row |
| `/tax/transactions/:id` | `GET` | `note` on each tax jurisdiction row |
| `/tax/refunds` | `POST` | `note` on each tax jurisdiction row |
| `/tax/transactions/:id/refunds` | `GET` | `note` on each tax jurisdiction row |
| `/tax/refund_reversals` | `POST` | `note` on each tax jurisdiction row |

### Unchanged

| Endpoint | Method | Description |
| - | - | - |
| `/tax/merchants` | `POST`, `GET` | Create and list merchants |
| `/tax/merchants/:id` | `GET`, `POST`, `DELETE` | Get, update, delete a merchant |
| `/tax/platform/transactions` | `POST` | Record platform transactions |
| `/tax/transactions/:id` | `DELETE` | Delete a transaction |
| `/tax/products` | `POST`, `GET` | Manage products |
| `/tax/customers` | `POST`, `GET` | Manage customers |
| `/tax/certificates`, `/tax/certificate-requests`, `/tax/certificate-uploads` | various | Exemption certificates |
| `/tax/exchange_rates` | `GET` | Daily exchange rate for a currency pair |
| `/tax/ping` | `GET` | Health check |


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