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

Merchant Management

Create and manage merchants (sellers) on your platform with full CRUD operations.

Platform Calculations

Calculate taxes for marketplace transactions with per-unit pricing and fee support.

Key Changes

Breaking Change: Amount is Per-Unit in Platform CalculationsIn /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

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-01-01" \
  -H "Content-Type: application/json"

API Version Header

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

X-API-Version: 2026-01-01

The merchant and platform calculation endpoints require the 2026-01-01 version header.

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

Get Started

AI help

Integration FAQs

Essentials

Objects

API Reference

Introduction v2026-01-01

API Reference

What’s New in 2026-01-01

Merchant Management

Platform Calculations

Key Changes

Authentication

API Version Header

Base URL

Endpoints Overview

New in 2026-01-01

Existing Endpoints

​API Reference

​What’s New in 2026-01-01

Merchant Management

Platform Calculations

​Key Changes

​Authentication

​API Version Header

​Base URL

​Endpoints Overview

​New in 2026-01-01

​Existing Endpoints

API Reference

What’s New in 2026-01-01

Key Changes

Authentication

API Version Header

Base URL

Endpoints Overview

New in 2026-01-01

Existing Endpoints