---
title: "POST /tax/calculations"
method: POST
path: "/tax/calculations"
---

# POST /tax/calculations

`POST /tax/calculations`

Get tax information for a given product and address

## Headers

- `X-API-Version` '2026-03-01' | '2026-01-01' | '2025-05-12' | '2024-09-01', required

## Request body

- union
  - CalculationRequestV202603
    - `customer` CustomerDetailsV202603, required
      - `id` string — The ID of the customer that you created in our system. Can be used to log customer information or indicate that a purchaser is tax exempt. For more, see [Creating a Customer](/api-reference/endpoint/customers).
      - `type` 'CONSUMER' | 'BUSINESS' — The type of customer. `CONSUMER` are private individuals. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST.
      - `tax_ids` object[] — Array of tax identification numbers. Only available for `BUSINESS` customer types.
        - `type` string, required — Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
        - `value` string, required — The tax ID value
      - `address` object
        - `address_line_1` string, required
        - `address_line_2` string
        - `address_city` string, required
        - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
        - `address_postal_code` string, required
        - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
        - `address_type` string, required — The type of address. Must be one of: `shipping` or `billing`. Required if `ip` is not provided.
      - `ip` object — IP address for geo-based tax resolution. Required if `address` is not provided.
        - `value` string, required — A valid IPv4 or IPv6 address.
        - `resolution` 'strict' | 'zero' | 'approximate' | 'best_effort' — How to handle insufficient IP resolution. strict (default): error if insufficient. zero: return zero-rate. approximate: attempt to resolve using heuristics. best_effort: try approximate, fall back to zero.
    - `origin_address` Address, required
      - `address_line_1` string, required
      - `address_line_2` string
      - `address_city` string, required
      - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
      - `address_postal_code` string, required
      - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
    - `order_details` OrderDetails, required
      - `customer_currency_code` string, required — The currency code of the transaction. For API version 2024-09-01: Must be either 'USD' or 'CAD'. For API version 2025-05-12: Supports 32 currencies including USD, CAD, EUR, GBP, AUD, CHF, JPY, and more.
      - `tax_included_in_amount` boolean, required — For the line items in this transaction, does the amount include tax? This should typically be `false` for most North American sales, but may vary by jurisdiction and business model.
      - `automatic_tax` 'auto' | 'disabled' — Controls automatic tax behavior. Available with API version 2025-05-12. `auto`: return real rates if client is registered/enabled in that jurisdiction, bypasses threshold checking. `disabled`: always return 0 tax rates regardless of registration status.
      - `line_items` LineItem[], required — Each line item should represent one type of product. For compliance, we require either a `reference_product_id` or a `product_category`. See [this guide](/essentials/integration-guides/products-and-categories) for more.
        - `reference_line_item_id` string — The ID of the line item from your system. This field is optional and will be primarily used for record keeping.
        - `reference_product_id` string — The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no `product_category`.
        - `product_category` string — A tax category from our [category taxonomy](/essentials/product-categories). Required if no `reference_product_id`.
        - `fallback_product_category` string — Optional fallback product category used when `reference_product_id` is provided but no matching product exists in Numeral. Lets integration partners always pass a product ID without first ensuring the product has been created. Must be a valid product category from the Numeral taxonomy — an invalid value returns a 400. If a matching product is found, its stored category takes precedence.
        - `amount` number, required — The price of this line item in the currency's smallest unit. We will calculate tax against this value. (e.g., if USD then 2000 = $20.00, if JPY then 2000 = ¥2000)
        - `quantity` number, required — The quantity of this product being sold. Primarily used for record keeping.
    - `metadata` Metadata — You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
      - `example_key` string — Storing things like an order number may be useful for reporting and reconciliation.
    - `default_customer_type` 'CONSUMER' | 'BUSINESS' — Optional fallback customer type used when `customer.id` is provided but no matching customer exists in Numeral. Lets integration partners always pass a customer ID without first ensuring the customer has been created. When the lookup misses, this value drives tax-exemption logic and business tax-ID validation as if it were `customer.type`. If a matching customer is found, the stored `customer.type` takes precedence. Available in API version `2026-03-01` and later.
  - CalculationRequestV2025
    - `customer` CustomerDetailsV2025, required
      - `id` string — The ID of the customer that you created in our system. Can be used to log customer information or indicate that a purchaser is tax exempt. For more, see [Creating a Customer](/api-reference/endpoint/customers).
      - `type` 'CONSUMER' | 'BUSINESS' — The type of customer. Available with API version 2025-05-12. `CONSUMER` are private individuals who are not registered for VAT/GST (or any other local indirect-tax scheme) in the country where the supply is taxed. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST (or an equivalent local tax) in the country where the supply is taxed.
      - `tax_ids` object[] — Array of tax identification numbers. Available with API version 2025-05-12. Only available for `BUSINESS` customer types.
        - `type` string, required — Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
        - `value` string, required — The tax ID value
      - `address` object, required
        - `address_line_1` string, required
        - `address_line_2` string
        - `address_city` string, required
        - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
        - `address_postal_code` string, required
        - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
        - `address_type` string, required — The type of address. Must be one of: `shipping` or `billing`. For physical goods, `shipping` should be used. For software and digital goods, `billing` is more appropriate
    - `origin_address` Address, required
      - `address_line_1` string, required
      - `address_line_2` string
      - `address_city` string, required
      - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
      - `address_postal_code` string, required
      - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
    - `order_details` OrderDetails, required
      - `customer_currency_code` string, required — The currency code of the transaction. For API version 2024-09-01: Must be either 'USD' or 'CAD'. For API version 2025-05-12: Supports 32 currencies including USD, CAD, EUR, GBP, AUD, CHF, JPY, and more.
      - `tax_included_in_amount` boolean, required — For the line items in this transaction, does the amount include tax? This should typically be `false` for most North American sales, but may vary by jurisdiction and business model.
      - `automatic_tax` 'auto' | 'disabled' — Controls automatic tax behavior. Available with API version 2025-05-12. `auto`: return real rates if client is registered/enabled in that jurisdiction, bypasses threshold checking. `disabled`: always return 0 tax rates regardless of registration status.
      - `line_items` LineItem[], required — Each line item should represent one type of product. For compliance, we require either a `reference_product_id` or a `product_category`. See [this guide](/essentials/integration-guides/products-and-categories) for more.
        - `reference_line_item_id` string — The ID of the line item from your system. This field is optional and will be primarily used for record keeping.
        - `reference_product_id` string — The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no `product_category`.
        - `product_category` string — A tax category from our [category taxonomy](/essentials/product-categories). Required if no `reference_product_id`.
        - `fallback_product_category` string — Optional fallback product category used when `reference_product_id` is provided but no matching product exists in Numeral. Lets integration partners always pass a product ID without first ensuring the product has been created. Must be a valid product category from the Numeral taxonomy — an invalid value returns a 400. If a matching product is found, its stored category takes precedence.
        - `amount` number, required — The price of this line item in the currency's smallest unit. We will calculate tax against this value. (e.g., if USD then 2000 = $20.00, if JPY then 2000 = ¥2000)
        - `quantity` number, required — The quantity of this product being sold. Primarily used for record keeping.
    - `metadata` Metadata — You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
      - `example_key` string — Storing things like an order number may be useful for reporting and reconciliation.
  - CalculationRequestV2025
    - `customer` CustomerDetailsV2025, required
      - `id` string — The ID of the customer that you created in our system. Can be used to log customer information or indicate that a purchaser is tax exempt. For more, see [Creating a Customer](/api-reference/endpoint/customers).
      - `type` 'CONSUMER' | 'BUSINESS' — The type of customer. Available with API version 2025-05-12. `CONSUMER` are private individuals who are not registered for VAT/GST (or any other local indirect-tax scheme) in the country where the supply is taxed. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST (or an equivalent local tax) in the country where the supply is taxed.
      - `tax_ids` object[] — Array of tax identification numbers. Available with API version 2025-05-12. Only available for `BUSINESS` customer types.
        - `type` string, required — Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
        - `value` string, required — The tax ID value
      - `address` object, required
        - `address_line_1` string, required
        - `address_line_2` string
        - `address_city` string, required
        - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
        - `address_postal_code` string, required
        - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
        - `address_type` string, required — The type of address. Must be one of: `shipping` or `billing`. For physical goods, `shipping` should be used. For software and digital goods, `billing` is more appropriate
    - `origin_address` Address, required
      - `address_line_1` string, required
      - `address_line_2` string
      - `address_city` string, required
      - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
      - `address_postal_code` string, required
      - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
    - `order_details` OrderDetails, required
      - `customer_currency_code` string, required — The currency code of the transaction. For API version 2024-09-01: Must be either 'USD' or 'CAD'. For API version 2025-05-12: Supports 32 currencies including USD, CAD, EUR, GBP, AUD, CHF, JPY, and more.
      - `tax_included_in_amount` boolean, required — For the line items in this transaction, does the amount include tax? This should typically be `false` for most North American sales, but may vary by jurisdiction and business model.
      - `automatic_tax` 'auto' | 'disabled' — Controls automatic tax behavior. Available with API version 2025-05-12. `auto`: return real rates if client is registered/enabled in that jurisdiction, bypasses threshold checking. `disabled`: always return 0 tax rates regardless of registration status.
      - `line_items` LineItem[], required — Each line item should represent one type of product. For compliance, we require either a `reference_product_id` or a `product_category`. See [this guide](/essentials/integration-guides/products-and-categories) for more.
        - `reference_line_item_id` string — The ID of the line item from your system. This field is optional and will be primarily used for record keeping.
        - `reference_product_id` string — The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no `product_category`.
        - `product_category` string — A tax category from our [category taxonomy](/essentials/product-categories). Required if no `reference_product_id`.
        - `fallback_product_category` string — Optional fallback product category used when `reference_product_id` is provided but no matching product exists in Numeral. Lets integration partners always pass a product ID without first ensuring the product has been created. Must be a valid product category from the Numeral taxonomy — an invalid value returns a 400. If a matching product is found, its stored category takes precedence.
        - `amount` number, required — The price of this line item in the currency's smallest unit. We will calculate tax against this value. (e.g., if USD then 2000 = $20.00, if JPY then 2000 = ¥2000)
        - `quantity` number, required — The quantity of this product being sold. Primarily used for record keeping.
    - `metadata` Metadata — You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
      - `example_key` string — Storing things like an order number may be useful for reporting and reconciliation.
  - CalculationRequest
    - `customer` CustomerDetails, required
      - `id` string — The ID of the customer that you created in our system. Can be used to log customer information or indicate that a purchaser is tax exempt. For more, see [Creating a Customer](/api-reference/endpoint/customers).
      - `address` object, required
        - `address_line_1` string, required
        - `address_line_2` string
        - `address_city` string, required
        - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
        - `address_postal_code` string, required
        - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
        - `address_type` string, required — The type of address. Must be one of: `shipping` or `billing`. For physical goods, `shipping` should be used. For software and digital goods, `billing` is more appropriate
    - `origin_address` Address, required
      - `address_line_1` string, required
      - `address_line_2` string
      - `address_city` string, required
      - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
      - `address_postal_code` string, required
      - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
    - `order_details` OrderDetails, required
      - `customer_currency_code` string, required — The currency code of the transaction. For API version 2024-09-01: Must be either 'USD' or 'CAD'. For API version 2025-05-12: Supports 32 currencies including USD, CAD, EUR, GBP, AUD, CHF, JPY, and more.
      - `tax_included_in_amount` boolean, required — For the line items in this transaction, does the amount include tax? This should typically be `false` for most North American sales, but may vary by jurisdiction and business model.
      - `automatic_tax` 'auto' | 'disabled' — Controls automatic tax behavior. Available with API version 2025-05-12. `auto`: return real rates if client is registered/enabled in that jurisdiction, bypasses threshold checking. `disabled`: always return 0 tax rates regardless of registration status.
      - `line_items` LineItem[], required — Each line item should represent one type of product. For compliance, we require either a `reference_product_id` or a `product_category`. See [this guide](/essentials/integration-guides/products-and-categories) for more.
        - `reference_line_item_id` string — The ID of the line item from your system. This field is optional and will be primarily used for record keeping.
        - `reference_product_id` string — The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no `product_category`.
        - `product_category` string — A tax category from our [category taxonomy](/essentials/product-categories). Required if no `reference_product_id`.
        - `fallback_product_category` string — Optional fallback product category used when `reference_product_id` is provided but no matching product exists in Numeral. Lets integration partners always pass a product ID without first ensuring the product has been created. Must be a valid product category from the Numeral taxonomy — an invalid value returns a 400. If a matching product is found, its stored category takes precedence.
        - `amount` number, required — The price of this line item in the currency's smallest unit. We will calculate tax against this value. (e.g., if USD then 2000 = $20.00, if JPY then 2000 = ¥2000)
        - `quantity` number, required — The quantity of this product being sold. Primarily used for record keeping.
    - `metadata` Metadata — You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
      - `example_key` string — Storing things like an order number may be useful for reporting and reconciliation.

## Response `200`

Calculate response

- CalculationResponse
  - `id` string — The ID of the `calculation`. You will use this to create a `transaction`.
  - `object` string — The type of object: `tax.calculation`.
  - `customer_currency_code` string — The ISO-4217 currency code of the transaction.
  - `customer` object — Customer information returned in the response.
    - `type` 'CONSUMER' | 'BUSINESS' — The type of customer. `CONSUMER` are private individuals. `BUSINESS` are companies or legal entities registered for VAT/GST.
  - `automatic_tax` 'auto' | 'disabled' — The automatic tax setting for this calculation.
  - `line_items` TransactionLineItem[]
    - `product` object
      - `reference_product_name` string
      - `reference_line_item_id` string
      - `reference_product_id` string
      - `product_tax_code` string
    - `tax_jurisdictions` object[]
      - `tax_rate` number — The tax rate percentage applied to this transaction.
      - `tax_due_decimal` number — Tax amount due for this jurisdiction in the currency's smallest unit.
      - `rate_type` string — Descriptive rate classification for this jurisdiction.
      - `fee_amount` number — The flat fee that is added to this transaction. Like all numeric values, this will be returned in cents and should be added directly to the tax amount independent of other percentages. For example, a $100 transaction taxed at 5% and with a `fee_amount: 50` will lead to `($100 * 5% + 0.50) = $5.50` in tax being charged
      - `tax_authority_name` string — Name of the tax authority.
      - `tax_authority_type` string — Type of tax authority (e.g., STATE, COUNTY, CITY, DISTRICT).
      - `tax_type` string — Type of tax: SALES, USE, VAT, or GST.
    - `quantity` number
    - `tax_amount` number
    - `amount_excluding_tax` number
    - `amount_including_tax` number
  - `tax_included_in_amount` boolean
  - `total_tax_amount` number — Total tax to charge on this `calculation`.
  - `total_amount_excluding_tax` number — Total sale charge, excluding tax.
  - `total_amount_including_tax` number — Total sale charge plus tax. What you should charge your customer.
  - `expires_at` number — Epoch datetime representing the date and time the tax rates are valid until.
  - `testmode` boolean — `True` if using a production API key. `False` if using a test API key.
  - `address_resolution_status` 'EXACT' | 'POSTAL_FALLBACK_1' | 'POSTAL_ONLY' — Status of address resolution for the customer address. `EXACT`: exact address match found, `POSTAL_FALLBACK_1`: used postal code fallback, `POSTAL_ONLY`: only postal code was used for tax calculation.
  - `address_used` object — The actual address used for tax calculation after resolution.
    - `address_line_1` string, required
    - `address_line_2` string
    - `address_city` string, required
    - `address_province` string, required
    - `address_postal_code` string, required
    - `address_country` string, required
  - `metadata` Metadata — You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.
    - `example_key` string — Storing things like an order number may be useful for reporting and reconciliation.
  - `location_source` 'address' | 'ip' — Which input was used for tax determination.
  - `resolution_precision` 'STREET' | 'POSTAL_PLUS' | 'POSTAL' | 'PROVINCE' | 'COUNTRY' | 'APPROXIMATED' — The precision level of the resolved location.

## Other responses

- `400` — Validation error
- `404` — Resource not found

---

[API](https://skmtc.dev/numeralhq/apis/numeral-api.md) · [All operations](https://skmtc.dev/numeralhq/apis/numeral-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/numeralhq/numeral-api/revisions/6c4df0cf417d/schema)