Skip to main content

​
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

IP-Based Tax Resolution

Resolve customer location from an IP address for tax calculations without requiring a full address.

Resolution Modes

Choose how to handle insufficient IP data: strict, zero, approximate, or best_effort.

​
Inherited from 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

IP-Based Tax ResolutionYou can now pass customer.ip instead of (or in addition to) customer.address:
{
  "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.
Note: 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-03-01" \
  -H "Content-Type: application/json"

​
API Version Header

To use this version, include the X-API-Version header: 
X-API-Version: 2026-03-01
The merchant and platform calculation endpoints require the 2026-03-01 (or 2026-01-01) version header.

​
Base URL

https://api.numeralhq.com

​
Endpoints Overview

​
New in 2026-03-01

FeatureEndpoints AffectedDescription
IP-Based Tax Resolution/tax/calculations, /tax/platform/calculationsPass customer.ip instead of or in addition to customer.address

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