Create Calculations

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_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
      }
    ]
  }
}
'

{
  "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"
  }
}

POST

tax

calculations

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_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
      }
    ]
  }
}
'

{
  "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"
  }
}

Get tax information for a given product and address

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. Jurisdictions whose rate applies to only part of the amount carry a note value other than RATE_FRAC, such as PROGRESSIVE_RATE.

cURL Header Example

Include all request headers explicitly:

curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2024-09-01' \
  --data '{ ... }'

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>

required

API version to use.

Available options:

2026-03-01,

2026-01-01,

2025-05-12,

2024-09-01

Body

application/json

API Version 2026-03-01
API Version 2026-01-01
API Version 2025-05-12
API Version 2024-09-01

customer

object

required

Customer details. At least one of address or ip must be provided.

Show child attributes

origin_address

object

required

Required from API version 2025-05-12+. The address that a product is shipped from.

Show child attributes

order_details

object

required

Show child attributes

metadata

object

You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.

Show child attributes

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"

Response

Calculate response

string

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

Example:

"calc_123456789"

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.

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

number

Total tax to charge on this calculation.

Example:

14

total_amount_excluding_tax

number

Total sale charge, excluding tax.

Example:

200

total_amount_including_tax

number

Total sale charge plus tax. What you should charge your customer.

Example:

214

expires_at

number

Epoch datetime representing the date and time the tax rates are valid until.

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. Any valid JSON object whose values are less than 255 characters long is accepted.

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"

Getting Started

API Reference

cURL Header Example

Authorizations

Headers

Body

Response