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

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 Resolution

You 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 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

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

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