Skip to main content

​
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.
EndpointAmount Behavior
/tax/calculationsTotal line item value
/tax/platform/calculationsPer-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:
RoleDescription
marketplace_providerYou operate a marketplace connecting buyers and sellers
payment_processorYou process payments for the transaction
merchant_of_recordYou 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 RoleTransactions Created
payment_processor2 (order + fee)
marketplace_provider1 (order only)
merchant_of_record1 (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"
    }
  ]
}
FieldDescription
tax_authority_nameHuman-readable authority name
tax_authority_typeSTATE, COUNTY, CITY, or DISTRICT
tax_typeSALES, 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

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

​
Adopting Platform Calculations

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

​
Previous Versions

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