Skip to main content

​
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

EndpointMethodDescription
/tax/merchantsPOSTCreate a new merchant
/tax/merchantsGETList all merchants
/tax/merchants/:idGETGet a merchant
/tax/merchants/:idPOSTUpdate a merchant
/tax/merchants/:idDELETEDelete a merchant
/tax/platform/calculationsPOSTCalculate platform taxes

​
Existing Endpoints

EndpointMethodDescription
/tax/calculationsPOSTCalculate taxes
/tax/transactionsPOSTRecord a transaction
/tax/refundsPOSTCreate a refund
/tax/productsPOST, GETManage products
/tax/customersPOST, GETManage customers