> ## 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. # Create Calculations > Get tax information for a given product and address or IP Get tax information for a given product and address ## cURL Header Example Use `X-API-Version` explicitly in requests: ```bash theme={null} curl --request POST \ --url https://api.numeralhq.com/tax/calculations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'X-API-Version: 2025-05-12' \ --data '{ ... }' ``` ## OpenAPI ````yaml POST /tax/calculations openapi: 3.0.1 info: title: Numeral API description: API for sales tax calculations license: name: MIT version: 1.0.0 servers: - url: https://api.numeralhq.com/ security: - bearerAuth: [] paths: /tax/calculations: post: description: Get tax information for a given product and address parameters: - name: X-API-Version in: header required: true schema: type: string enum: - '2026-03-01' - '2026-01-01' - '2025-05-12' - '2024-09-01' description: API version to use. example: '2026-03-01' requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/CalculationRequestV202603' title: API Version 2026-03-01 - $ref: '#/components/schemas/CalculationRequestV2025' title: API Version 2026-01-01 - $ref: '#/components/schemas/CalculationRequestV2025' title: API Version 2025-05-12 - $ref: '#/components/schemas/CalculationRequest' title: API Version 2024-09-01 examples: '2024-09-01': summary: Basic calculation (API version 2024-09-01) value: customer: address: address_line_1: 4 Privet Drive address_city: Little Whining address_province: CA address_postal_code: '90210' address_country: US address_type: shipping order_details: customer_currency_code: USD tax_included_in_amount: false line_items: - reference_product_id: wand_elder_12 amount: 10000 quantity: 1 '2026-03-01': summary: IP-based calculation (API version 2026-03-01) value: 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: - reference_line_item_id: line_123456789 product_category: SAAS_GENERAL amount: 10000 quantity: 2 '2026-01-01': summary: Per-unit pricing calculation (API version 2026-01-01) value: customer: type: CONSUMER address: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '90210' address_country: US address_type: shipping origin_address: address_line_1: 3990 N County Rd 300 E address_line_2: Unit 2 address_city: Danville address_province: IN address_postal_code: '46122' address_country: US order_details: customer_currency_code: USD tax_included_in_amount: false automatic_tax: auto line_items: - reference_line_item_id: line_20260101 product_category: GENERAL_MERCHANDISE amount: 2500 quantity: 3 2025-05-12-consumer: summary: Enhanced consumer calculation (API version 2025-05-12) value: customer: type: CONSUMER address: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '90210' address_country: US address_type: shipping origin_address: address_line_1: 3990 N County Rd 300 E address_line_2: Unit 2 address_city: Danville address_province: IN address_postal_code: '46122' address_country: US order_details: customer_currency_code: USD tax_included_in_amount: false automatic_tax: auto line_items: - reference_product_id: wand_elder_12 amount: 10000 quantity: 1 2025-05-12-business: summary: Business customer with tax IDs (API version 2025-05-12) value: customer: type: BUSINESS tax_ids: - type: gb_vat value: GB123456789 address: address_line_1: 123 Business St address_city: Commerce City address_province: NY address_postal_code: '10001' address_country: US address_type: billing origin_address: address_line_1: Tech Park 1 address_city: Dublin address_province: L address_postal_code: D02 XY45 address_country: IE order_details: customer_currency_code: EUR tax_included_in_amount: false automatic_tax: auto line_items: - reference_product_id: business_software_license amount: 50000 quantity: 5 2025-05-12-US-standard: summary: US standard consumer sale (API version 2025-05-12) value: customer: address: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '92037' address_country: US address_type: shipping origin_address: address_line_1: 3990 N County Rd 300 E address_line_2: Unit 2 address_city: Danville address_province: IN address_postal_code: '46122' address_country: US order_details: customer_currency_code: USD tax_included_in_amount: false automatic_tax: auto line_items: - reference_line_item_id: line_123456789 product_category: SAAS_GENERAL amount: 200 quantity: 2 2025-05-12-US-business: summary: US business sale (API version 2025-05-12) value: customer: type: BUSINESS tax_ids: - type: us_ein value: 12-3456789 address: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '92037' address_country: US address_type: billing origin_address: address_line_1: 3990 N County Rd 300 E address_line_2: Unit 2 address_city: Danville address_province: IN address_postal_code: '46122' address_country: US order_details: customer_currency_code: USD tax_included_in_amount: false automatic_tax: auto line_items: - reference_line_item_id: line_123456789 product_category: SAAS_GENERAL amount: 200 quantity: 2 required: true responses: '200': description: Calculate response content: application/json: schema: $ref: '#/components/schemas/CalculationResponse' examples: '2024-09-01': summary: Basic calculation response (API version 2024-09-01) value: id: calc_1726683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9 object: tax.calculation customer_currency_code: USD line_items: - product: reference_product_name: Elder Wand reference_product_id: wand_elder_12 product_tax_code: GENERAL_MERCHANDISE tax_jurisdictions: - tax_rate: 0.1 rate_type: SALES TAX jurisdiction_name: California fee_amount: 0 quantity: 1 tax_amount: 1000 amount_excluding_tax: 10000 amount_including_tax: 11000 tax_included_in_amount: false total_tax_amount: 1000 total_amount_excluding_tax: 10000 total_amount_including_tax: 11000 expires_at: 1726683511 testmode: true address_resolution_status: EXACT address_used: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '90210' address_country: US '2026-03-01': summary: IP-based calculation response (API version 2026-03-01) value: id: calc_17725714816806a81b828-0757-4ec2-9307-3c1001733f73 object: tax.calculation customer_currency_code: USD customer: type: CONSUMER automatic_tax: auto line_items: - 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: 3000 fee_amount: 0 rate_type: GENERAL STATE SALES TAX tax_authority_name: Pennsylvania tax_authority_type: '' tax_type: SALES - tax_rate: 0.01 tax_due_decimal: 500 fee_amount: 0 rate_type: GENERAL COUNTY LOCAL SALES TAX tax_authority_name: ALLEGHENY tax_authority_type: '' tax_type: SALES quantity: 5 tax_amount: 3500 amount_excluding_tax: 50000 amount_including_tax: 53500 total_tax_amount: 3500 tax_included_in_amount: false total_amount_excluding_tax: 50000 total_amount_including_tax: 53500 expires_at: 1772657881 testmode: true 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 '2026-01-01': summary: Per-unit pricing response (API version 2026-01-01) value: id: calc_1762683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9 object: tax.calculation customer_currency_code: USD customer: type: CONSUMER automatic_tax: auto line_items: - product: reference_product_name: Elder Wand reference_product_id: wand_elder_12 product_tax_code: GENERAL_MERCHANDISE tax_jurisdictions: - tax_rate: 0.1 tax_due_decimal: 750 fee_amount: 0 rate_type: GENERAL STATE SALES TAX tax_authority_name: California tax_authority_type: STATE tax_type: SALES quantity: 3 tax_amount: 750 amount_excluding_tax: 7500 amount_including_tax: 8250 tax_included_in_amount: false total_tax_amount: 750 total_amount_excluding_tax: 7500 total_amount_including_tax: 8250 expires_at: 1762683511 testmode: true address_resolution_status: EXACT address_used: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '90210' address_country: US '2025-05-12': summary: Enhanced B2B calculation response (API version 2025-05-12) value: id: calc_1726683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9 object: tax.calculation customer_currency_code: USD customer: type: CONSUMER automatic_tax: auto line_items: - product: reference_product_name: Elder Wand reference_product_id: wand_elder_12 product_tax_code: GENERAL_MERCHANDISE tax_jurisdictions: - tax_rate: 0.1 rate_type: SALES TAX jurisdiction_name: California fee_amount: 0 note: Standard consumer sale quantity: 1 tax_amount: 1000 amount_excluding_tax: 10000 amount_including_tax: 11000 tax_included_in_amount: false total_tax_amount: 1000 total_amount_excluding_tax: 10000 total_amount_including_tax: 11000 expires_at: 1726683511 testmode: true address_resolution_status: EXACT address_used: address_line_1: 4 Privet Drive address_city: Little Whinging address_province: CA address_postal_code: '90210' address_country: US 2025-05-12-business: summary: >- Business customer calculation response (API version 2025-05-12) value: id: calc_1726683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9 object: tax.calculation customer_currency_code: EUR customer: type: BUSINESS automatic_tax: auto line_items: - product: reference_product_name: Business Software License reference_product_id: business_software_license product_tax_code: SOFTWARE tax_jurisdictions: - tax_rate: 0 rate_type: REVERSE CHARGE jurisdiction_name: Cross-border B2B fee_amount: 0 note: >- Cross-border B2B sale to VAT-registered business, reverse charge applies quantity: 5 tax_amount: 0 amount_excluding_tax: 250000 amount_including_tax: 250000 tax_included_in_amount: false total_tax_amount: 0 total_amount_excluding_tax: 250000 total_amount_including_tax: 250000 expires_at: 1726683511 testmode: true address_resolution_status: POSTAL_ONLY address_used: address_line_1: 123 Business St address_city: Commerce City address_province: NY address_postal_code: '10001' address_country: US '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/MissingOriginAddressError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ProductNotFoundError' components: schemas: CalculationRequestV202603: type: object properties: customer: $ref: '#/components/schemas/CustomerDetailsV202603' description: Customer details. At least one of address or ip must be provided. origin_address: $ref: '#/components/schemas/Address' description: >- Required from API version 2025-05-12+. The address that a product is shipped from. order_details: $ref: '#/components/schemas/OrderDetails' metadata: $ref: '#/components/schemas/Metadata' default_customer_type: type: string enum: - CONSUMER - BUSINESS description: >- 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. example: CONSUMER required: - customer - origin_address - order_details CalculationRequestV2025: type: object properties: customer: $ref: '#/components/schemas/CustomerDetailsV2025' description: >- Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions. origin_address: $ref: '#/components/schemas/Address' description: >- Required for API version 2025-05-12. The address that a product is shipped from. order_details: $ref: '#/components/schemas/OrderDetails' metadata: $ref: '#/components/schemas/Metadata' required: - customer - origin_address - order_details CalculationRequest: type: object properties: customer: $ref: '#/components/schemas/CustomerDetails' description: >- Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions. origin_address: $ref: '#/components/schemas/Address' description: >- Required from API version 2025-05-12+. The address that a product is shipped from. order_details: $ref: '#/components/schemas/OrderDetails' metadata: $ref: '#/components/schemas/Metadata' required: - customer - origin_address - order_details CalculationResponse: type: object properties: id: type: string description: >- The ID of the `calculation`. You will use this to create a `transaction`. example: calc_123456789 object: type: string description: 'The type of object: `tax.calculation`.' example: tax.calculation customer_currency_code: type: string description: The ISO-4217 currency code of the transaction. example: USD customer: type: object description: Customer information returned in the response. properties: type: type: string enum: - CONSUMER - BUSINESS description: >- The type of customer. `CONSUMER` are private individuals. `BUSINESS` are companies or legal entities registered for VAT/GST. example: CONSUMER automatic_tax: type: string enum: - auto - disabled description: The automatic tax setting for this calculation. example: auto line_items: type: array items: $ref: '#/components/schemas/TransactionLineItem' tax_included_in_amount: type: boolean example: false total_tax_amount: type: number description: Total tax to charge on this `calculation`. example: 14 total_amount_excluding_tax: type: number description: Total sale charge, excluding tax. example: 200 total_amount_including_tax: type: number description: Total sale charge plus tax. What you should charge your customer. example: 214 expires_at: type: number description: >- Epoch datetime representing the date and time the tax rates are valid until. example: 1714787673 testmode: type: boolean description: >- `True` if using a production API key. `False` if using a test API key. example: 'false' address_resolution_status: type: string enum: - EXACT - POSTAL_FALLBACK_1 - POSTAL_ONLY description: >- 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. example: EXACT address_used: type: object description: The actual address used for tax calculation after resolution. properties: address_line_1: type: string example: 4 Privet Drive address_line_2: type: string example: Unit 2 address_city: type: string example: Little Whinging address_province: type: string example: CA address_postal_code: type: string example: '90210' address_country: type: string example: US required: - address_line_1 - address_city - address_province - address_postal_code - address_country metadata: $ref: '#/components/schemas/Metadata' location_source: type: string enum: - address - ip description: Which input was used for tax determination. example: address resolution_precision: type: string enum: - STREET - POSTAL_PLUS - POSTAL - PROVINCE - COUNTRY - APPROXIMATED description: The precision level of the resolved location. example: POSTAL Error: type: object properties: error: type: object properties: error_code: type: string error_message: type: string error_meta: type: object properties: field: type: string expected: type: string received: type: string request_id: type: string description: The ID of the request example: req_123456789 example: error: error_code: missing_field error_message: Field is required error_meta: field: path.to.fieldname expected: string received: undefined MissingOriginAddressError: type: object properties: error: type: object properties: error_code: type: string error_message: type: string error_meta: type: object properties: field: type: string expected: type: string received: type: string example: error: error_code: missing_origin_address error_message: >- Origin address is required for API version 2025-05-12 but was not provided and no default origin address is configured. ProductNotFoundError: type: object properties: error: type: object properties: error_code: type: string error_message: type: string error_meta: type: object properties: field: type: string expected: type: string received: type: string example: error: error_code: error error_message: >- Unable to create calculation. Unable to find product {reference_product_id} in {environment} environment CustomerDetailsV202603: type: object properties: id: type: string description: >- 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). example: cus_123456789 type: type: string enum: - CONSUMER - BUSINESS description: >- The type of customer. `CONSUMER` are private individuals. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST. example: CONSUMER tax_ids: type: array description: >- Array of tax identification numbers. Only available for `BUSINESS` customer types. items: type: object properties: type: type: string description: >- Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types. example: us_ein value: type: string description: The tax ID value required: - type - value address: allOf: - $ref: '#/components/schemas/Address' - type: object properties: address_type: type: string description: >- The type of address. Must be one of: `shipping` or `billing`. Required if `ip` is not provided. example: shipping required: - address_type ip: type: object description: >- IP address for geo-based tax resolution. Required if `address` is not provided. properties: value: type: string description: A valid IPv4 or IPv6 address. example: 217.217.113.167 resolution: type: string enum: - strict - zero - approximate - best_effort default: strict description: >- 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. required: - value Address: type: object properties: address_line_1: type: string example: 3990 N County Rd 300 E address_line_2: type: string example: Unit 2 address_city: type: string example: Danville address_province: type: string description: >- The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code. example: IN address_postal_code: type: string example: '46122' address_country: type: string description: >- The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code. example: US required: - address_line_1 - address_city - address_province - address_postal_code - address_country OrderDetails: type: object properties: customer_currency_code: type: string description: >- 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. example: USD tax_included_in_amount: type: boolean description: >- 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. example: false automatic_tax: type: string enum: - auto - disabled description: >- 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. example: auto line_items: type: array description: >- 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. items: $ref: '#/components/schemas/LineItem' required: - customer_currency_code - tax_included_in_amount - line_items Metadata: type: object description: >- You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted. properties: example_key: type: string description: >- Storing things like an order number may be useful for reporting and reconciliation. example: example_value CustomerDetailsV2025: type: object properties: id: type: string description: >- 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). example: cus_123456789 type: type: string enum: - CONSUMER - BUSINESS description: >- 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. example: CONSUMER tax_ids: type: array description: >- Array of tax identification numbers. Available with API version 2025-05-12. Only available for `BUSINESS` customer types. items: type: object properties: type: type: string description: >- Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types. example: us_ein value: type: string description: The tax ID value required: - type - value address: allOf: - $ref: '#/components/schemas/Address' - type: object properties: address_type: type: string description: >- 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 example: shipping required: - address_type required: - address CustomerDetails: type: object properties: id: type: string description: >- 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). example: cus_123456789 address: allOf: - $ref: '#/components/schemas/Address' - type: object properties: address_type: type: string description: >- 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 example: shipping required: - address_type required: - address TransactionLineItem: type: object properties: product: type: object properties: reference_product_name: type: string example: Widget reference_line_item_id: type: string example: line_987654321 reference_product_id: type: string example: p-1233543 product_tax_code: type: string example: GENERAL_MERCHANDISE tax_jurisdictions: type: array items: type: object properties: tax_rate: description: The tax rate percentage applied to this transaction. type: number example: 0.07 tax_due_decimal: type: number description: >- Tax amount due for this jurisdiction in the currency's smallest unit. example: 700 rate_type: type: string description: Descriptive rate classification for this jurisdiction. example: GENERAL STATE SALES TAX fee_amount: description: >- 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 type: number example: 0 tax_authority_name: type: string description: Name of the tax authority. example: Tennessee tax_authority_type: type: string description: Type of tax authority (e.g., STATE, COUNTY, CITY, DISTRICT). example: '' tax_type: type: string description: 'Type of tax: SALES, USE, VAT, or GST.' example: SALES nullable: true quantity: type: number format: int32 example: 2 tax_amount: type: number format: int32 example: 14 amount_excluding_tax: type: number format: int32 example: 200 amount_including_tax: type: number format: int32 example: 214 LineItem: type: object properties: reference_line_item_id: type: string description: >- The ID of the line item from your system. This field is optional and will be primarily used for record keeping. example: line_123456789 reference_product_id: type: string description: >- The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no `product_category`. example: p-1233543 product_category: type: string description: >- A tax category from our [category taxonomy](/essentials/product-categories). Required if no `reference_product_id`. example: GENERAL_MERCHANDISE fallback_product_category: type: string description: >- 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. example: GENERAL_MERCHANDISE amount: type: number description: >- 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) example: 200 quantity: type: number description: >- The quantity of this product being sold. Primarily used for record keeping. example: 2 required: - quantity - amount securitySchemes: bearerAuth: type: http scheme: bearer ````