Calculations

The calculation object contains tax rate information with support for per-unit line item pricing, origin addresses, metadata passthrough, and enhanced tax jurisdiction detail. 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.

How to create Calculations

Calculation Request (2026-01-01)

curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2026-01-01' \
  --data '{
  "customer": {
    "address": {
      "address_city": "Nashville",
      "address_country": "US",
      "address_line_1": "123 Broadway",
      "address_postal_code": "37203",
      "address_province": "TN",
      "address_type": "billing"
    }
  },
  "metadata": {
    "payment_id": "68407cb7-e1fa-47fa-8244-bd9411d53c61"
  },
  "order_details": {
    "automatic_tax": "auto",
    "customer_currency_code": "USD",
    "line_items": [
      {
        "amount": 1000000,
        "product_category": "BEVERAGES",
        "quantity": 1
      },
      {
        "amount": 1000000,
        "product_category": "GENERAL_MERCHANDISE",
        "quantity": 1
      }
    ],
    "tax_included_in_amount": false
  },
  "origin_address": {
    "address_city": "Nashville",
    "address_country": "US",
    "address_line_1": "500 Church St",
    "address_line_2": "",
    "address_postal_code": "37219",
    "address_province": "TN"
  }
}'

Sample Response

{
  "testmode": true,
  "id": "calc_17725956342644181bdd4-5975-44d5-8c96-05233f565fdd",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1772595634232f1d34578-aed2-42cb-a917-09b2c8322b20",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "default-beverages",
        "reference_product_name": "Default BEVERAGES Product",
        "product_tax_code": "BEVERAGES"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.04,
          "tax_due_decimal": 40000,
          "fee_amount": 0,
          "rate_type": "FOOD_AND_DRUG STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.0225,
          "tax_due_decimal": 3600,
          "fee_amount": 0,
          "rate_type": "FOOD_AND_DRUG CITY LOCAL SALES TAX",
          "tax_authority_name": "Place 52006, TN",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.005,
          "tax_due_decimal": 800,
          "fee_amount": 0,
          "rate_type": "FOOD_AND_DRUG DISTRICT LOCAL SALES TAX",
          "tax_authority_name": "Other Special Applications 91951",
          "tax_authority_type": "",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 44400,
      "amount_excluding_tax": 1000000,
      "amount_including_tax": 1044400,
      "quantity": 1
    },
    {
      "line_item_id": "li_177259563426441045f22-c55e-4a4b-a1b9-e880b1d6a7b0",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "default-general-merchandise",
        "reference_product_name": "Default GENERAL_MERCHANDISE Product",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0275,
          "tax_due_decimal": 4400,
          "fee_amount": 0,
          "rate_type": "SINGLE_ARTICLE STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.07,
          "tax_due_decimal": 70000,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.0225,
          "tax_due_decimal": 3600,
          "fee_amount": 0,
          "rate_type": "GENERAL CITY LOCAL SALES TAX",
          "tax_authority_name": "Place 52006, TN",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.005,
          "tax_due_decimal": 800,
          "fee_amount": 0,
          "rate_type": "GENERAL DISTRICT LOCAL SALES TAX",
          "tax_authority_name": "Other Special Applications 91951",
          "tax_authority_type": "",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 78800,
      "amount_excluding_tax": 1000000,
      "amount_including_tax": 1078800,
      "quantity": 1
    }
  ],
  "total_tax_amount": 123200,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 2000000,
  "total_amount_including_tax": 2123200,
  "expires_at": 1772682034,
  "metadata": {
    "payment_id": "68407cb7-e1fa-47fa-8244-bd9411d53c61"
  },
  "customer": {
    "type": "CONSUMER"
  },
  "automatic_tax": "auto",
  "address_resolution_status": "EXACT",
  "address_used": {
    "address_line_1": "500 Church St",
    "address_line_2": "",
    "address_city": "Nashville",
    "address_province": "TN",
    "address_postal_code": "37219",
    "address_country": "US"
  }
}

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.

Breaking Change: In version 2026-01-01, the amount field on line items represents the per-unit price. The taxable base is calculated as amount x quantity. This is a change from earlier versions where amount represented the total line item value.

Request Parameters

Customer Object

{
  "customer": {
    "id": "cus_123456789", // Optional customer ID
    "address": {
      "address_line_1": "123 Broadway",
      "address_line_2": "", // Optional
      "address_city": "Nashville",
      "address_province": "TN",
      "address_postal_code": "37203",
      "address_country": "US",
      "address_type": "billing" // "shipping" or "billing"
    },
    "type": "CONSUMER", // "BUSINESS" or "CONSUMER" (default if omitted)
    "tax_ids": [ // Required for BUSINESS (except US), not allowed for CONSUMER
      {
        "type": "eu_vat", // Stripe-style tax ID type (439+ types supported)
        "value": "DE123456789"
      }
    ]
  }
}

address (object): Required. The customer’s address for tax calculation.
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): Stripe-style tax ID type. 439+ types supported including us_ein, eu_vat, gb_vat, au_abn, ca_bn, jp_cn, and many more.
- value (string): Valid tax identification number

Origin Address

{
  "origin_address": {
    "address_line_1": "500 Church St",
    "address_line_2": "", // Optional
    "address_city": "Nashville",
    "address_province": "TN",
    "address_postal_code": "37219",
    "address_country": "US"
  }
}

The ship-from address used for origin-based tax jurisdictions. Required for accurate tax calculation in states that use origin-based sourcing rules.

Order Details

{
  "order_details": {
    "customer_currency_code": "USD", // Supports 32 currencies
    "tax_included_in_amount": false,
    "automatic_tax": "auto", // "auto" or "disabled"
    "line_items": [
      {
        "reference_line_item_id": "line_123456789", // Optional
        "reference_product_id": "p-1233543", // Required if no product_category
        "product_category": "GENERAL_MERCHANDISE", // Required if no reference_product_id
        "fallback_product_category": "GENERAL_MERCHANDISE", // Optional - used if reference_product_id is not found
        "amount": 1000000, // Per-unit price in smallest currency unit (e.g., cents)
        "quantity": 1 // Taxable base = amount x quantity
      }
    ]
  }
}

amount (number): Per-unit price in the currency’s smallest unit (e.g., cents for USD). The taxable base is amount x quantity.
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
fallback_product_category (string): Optional. If you pass a reference_product_id that does not exist in Numeral, the calculation falls back to this product category instead of returning a 400. Useful for integration partners who want to always send a product ID without first ensuring the product has been created in Numeral. Must be a valid product category from the Numeral taxonomy. If the reference_product_id is found, its stored category takes precedence.

Metadata

{
  "metadata": {
    "payment_id": "68407cb7-e1fa-47fa-8244-bd9411d53c61"
  }
}

Optional. Store arbitrary key-value pairs for your own reference. Values must be strings of 255 characters or fewer. Metadata is echoed back in the response unchanged.

New Features in 2026-01-01

Per-Unit Line Item Pricing

The amount field on line items now represents the per-unit price rather than the total line item value. The taxable base is calculated as amount x quantity.

Version	`amount` Meaning	Example: 3 items at $25.00 each
2025-05-12 and earlier	Total line item value	`"amount": 7500, "quantity": 3`
2026-01-01	Per-unit price	`"amount": 2500, "quantity": 3`

Enhanced Tax Jurisdiction Detail

Tax jurisdiction objects in the response now include richer detail from the tax engine:

Field	Type	Description
`tax_due_decimal`	number	Tax amount due for this jurisdiction in the currency’s smallest unit
`tax_authority_name`	string	Name of the tax authority (e.g., “Tennessee”, “ALLEGHENY”)
`tax_authority_type`	string	Type of authority (e.g., “STATE”, “COUNTY”, “CITY”, “DISTRICT”)
`tax_type`	string	Type of tax: `SALES`, `USE`, `VAT`, or `GST`
`rate_type`	string	Descriptive rate classification (e.g., “GENERAL STATE SALES TAX”, “FOOD_AND_DRUG CITY LOCAL SALES TAX”)

The jurisdiction_name and note fields from prior versions are no longer included in 2026-01-01 responses.

Origin Address Support

You can now provide an origin_address representing the ship-from location. This is used for origin-based tax jurisdictions where the seller’s location affects the applicable tax rate.

Address Resolution

Responses now include information about how the address was resolved:

address_resolution_status (string): Indicates the precision of the address match.

Value	Description
`EXACT`	Exact street-level address match
`POSTAL_FALLBACK_1`	Fell back to postal code-level match
`POSTAL_ONLY`	Only postal code was used for resolution

address_used (object): The resolved address that was actually used for the tax calculation.

Expanded Tax ID Types

Tax ID types have been expanded from 2 types (VAT, GST) to 439+ Stripe-style types. Examples include us_ein, eu_vat, gb_vat, au_abn, ca_bn, jp_cn, in_gst, br_cnpj, and many more.

Standard Error Format

Error responses now use a flat format:

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

This replaces the previous nested format ({ "error": { "code": "...", "message": "..." } }).

Further documentation

The full documentation for creating calculations is on this page.

Get Started

AI help

Integration FAQs

Essentials

Objects

API Reference

When to create Calculations

How to create Calculations

Request Parameters

Customer Object

Origin Address

Order Details

Metadata

New Features in 2026-01-01

Per-Unit Line Item Pricing

Enhanced Tax Jurisdiction Detail

Origin Address Support

Address Resolution

Expanded Tax ID Types

Standard Error Format

Further documentation

​When to create Calculations

​How to create Calculations

​Request Parameters

​Customer Object

​Origin Address

​Order Details

​Metadata

​New Features in 2026-01-01

​Per-Unit Line Item Pricing

​Enhanced Tax Jurisdiction Detail

​Origin Address Support

​Address Resolution

​Expanded Tax ID Types

​Standard Error Format

​Further documentation

When to create Calculations

How to create Calculations

Request Parameters

Customer Object

Origin Address

Order Details

Metadata

New Features in 2026-01-01

Per-Unit Line Item Pricing

Enhanced Tax Jurisdiction Detail

Origin Address Support

Address Resolution

Expanded Tax ID Types

Standard Error Format

Further documentation