Calculations

Quote the tax for a cart at checkout

A calculation quotes the tax for a cart. Create one at checkout after the customer enters an address and before you take payment. Use its id to record a transaction once the customer pays.

The response has the order’s totals and a breakdown for each line item. Most integrations charge total_tax_amount, and the details are there when you need them.

Where calculations fit in checkout

Checkout
├─ 1. Customer enters checkout
├─ 2. Customer enters address
│     └─ POST /tax/calculations
│          send:    products + address
│          receive: tax + calculation id
├─ 3. Tax added to the order total
└─ 4. Customer completes the purchase
      └─ POST /tax/transactions
           send:    calculation id
           receive: transaction id

Endpoints

Create a calculationPOST/tax/calculations

The Calculation object

Attributes

id · string

The ID of the calculation. Use it to create a transaction.

object · string, value is "tax.calculation"

String representing the object’s type.

customer_currency_code · string

ISO 4217 currency code of the calculation.

line_items · array of objects

One entry per line item in the request.

line_items[].line_item_id · string

Numeral-generated ID for this line item.

line_items[].product · object

Product information for this line item.

line_items[].product.reference_line_item_id · string

Echo of the reference_line_item_id you sent. Empty string when not sent.

line_items[].product.reference_product_id · string

The product ID in your system. default-<category> when the fallback product category was used.

line_items[].product.reference_product_name · string

The name of the product.

line_items[].product.product_tax_code · string

The tax code applied to this product.

line_items[].tax_jurisdictions · array of objects

One row per taxing jurisdiction that applies to this line item.

line_items[].tax_jurisdictions[].tax_rate · number

Statutory rate for the jurisdiction, as a decimal fraction (0.0725 = 7.25%). Some rates apply to only part of the amount, so don’t sum these; see Effective tax rate.

line_items[].tax_jurisdictions[].rate_type · string

The type of rate: sales_tax for US Streamlined Sales Tax (SST) states, general state sales tax or general county local sales tax for other US states, standard for VAT countries. Zero-rate placeholder rows use VAT.

line_items[].tax_jurisdictions[].jurisdiction_name · string

Name of the jurisdiction: a state or county name in the US, the ISO country code for VAT countries (e.g. DE).

line_items[].tax_jurisdictions[].fee_amount · number

Any fixed fee for this jurisdiction.

line_items[].tax_jurisdictions[].note · string

How the row was calculated, e.g. RATE_FRAC. A rate that applies to only part of the amount has another value, such as PROGRESSIVE_RATE. Zero-tax rows can carry a reason instead, e.g. no_collection_exempt_customer for a tax-exempt customer.

line_items[].tax_amount · number

Tax for this line item, in the currency’s smallest unit.

line_items[].amount_excluding_tax · number

Line amount before tax.

line_items[].amount_including_tax · number

Line amount including tax.

line_items[].quantity · number

Echo of the quantity you sent.

total_tax_amount · integer

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

total_amount_excluding_tax · integer

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

total_amount_including_tax · integer

Total including tax (rounded to an integer). What you charge your customer.

tax_included_in_amount · boolean

Echo of the request: whether line item amounts already include tax.

expires_at · timestamp

Unix seconds when the quoted rates expire, 24 hours after creation.

testmode · boolean

true if made with a test API key.

metadata · object

Key-value pairs from the request, echoed unchanged. Only present when sent.

The Calculation object

{
  "testmode": true,
  "id": "calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1783369478353396a9168-1972-4798-80cb-536d96c0cc5a",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "wand_elder_12",
        "reference_product_name": "Elder Wand",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0725,
          "rate_type": "general state sales tax",
          "jurisdiction_name": "California",
          "fee_amount": 0,
          "note": "RATE_FRAC"
        },
        {
          "tax_rate": 0.025,
          "rate_type": "general county local sales tax",
          "jurisdiction_name": "Los Angeles",
          "fee_amount": 0,
          "note": "RATE_FRAC"
        }
      ],
      "tax_amount": 975,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10975,
      "quantity": 1
    }
  ],
  "total_tax_amount": 975,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 10000,
  "total_amount_including_tax": 10975,
  "expires_at": 1783455878
}

Effective tax rate

Each tax_rate is the statutory rate for its jurisdiction, and some apply to only part of the line item amount, so don’t add them up to get the rate you charged.

• Tennessee’s single article rules are the common case: local rates apply only to the first $1,600 of an item, and the 2.75% state single article rate only to the part 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%.
• Rows whose rate applies to only part of the amount have a note other than RATE_FRAC, such as PROGRESSIVE_RATE.

There’s no effective rate field in this version. If you need one, work it out from the response as shown. Always charge the returned tax_amount or total_tax_amount.

Effective rate

effective rate = tax_amount / amount_excluding_tax

Tennessee, $10,000 item:
  sum of tax_rate values   12.25%
  tax due                  $788
  effective rate           788 / 10,000 = 7.88%

Create a calculation

Quotes tax for a cart. Try it in the API reference.

Always set an API version: send X-API-Version (recommended), or set a default version on your account. Requests with neither use 2024-09-01, but an account default set to a newer version takes precedence over that fallback.

Parameters

customer · object · required

Who is buying. The address is required.

customer.address · object · required

Destination address. address_country must be US, CA, or an EU member state (AT, BE, BG, HR, CZ, DE, DK, EE, FI, FR, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE).

customer.address.address_line_1 · string · required

customer.address.address_line_2 · string

customer.address.address_city · string · required

customer.address.address_province · string · required

ISO 3166-2 subdivision code. For US and Canada, a valid uppercase USPS state code or Canadian province code.

customer.address.address_postal_code · string · required

Required for US and Canada.

customer.address.address_country · string · required

ISO 3166-1 alpha-2 country code.

customer.address.address_type · enum · required

shipping or billing. Use shipping for physical goods and billing for software and digital goods. Only valid on customer.address.

customer.id · string

ID of a customer you created in Numeral: the Numeral id or your reference_customer_id. Used to log customer information or to apply a tax exemption.

order_details · object · required

The cart.

order_details.customer_currency_code · enum · required

ISO 4217 currency code. This version supports exactly 10: EUR, RON, PLN, DKK, HUF, CZK, BGN, SEK, USD, CAD. See supported currencies.

order_details.tax_included_in_amount · boolean · required

Whether line item amounts already include tax. Usually false for North American sales, but it varies by jurisdiction and business model.

order_details.line_items · array of objects · required

One entry per type of product. Each needs reference_product_id or product_category.

order_details.line_items[].amount · integer · required

Total price of the line (not per-unit) in the currency’s smallest unit, e.g. 2000 = $20.00 in USD. Tax is calculated on this value as-is. Per-unit pricing starts in API version 2026-01-01.

order_details.line_items[].quantity · integer · required

Quantity sold. Record keeping only in this version: it doesn’t change the taxable amount.

order_details.line_items[].product_category · string

Tax category from the category list. Required if no reference_product_id.

order_details.line_items[].reference_product_id · string

Your product ID, as created in Numeral. Required if no product_category.

order_details.line_items[].fallback_product_category · string

Used when reference_product_id isn’t found in Numeral, instead of returning an error. Lets you always send a product ID without first making sure the product exists. Must be a valid product category, or the request returns a 400. If the product is found, its stored category wins.

order_details.line_items[].reference_line_item_id · string

Your line item ID, echoed back for record keeping.

origin_address · object

The address the product ships from. Optional, but relevant for tax in some jurisdictions. Same fields as customer.address, without address_type.

metadata · object

Up to 50 key-value pairs, echoed back in the response. Keys and values up to 255 characters each. Values must be strings.

Returns

A Calculation object.

POST /tax/calculations

curl https://api.numeralhq.com/tax/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2024-09-01' \
  -d '{
    "customer": {
      "address": {
        "address_line_1": "4 Privet Drive",
        "address_city": "Little Whinging",
        "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
        }
      ]
    }
  }'

Response

{
  "id": "calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c",
  "object": "tax.calculation",
  "total_tax_amount": 975,
  "total_amount_excluding_tax": 10000,
  "total_amount_including_tax": 10975,
  "...": "see The Calculation object"
}

With fallback_product_category

{
  "line_items": [
    {
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "default-general-merchandise",
        "reference_product_name": "Default GENERAL_MERCHANDISE Product",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "...": "..."
    }
  ],
  "...": "..."
}

Errors

Errors in this version return an error object with error_code and error_message, and sometimes error_meta with details such as the offending field and the expected and received types. The request ID is in the X-Request-Id response header, not the body.

HTTP	error_code	When
400	missing_field	A required field is missing.
400	incorrect_type	A field has the wrong type.
400	unrecognized_field	An unknown field was sent, e.g. address_type on origin_address.
400	malformed_address	The address is invalid.
400	invalid_currency_code	customer_currency_code isn’t one of the 10 supported currencies.
400	—	fallback_product_category isn’t a valid product category.
404	—	reference_product_id isn’t found in Numeral and no fallback_product_category was sent.

400

{
  "error": {
    "error_code": "missing_field",
    "error_message": "Field is required"
  }
}