API Versioning

Understanding and using different versions of the Numeral API

API Versioning

Numeral API supports multiple versions to ensure backward compatibility while introducing new features. This document explains how to specify API versions and the differences between them.

Specifying an API Version

To specify which API version you want to use, include the X-API-Version header in your request:

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: 2026-11-01' \
  --data '{ ... }'

Your account also has a default API version. Requests without the header use the account default; the header overrides it for that request. Without either, requests use 2024-09-01.

Available Versions

2026-11-01 (Latest)

Explains every tax result:

--header 'X-API-Version: 2026-11-01'

New features:

• Tax jurisdiction notes - Every tax_jurisdictions row has a note saying why it came out the way it did (exempt customer, no registration, reverse charge, and so on)
• Effective tax rate - Calculations return effective_tax_rate for the order; platform calculations return one for the order and one for fees

No request, amount or error changes from 2026-03-01.

2026-03-01

IP-based tax resolution:

--header 'X-API-Version: 2026-03-01'

New features:

• IP-Based Tax Resolution - Calculate taxes using customer IP address instead of full address
• Resolution Modes - strict, zero, approximate, best_effort strategies for handling insufficient IP data
• Enhanced Response - Includes location_source, resolution_precision, address_used fields

2026-01-01

Marketplace and platform support:

--header 'X-API-Version: 2026-01-01'

New features:

• Merchant Management - Full CRUD for marketplace sellers
• Platform Calculations - Tax calculations for marketplace/platform transactions
• Per-Unit Pricing - In platform calculations, amount is per-unit (total = amount × quantity)
• Platform Roles - Specify your role (marketplace_provider, payment_processor, merchant_of_record)
• Fee Calculations - Separate tax calculation for platform fees
• Enhanced Response - Includes tax_authority_name, tax_authority_type, tax_type

Important: In /platform/calculations, the amount field is per-unit, not total. The taxable base = amount × quantity.

2025-05-12

Enhanced version with B2B support:

--header 'X-API-Version: 2025-05-12'

This version includes:

• Customer Types - Support for business-to-business (B2B) and consumer transactions
• Tax IDs - VAT and GST identification support
• Automatic Tax Settings - Control over tax collection and registration (field is required)
• Expanded Currency Support - 32 currencies supported
• Required Fields - origin_address and automatic_tax are now required fields

2024-09-01 (Default)

If you don’t send the header and your account has no default version set, your request will default to the 2024-09-01 version.

This is the base API version with core functionality.

Version Differences

Feature	2024-09-01	2025-05-12	2026-01-01	2026-03-01	2026-11-01
Customer Types	Not supported	BUSINESS/CONSUMER	BUSINESS/CONSUMER	BUSINESS/CONSUMER	BUSINESS/CONSUMER
Tax IDs	Not supported	VAT, GST, EIN	VAT, GST, EIN	VAT, GST, EIN	VAT, GST, EIN
Automatic Tax	Not configurable	auto/disabled (required)	auto/disabled (required)	auto/disabled (required)	auto/disabled (required)
Origin Address	Optional	Required	Required	Required	Required
Supported Currencies	10	32	32	32	32
Merchants	Not supported	Not supported	Full CRUD	Full CRUD	Full CRUD
Platform Calculations	Not supported	Not supported	Supported	Supported	Supported
Per-Unit Pricing	N/A	N/A	In platform calcs	In platform calcs	In platform calcs
Fee Calculations	Not supported	Not supported	Supported	Supported	Supported
IP-Based Tax Resolution	Not supported	Not supported	Not supported	Supported	Supported
Resolution Modes	N/A	N/A	N/A	strict, zero, approximate, best_effort	strict, zero, approximate, best_effort
Tax jurisdiction note	Internal method values	Internal method values	Not returned	Not returned	Reason codes
effective_tax_rate	Not returned	Not returned	Not returned	Not returned	Calculations and platform totals

New in 2026-11-01

Tax jurisdiction notes and effective tax rate

Every tax_jurisdictions row has a note, and calculations return effective_tax_rate:

{
  "line_items": [
    {
      "tax_jurisdictions": [
        {
          "tax_rate": 0,
          "rate_type": "VAT",
          "tax_authority_name": "FR",
          "tax_type": "VAT",
          "note": "b2b_reverse_charge"
        }
      ]
    }
  ],
  "total_tax_amount": 0,
  "effective_tax_rate": 0
}

See Calculations for every note value.

New in 2026-03-01

IP-Based Tax Resolution

Pass a customer IP address instead of a full address for tax calculations:

{
  "customer": {
    "ip": {
      "value": "217.217.113.167",
      "resolution": "strict"
    }
  }
}

Works with both /tax/calculations and /tax/platform/calculations. Supports IPv4 and IPv6 addresses.

New in 2026-01-01

Merchant Endpoints

Endpoint	Method	Description
/tax/merchants	POST	Create a merchant
/tax/merchants	GET	List merchants
/tax/merchants/:id	GET	Get a merchant
/tax/merchants/:id	POST	Update a merchant
/tax/merchants/:id	DELETE	Delete a merchant

Platform Calculations

Endpoint	Method	Description
/tax/platform/calculations	POST	Calculate taxes for platform transactions

Version Migration

All API versions will be maintained in parallel. We recommend:

• New integrations: Use 2026-11-01 for access to all features, including tax jurisdiction notes and the effective tax rate
• Marketplace/platforms: Use 2026-11-01 for merchant, platform calculation, IP resolution, and per-bucket effective rate support
• Existing integrations: Can continue using current version; upgrade when needed

For detailed changelog, see the Changelog.