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

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

# API Reference

Welcome to the Numeral API v2026-03-01 reference documentation. This version introduces **IP-Based Tax Resolution**, allowing you to calculate taxes using a customer's IP address instead of a full street address.

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

<CardGroup cols={2}>
  <Card title="IP-Based Tax Resolution" icon="globe" href="/api-reference/v2026-03-01/endpoint/calculations">
    Resolve customer location from an IP address for tax calculations without requiring a full address.
  </Card>

  <Card title="Resolution Modes" icon="sliders" href="/api-reference/v2026-03-01/error-codes">
    Choose how to handle insufficient IP data: strict, zero, approximate, or best\_effort.
  </Card>
</CardGroup>

### Inherited from 2026-01-01

<CardGroup cols={2}>
  <Card title="Merchant Management" icon="store" href="/api-reference/v2026-03-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-03-01/endpoint/platform_calculations">
    Calculate taxes for marketplace transactions with per-unit pricing and fee support.
  </Card>
</CardGroup>

## Key Changes

<Info>
  **IP-Based Tax Resolution**

  You can now pass `customer.ip` instead of (or in addition to) `customer.address`:

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

  The response will include `location_source`, `resolution_precision`, and `address_used` to indicate how the location was determined.
</Info>

<Warning>
  **Note: 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-03-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-03-01
```

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

## Base URL

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

## Endpoints Overview

### New in 2026-03-01

| Feature                 | Endpoints Affected                                | Description                                                        |
| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| IP-Based Tax Resolution | `/tax/calculations`, `/tax/platform/calculations` | Pass `customer.ip` instead of or in addition to `customer.address` |

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