Skip to main content
The calculation object contains tax rate information with enhanced support for business-to-business (B2B) transactions. A calculation also includes a calculation_id that you’ll use to record a transaction for filing.

​
When to create Calculations

Calculations should be used any time you need to calculate sales tax before charging a customer for a transaction. Most e-commerce clients will submit a POST to /tax/calculations during their checkout flow after the end customer has submitted their address, but before collecting payment. core flow

​
How to create Calculations

curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2025-05-12' \
  --data '{
  "customer": {
    "address": {
      "address_line_1": "10 Downing Street",
      "address_city": "London",
      "address_province": "Greater London",
      "address_postal_code": "SW1A 2AA",
      "address_country": "GB",
      "address_type": "shipping"
    },
    "type": "BUSINESS",
    "tax_ids": [
      {
        "type": "VAT",
        "value": "GB123456789"
      }
    ]
  },
  "order_details": {
    "customer_currency_code": "GBP",
    "tax_included_in_amount": false,
    "automatic_tax": "auto",
    "line_items": [
      {
        "reference_line_item_id": "line_123456789",
        "product_category": "SAAS_GENERAL",
        "amount": 200,
        "quantity": 2
      }
    ]
  }
}'

{
  "testmode": false,
  "id": "calc_1748380341807e125e1a0-415e-407d-98e4-00d2717f4ac9",
  "object": "tax.calculation",
  "customer_currency_code": "GBP",
  "line_items": [
    {
      "line_item_id": "li_1748380341807098a8e8c-654c-4b32-9dbd-7bf883482ca2",
      "product": {
        "reference_line_item_id": "line_123456789",
        "reference_product_id": "1",
        "reference_product_name": "Sales",
        "product_tax_code": "SAAS_GENERAL"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.20,
          "rate_type": "VAT",
          "jurisdiction_name": "United Kingdom",
          "fee_amount": 0,
          "note": "collection_threshold_reached"
        }
      ],
      "tax_amount": 40,
      "amount_excluding_tax": 200,
      "amount_including_tax": 240,
      "quantity": 2
    }
  ],
  "total_tax_amount": 40,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 200,
  "total_amount_including_tax": 240,
  "expires_at": 1748466741,
  "customer": {
    "type": "BUSINESS"
  },
  "automatic_tax": "auto"
}
We return both the aggregate tax information as well as a detailed breakdown for each line item. Many users will just use the total_tax_amount to identify what to charge a user, but you will always have the details as you need them.

​
Request Parameters

​
Customer Object (Enhanced)

{
  "customer": {
    "id": "cus_123456789", // Optional customer ID
    "address": {
      "address_line_1": "10 Downing Street",
      "address_line_2": "", // Optional
      "address_city": "London",
      "address_province": "Greater London",
      "address_postal_code": "SW1A 2AA",
      "address_country": "GB",
      "address_type": "shipping" // "shipping" or "billing"
    },
    "type": "BUSINESS", // "BUSINESS" or "CONSUMER" (default if omitted)
    "tax_ids": [ // Required for BUSINESS (except US), not allowed for CONSUMER
      {
        "type": "VAT", // "VAT" or "GST"
        "value": "GB123456789"
      }
    ]
  }
}
New Fields in 2025-05-12:
  • type (string): Customer type affecting tax calculation
    • CONSUMER (default) - Individual consumer, standard B2C tax calculations
    • BUSINESS - Business entity requiring tax IDs for B2B tax logic
  • tax_ids (array): Required for BUSINESS customers (except US), not allowed for CONSUMER customers
    • type (string): Tax ID type (VAT or GST)
    • value (string): Valid tax identification number
    • Note: Not required for US-based BUSINESS customers in calculation requests

​
Order Details (Enhanced)

{
  "order_details": {
    "customer_currency_code": "GBP", // Supports 32 currencies
    "tax_included_in_amount": false,
    "automatic_tax": "auto", // New field for tax control
    "line_items": [
      {
        "reference_line_item_id": "line_123456789", // Optional
        "reference_product_id": "p-1233543", // Required if no product_category
        "product_category": "SAAS_GENERAL", // Required if no reference_product_id
        "amount": 200, // In currency's smallest unit (e.g., cents for USD, whole units for JPY)
        "quantity": 2
      }
    ]
  }
}
New Fields in 2025-05-12:
  • automatic_tax (string): Controls tax collection and registration behavior
    • auto - Return tax rates everywhere you have an active registration
    • disabled - Always return 0 tax regardless of thresholds

​
Enhanced Features in 2025-05-12

​
Customer Types and B2B Logic

The 2025-05-12 version introduces business-to-business (B2B) tax logic through customer types:
  • BUSINESS customers: Must provide valid tax IDs (except for US-based calculations), enabling B2B tax exemptions and reverse charge mechanisms in applicable jurisdictions
  • CONSUMER customers: Standard B2C tax calculations without tax ID requirements. This is the default if the type field is omitted.

​
Tax ID Validation

When using customer.type: "BUSINESS", tax IDs are validated in real-time:
  • VAT IDs: Validated against European VIES database
  • GST IDs: Validated for applicable countries
  • Invalid tax IDs will result in calculation errors

​
Automatic Tax Configuration

The automatic_tax setting provides granular control over tax collection:
SettingTax Rates ReturnedRegistration TriggeredUse Case
auto✅ Where you have active registration❌ NoStandard operation
disabled❌ Always 0❌ NoTax-exempt scenarios

​
Enhanced Currency Support

The 2025-05-12 version supports 32 currencies (22 additional beyond the original 10), enabling global tax calculations across major markets including GBP, AUD, JPY, SGD, and many others.

​
IP-Based Tax Resolution (New in 2026-03-01)

Starting with API version 2026-03-01, you can provide a customer IP address instead of a full street address. The API will geo-resolve the IP to determine the taxable location.

​
The customer.ip Object

{
  "customer": {
    "type": "CONSUMER",
    "ip": {
      "value": "217.217.113.167",   // IPv4 or IPv6
      "resolution": "strict"         // "strict", "zero", "approximate", or "best_effort"
    }
  }
}
At least one of customer.address or customer.ip must be provided. If both are given, the address is used first with IP as a fallback.

​
Resolution Modes

ModeBehavior
strict (default)Error if IP cannot resolve to sufficient detail for tax calculation
zeroReturn zero-rate response if resolution is insufficient
approximateAttempts to resolve the IP to an address using heuristics
best_effortTry approximate first, fall back to zero rates
Numeral strongly recommends using strict mode to stay as compliant as possible.

​
New Response Fields

Responses include additional fields when using this API version:
FieldTypeDescription
location_sourcestring"address" or "ip" — which input was used for tax determination
resolution_precisionstringPrecision level: STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, or APPROXIMATED
address_usedobjectThe resolved address that was actually used for tax calculation
curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2026-03-01' \
  --data '{
  "customer": {
    "type": "CONSUMER",
    "ip": {
      "value": "217.217.113.167",
      "resolution": "strict"
    }
  },
  "order_details": {
    "customer_currency_code": "USD",
    "tax_included_in_amount": false,
    "automatic_tax": "auto",
    "line_items": [
      {
        "product_category": "SAAS_GENERAL",
        "reference_line_item_id": "ip-test-001",
        "amount": 10000,
        "quantity": 1
      }
    ]
  }
}'

{
  "testmode": true,
  "id": "calc_...",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_...",
      "product": {
        "reference_line_item_id": "ip-test-001",
        "reference_product_id": "default-saas-general",
        "reference_product_name": "Default SAAS_GENERAL Product",
        "product_tax_code": "SAAS_GENERAL"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.06,
          "tax_due_decimal": 600,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Pennsylvania",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.01,
          "tax_due_decimal": 100,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "ALLEGHENY",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 700,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10700,
      "quantity": 1
    }
  ],
  "total_tax_amount": 700,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 10000,
  "total_amount_including_tax": 10700,
  "expires_at": 1771710514,
  "customer": { "type": "CONSUMER" },
  "automatic_tax": "auto",
  "address_resolution_status": "POSTAL_ONLY",
  "address_used": {
    "address_line_1": "",
    "address_line_2": "",
    "address_city": "",
    "address_province": "PA",
    "address_postal_code": "15212",
    "address_country": "US"
  },
  "location_source": "ip",
  "resolution_precision": "POSTAL"
}

​
Further documentation

The full documentation for creating calculations is on this page.