Make sure you generate an API key before making any requests. See API Keys for details.

​
Overview

The Numeral API allows you to calculate and collect sales tax for your business. With our API, you can:
  • Get tax information for products and addresses
  • Record completed sales
  • Handle refunds
  • Manage products and customers
  • Support business-to-business (B2B) transactions
  • Configure automatic tax collection behavior

​
Authentication

All API endpoints are authenticated using Bearer tokens. Include your API key in the Authorization header of all requests: 
curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2025-05-12' \
  --data '{ ... }'

​
Base URL

All API requests should be made to: 
https://api.numeralhq.com/

​
API Version

This documentation covers the 2025-05-12 API version. You must explicitly specify this version in your API requests by including the X-API-Version header: 
--header 'X-API-Version: 2025-05-12'

​
New Features in 2025-05-12

​
Customer Types

Support for business-to-business (B2B) transactions with the customer.type field:
  • BUSINESS - Business customer (requires tax IDs)
  • CONSUMER - Consumer customer (default)

​
Tax IDs

When customer.type is set to BUSINESS, you must provide tax identification:
  • Supports VAT and GST tax IDs
  • Required for BUSINESS type customers
  • Not allowed for CONSUMER type customers

​
Automatic Tax

Control over tax collection and registration with the order_details.automatic_tax field:
  • auto - Return tax rates everywhere you have an active registration
  • disabled - Always return 0 tax regardless of thresholds

​
Expanded Currency Support

This version supports all currencies from 2024-09-01 plus 22 additional currencies including GBP, AUD, JPY, and more. For a complete list of supported currencies, see the Currencies documentation.