Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-26286592.7 KB

Get tax information for a given product and address or IP

post/tax/calculations

Headers

X-API-Version'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.

Request body

transacted_atinteger

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.

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.

invalid_tax_id_customer_fallback_type'CONSUMER'

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.

Example request

{
  "customer": {
    "id": "cust_123456789",
    "type": "CONSUMER",
    "tax_ids": [
      {
        "type": "us_ein",
        "value": "12-3456789"
      }
    ],
    "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",
      "address_type": "shipping"
    },
    "ip": {
      "value": "217.217.113.167"
    }
  },
  "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",
    "automatic_tax": "auto",
    "line_items": [
      {
        "reference_line_item_id": "line_123456789",
        "reference_product_id": "p-1233543",
        "product_category": "GENERAL_MERCHANDISE",
        "fallback_product_category": "GENERAL_MERCHANDISE",
        "amount": 2000,
        "quantity": 1
      }
    ]
  },
  "metadata": {
    "example_key": "example_value"
  },
  "transacted_at": 1772323200,
  "default_customer_type": "CONSUMER",
  "invalid_tax_id_customer_fallback_type": "CONSUMER"
}

Response

Calculate response

idstring

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

objectstring

The type of object: tax.calculation.

customer_currency_codestring

The ISO-4217 currency code of the transaction.

automatic_tax'auto' | 'disabled'

The automatic tax setting for this calculation.

tax_included_in_amountboolean
total_tax_amountinteger

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

total_amount_excluding_taxinteger

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

total_amount_including_taxinteger

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

expires_atinteger

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

testmodeboolean

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.

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.

Example response

{
  "id": "calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "customer": {
    "type": "CONSUMER",
    "tax_ids": [
      {
        "type": "us_ein",
        "value": "12-3456789"
      }
    ]
  },
  "automatic_tax": "auto",
  "line_items": [
    {
      "product": {
        "reference_product_name": "Widget",
        "reference_line_item_id": "line_987654321",
        "reference_product_id": "p-1233543",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.07,
          "tax_due_decimal": 700,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_type": "SALES"
        }
      ],
      "quantity": 2,
      "tax_amount": 14,
      "amount_excluding_tax": 200,
      "amount_including_tax": 214
    }
  ],
  "total_tax_amount": 140,
  "total_amount_excluding_tax": 2000,
  "total_amount_including_tax": 2140,
  "expires_at": 1714787673,
  "address_resolution_status": "EXACT",
  "address_used": {
    "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"
  },
  "metadata": {
    "example_key": "example_value"
  },
  "location_source": "address",
  "resolution_precision": "POSTAL"
}