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

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

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 for the migration steps.

Inherited from earlier versions

IP-Based Tax Resolution

Resolve customer location from an IP address without a full street address (from 2026-03-01).

Platform Calculations

Calculate taxes for marketplace transactions with merchant and fee support (from 2026-01-01).

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:

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:

X-API-Version: 2026-11-01

Your account has a default API version. The X-API-Version header overrides it for that request. See Versioning.

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

Getting Started

API Reference

Introduction v2026-11-01

API Reference

What’s New in 2026-11-01

Tax jurisdiction notes

Effective tax rate

Inherited from earlier versions

IP-Based Tax Resolution

Platform Calculations

Authentication

API Version Header

Base URL

Endpoints Overview

Changed in 2026-11-01

Unchanged

​API Reference

​What’s New in 2026-11-01

Tax jurisdiction notes

Effective tax rate

​Inherited from earlier versions

IP-Based Tax Resolution

Platform Calculations

​Authentication

​API Version Header

​Base URL

​Endpoints Overview

​Changed in 2026-11-01

​Unchanged

API Reference

What’s New in 2026-11-01

Inherited from earlier versions

Authentication

API Version Header

Base URL

Endpoints Overview

Changed in 2026-11-01

Unchanged