API Changelog

Version 2026-01-01

Release Date: January 1, 2026This version introduces Merchant Management and Platform Calculations for marketplace and payment processor scenarios.

New Endpoints

Merchant CRUD

Full create, read, update, and delete operations for merchants (sellers) on your platform.

POST /tax/merchants - Create merchant
GET /tax/merchants - List merchants
GET /tax/merchants/:id - Get merchant
POST /tax/merchants/:id - Update merchant
DELETE /tax/merchants/:id - Delete merchant

Platform Calculations

Tax calculations for marketplace transactions with merchant context.

POST /tax/platform/calculations

Platform Transactions

Convert platform calculations into recorded transactions for tax reporting.

POST /tax/platform/transactions

Breaking Changes

Amount is Per-Unit in Platform CalculationsThe most significant change in this version is how amount is interpreted in the /platform/calculations endpoint.

Endpoint	Amount Behavior
`/tax/calculations`	Total line item value
`/tax/platform/calculations`	Per-unit price

Example:

// For 3 items at $25.00 each

// Standard calculations (amount = total)
{
  "amount": 7500,  // $75.00 total
  "quantity": 3
}

// Platform calculations (amount = per-unit)
{
  "amount": 2500,  // $25.00 per unit
  "quantity": 3    // taxable base = $75.00
}

New Features

Merchant Management

Create and manage merchants (sellers) on your platform:

curl -X POST https://api.numeralhq.com/tax/merchants \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_merchant_id": "seller-123",
    "name": "Acme Seller",
    "default_address": {
      "address_line_1": "123 Main St",
      "address_city": "San Francisco",
      "address_province": "CA",
      "address_postal_code": "94105",
      "address_country": "US"
    }
  }'

Key features:

Use your own IDs via reference_merchant_id
Store merchant tax IDs for B2B transactions
Default addresses used as origin in calculations
Testmode isolation (test merchants separate from live)

Platform Calculations

Calculate taxes for marketplace/platform transactions:

curl -X POST https://api.numeralhq.com/tax/platform/calculations \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "address": { ... }
    },
    "merchant": {
      "merchant_id": "seller-123"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "line_items": [
        { "amount": 2500, "quantity": 3, "product_category": "GENERAL_MERCHANDISE" }
      ]
    },
    "roles": ["marketplace_provider"]
  }'

Key features:

Per-unit pricing - amount × quantity = taxable base
Merchant context - Link calculations to specific sellers
Platform roles - Specify your role (marketplace, payment processor, merchant of record)
Fee calculations - Separate tax calculation for platform fees
Enhanced response - Includes tax_authority_name, tax_authority_type, tax_type

Platform Roles

Specify your role in the transaction:

Role	Description
`marketplace_provider`	You operate a marketplace connecting buyers and sellers
`payment_processor`	You process payments for the transaction
`merchant_of_record`	You are the legal seller of record

Platform Transactions

Convert platform calculations into recorded transactions for tax reporting and filing:

curl -X POST https://api.numeralhq.com/tax/platform/transactions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_calculation_id": "plat_calc_abc123",
    "reference_order_id": "order_12345",
    "reference_payment_id": "pay_67890",
    "transaction_processed_at": 1736300000
  }'

Key features:

Returns a list - May return one or two transactions depending on your platform role
Payment processors - Receive separate order and fee transactions
Marketplace providers / Merchants of record - Receive a single order transaction
Transaction types - type: "order" for sales, type: "fee" for platform fees

Platform Role	Transactions Created
`payment_processor`	2 (order + fee)
`marketplace_provider`	1 (order only)
`merchant_of_record`	1 (order only)

Fee Calculations

Calculate taxes on platform fees separately from order items:

{
  "order_details": { ... },
  "fee_details": {
    "line_items": [
      { "amount": 299, "quantity": 1, "product_category": "ELECTRONIC_GOODS" }
    ]
  }
}

The response includes separate totals:

{
  "totals": {
    "order": { "tax_amount": 875 },
    "fees": { "tax_amount": 26 }
  }
}

Enhanced Tax Response

Platform calculations include additional jurisdiction details:

{
  "tax_jurisdictions": [
    {
      "tax_rate": 0.0875,
      "rate_type": "SALES TAX",
      "jurisdiction_name": "California",
      "tax_authority_name": "California State",
      "tax_authority_type": "STATE",
      "tax_type": "SALES"
    }
  ]
}

Field	Description
`tax_authority_name`	Human-readable authority name
`tax_authority_type`	`STATE`, `COUNTY`, `CITY`, or `DISTRICT`
`tax_type`	`SALES`, `USE`, `VAT`, or `GST`

New Error Format

Breaking Change: Simplified Error ResponseError responses now use a flattened structure instead of the nested error object from previous versions.

Previous format (2025-05-12 and earlier):

{
  "error": {
    "code": "product_not_found",
    "message": "Product not found"
  }
}

New format (2026-01-01):

{
  "code": 400,
  "type": "PRODUCT_NOT_FOUND",
  "message": "Product not found"
}

Key changes:

Flattened structure - No more nested error object
HTTP status in response - code field contains the HTTP status code
Uppercase error types - Error types are now SCREAMING_SNAKE_CASE
Consistent typing - Use the type field for programmatic error handling

Error Codes Reference

See the complete list of error types and their meanings.

Migration Guide

From 2025-05-12 to 2026-01-01

Update error handling - Error responses use a new flattened format with code, type, and message fields
New endpoints require X-API-Version: 2026-01-01 header
Platform calculations use per-unit amounts (important!)

Adopting Platform Calculations

Create merchants for your sellers
Use /tax/platform/calculations instead of /tax/calculations
Remember: amount is per-unit, taxable base = amount × quantity
Specify your roles in each request

Previous Versions

Version	Key Features
2025-05-12	Customer types (B2B/B2C), tax IDs, 32 currencies, automatic_tax
2024-09-01	Base version with core tax calculation features

Get Started

AI help

Integration FAQs

Essentials

Objects

API Reference

Changelog

API Changelog

Version 2026-01-01

New Endpoints

Merchant CRUD

Platform Calculations

Platform Transactions

Breaking Changes

New Features

Merchant Management

Platform Calculations

Platform Roles

Platform Transactions

Fee Calculations

Enhanced Tax Response

New Error Format

Error Codes Reference

Migration Guide

From 2025-05-12 to 2026-01-01

Adopting Platform Calculations

Previous Versions

​API Changelog

​Version 2026-01-01

​New Endpoints

Merchant CRUD

Platform Calculations

Platform Transactions

​Breaking Changes

​New Features

​Merchant Management

​Platform Calculations

​Platform Roles

​Platform Transactions

​Fee Calculations

​Enhanced Tax Response

​New Error Format

Error Codes Reference

​Migration Guide

​From 2025-05-12 to 2026-01-01

​Adopting Platform Calculations

​Previous Versions

API Changelog

Version 2026-01-01

New Endpoints

Breaking Changes

New Features

Merchant Management

Platform Calculations

Platform Roles

Platform Transactions

Fee Calculations

Enhanced Tax Response

New Error Format

Migration Guide

From 2025-05-12 to 2026-01-01

Adopting Platform Calculations

Previous Versions