> ## Documentation Index > Fetch the complete documentation index at: https://docs.numeral.com/llms.txt > Use this file to discover all available pages before exploring further. # Calculations > Use the `calculation` object to get tax rates with per-unit pricing, origin addresses, and enhanced jurisdiction detail 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. core flow ## How to create Calculations ``` curl --request POST \ --url https://api.numeralhq.com/tax/calculations \ --header 'Authorization: Bearer ' \ --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" } }' ``` ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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: ```json theme={null} { "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](/api-reference/v2026-01-01/endpoint/calculations).