Create Calculations

Get tax information for a given product and address or IP

POST /tax/calculations

cURL

address_based

curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <x-api-version>' \
  --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": 10000,
        "product_category": "BEVERAGES",
        "quantity": 1
      },
      {
        "amount": 10000,
        "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"
  }
}
'

200

address_based

{
  "testmode": true,
  "id": "calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f",
      "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.07,
          "tax_due_decimal": 700,
          "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": 225,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "DAVIDSON",
          "tax_authority_type": "",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 925,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10925,
      "quantity": 1
    },
    {
      "line_item_id": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f80",
      "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.07,
          "tax_due_decimal": 700,
          "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": 225,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "DAVIDSON",
          "tax_authority_type": "",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 925,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10925,
      "quantity": 1
    }
  ],
  "total_tax_amount": 1850,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 20000,
  "total_amount_including_tax": 21850,
  "expires_at": 1783456061,
  "metadata": {
    "payment_id": "68407cb7-e1fa-47fa-8244-bd9411d53c61"
  },
  "customer": {
    "type": "CONSUMER"
  },
  "automatic_tax": "auto",
  "address_resolution_status": "EXACT",
  "address_used": {
    "address_line_1": "123 Broadway",
    "address_city": "Nashville",
    "address_province": "TN",
    "address_postal_code": "37203",
    "address_country": "US"
  },
  "location_source": "address",
  "resolution_precision": "STREET"
}

Get tax information for a given product and address or IP.

Required from 2025-05-12+:

• The origin_address field is required for all calculations starting from API version 2025-05-12, unless a default origin address is configured for the destination jurisdiction on your account.
• The automatic_tax field in order_details is required starting from API version 2025-05-12 (and must be "auto" for US addresses). Use "auto" to enable automatic tax calculation or "disabled" to return zero tax rates.

Note: The address_type field is only valid on customer.address — including it on origin_address returns a 400 UNRECOGNIZED_FIELD error.

cURL Header Example

Use X-API-Version explicitly in requests:

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 '{ ... }'

New in 2026-03-01:

• You can now provide customer.ip instead of (or in addition to) customer.address for IP-based tax resolution.
• Optional transacted_at (Unix timestamp in seconds): evaluate time-dependent inputs (e.g., out-of-state-seller status, rates) as of the sale time instead of now.
• Optional default_customer_type: fallback customer type when customer.id doesn’t exist in Numeral yet.
• US ZIP-to-state fallback: address_province is still required and should always be sent, but if it is missing or empty on a US address, Thomas attempts to infer the state from a valid 5-digit ZIP (an unrecognized ZIP returns a 400 MALFORMED_ADDRESS).

Inherited from 2026-01-01: The amount field on line items is per-unit price (taxable base = amount x quantity). Responses include address_resolution_status, address_used, and enhanced tax_jurisdictions fields (tax_authority_name, tax_authority_type, tax_type, tax_due_decimal).

Caution about simply summing tax_rate values. Each tax_rate in tax_jurisdictions is the statutory rate for that jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount. Tennessee’s single article rules are the common example: local rates apply only to the first $1,600 of an item, and the 2.75% state single article rate applies only to the portion between $1,600 and $3,200. For a $10,000 item the returned rates sum to 12.25%, but the tax due is $788, an effective rate of 7.88%.

Always charge the returned tax_amount (or total_tax_amount). If you need an effective rate, compute tax_amount / amount_excluding_tax from the response rather than adding up tax_rate values. The per-jurisdiction tax_due_decimal field shows how much each jurisdiction actually contributed.

IP-Based Resolution

Instead of providing a full customer address, you can pass an IP address and we’ll resolve it to a taxable location:

{
  "customer": {
    "type": "CONSUMER",
    "ip": {
      "value": "217.217.113.167",
      "resolution": "strict"
    }
  }
}

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

Mode	Behavior
strict (default)	Error if IP cannot resolve to sufficient detail for tax calculation
zero	Return zero-rate response if resolution is insufficient
approximate	Attempts to resolve the IP to an address using heuristics
best_effort	Try approximate first, fall back to zero rates

Numeral strongly recommends using strict mode to stay as compliant as possible.

New Response Fields

Field	Description
location_source	"address" or "ip" — which input was used
resolution_precision	STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, or APPROXIMATED
address_used	The resolved address used for tax calculation

IP Resolution Errors

Error Type	HTTP Code	Description
INVALID_IP_FORMAT	400	ip.value is not a valid IPv4 or IPv6 address
IP_RESOLUTION_FAILED	422	IP could not be resolved to any country
IP_RESOLUTION_INSUFFICIENT_US	422	IP resolved to a US state but no postal code could be determined
IP_RESOLUTION_INSUFFICIENT_CA	422	IP resolved to Canada but no province could be determined

Error Codes Reference

See the complete list of error types and their meanings.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version · enum<string> · default: 2026-03-01 · required

The API version for this request. Always set a version: pass this header explicitly (recommended), or configure a default API version on your account and omit the header. Accounts with no configured version fall back to 2024-09-01, NOT this version.

Available options: 2026-03-01

Body

application/json

customer · object · required

Customer details. At least one of customer.address or customer.ip must be provided. Optionally accepts a customer ID for order tracking and exemptions.

Show child attributes

order_details · object · required

Show child attributes

origin_address · object

The address that a product is shipped from. Required at calculation time unless a default origin address is configured for the destination jurisdiction on your account — omitting it with no default configured returns a 400.

Show child attributes

metadata · object

You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).

Show child attributes

transacted_at · integer

Optional. The time the transaction occurred, as a Unix timestamp in seconds (not milliseconds). Used to determine which tax rates and rules apply at the time of the transaction (for example, during sales tax holidays), as well as other time-dependent inputs such as out-of-state-seller status. If omitted, the calculation uses the current time. Available in API version 2026-03-01 and later.

Example:

1772323200

default_customer_type · enum<string>

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.

Available options: CONSUMER, BUSINESS

Example:

"CONSUMER"

invalid_tax_id_customer_fallback_type · enum<string>

Optional. When business tax ID validation fails, fall back to treating the customer as this type instead of returning a 400. CONSUMER is the only accepted value. Available in API version 2026-01-01 and later.

Available options: CONSUMER

Example:

"CONSUMER"

Response

200

application/json

Calculate response

id · string

The ID of the calculation. You will use this to create a transaction.

Example:

"calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3"

object · string

The type of object: tax.calculation.

Example:

"tax.calculation"

customer_currency_code · string

The ISO-4217 currency code of the transaction.

Example:

"USD"

customer · object

Customer information returned in the response. type reflects the effective customer type used for the calculation (e.g., after default_customer_type or invalid_tax_id_customer_fallback_type is applied).

Show child attributes

automatic_tax · enum<string>

The automatic tax setting for this calculation.

Available options: auto, disabled

Example:

"auto"

line_items · object[]

Show child attributes

tax_included_in_amount · boolean

Example:

false

total_tax_amount · integer

Total tax to charge on this calculation, in the currency's smallest unit (rounded to an integer).

Example:

140

total_amount_excluding_tax · integer

Total sale charge excluding tax, in the currency's smallest unit (rounded to an integer).

Example:

2000

total_amount_including_tax · integer

Total sale charge plus tax, in the currency's smallest unit (rounded to an integer). What you should charge your customer.

Example:

2140

expires_at · integer

Unix timestamp in seconds at which the quoted tax rates expire — 24 hours after the calculation is created.

Example:

1714787673

testmode · boolean

True if using a production API key. False if using a test API key.

Example:

false

address_resolution_status · enum<string>

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.

Available options: EXACT, POSTAL_FALLBACK_1, POSTAL_ONLY

Example:

"EXACT"

address_used · object

The actual address used for tax calculation after resolution.

Show child attributes

metadata · object

You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).

Show child attributes

location_source · enum<string>

Which input was used for tax determination.

Available options: address, ip

Example:

"address"

resolution_precision · enum<string>

The precision level of the resolved location.

Available options: STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, APPROXIMATED

Example:

"POSTAL"