Skip to main content
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
Endpoints
Create a calculationPOST/tax/calculations

The Calculation object

Attributes

string
The ID of the calculation. Use it to create a transaction.
string, value is "tax.calculation"
String representing the object’s type.
string
ISO 4217 currency code of the calculation.
array of objects
One entry per line item in the request.
string
Numeral-generated ID for this line item.
object
Product information for this line item.
string
Echo of the reference_line_item_id you sent. Empty string when not sent.
string
The product ID in your system. default-<category> when the fallback product category was used.
string
The name of the product.
string
The tax code applied to this product.
array of objects
One row per taxing jurisdiction that applies to this line item.
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.
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.
string
Name of the jurisdiction: a state or county name in the US, the ISO country code for VAT countries (e.g. DE).
number
Any fixed fee for this jurisdiction.
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.
number
Tax for this line item, in the currency’s smallest unit.
number
Line amount before tax.
number
Line amount including tax.
number
Echo of the quantity you sent.
integer
Total tax to charge, in the currency’s smallest unit (rounded to an integer).
integer
Total excluding tax, in the currency’s smallest unit (rounded to an integer).
integer
Total including tax (rounded to an integer). What you charge your customer.
boolean
Echo of the request: whether line item amounts already include tax.
timestamp
Unix seconds when the quoted rates expire, 24 hours after creation.
boolean
true if made with a test API key.
object
Key-value pairs from the request, echoed unchanged. Only present when sent.
The Calculation object

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

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

object
required
Who is buying. The address is required.
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).
string
required
string
string
required
string
required
ISO 3166-2 subdivision code. For US and Canada, a valid uppercase USPS state code or Canadian province code.
string
required
Required for US and Canada.
string
required
ISO 3166-1 alpha-2 country code.
enum
required
shipping or billing. Use shipping for physical goods and billing for software and digital goods. Only valid on customer.address.
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.
object
required
The cart.
enum
required
ISO 4217 currency code. This version supports exactly 10: EUR, RON, PLN, DKK, HUF, CZK, BGN, SEK, USD, CAD. See supported currencies.
boolean
required
Whether line item amounts already include tax. Usually false for North American sales, but it varies by jurisdiction and business model.
array of objects
required
One entry per type of product. Each needs reference_product_id or product_category.
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.
integer
required
Quantity sold. Record keeping only in this version: it doesn’t change the taxable amount.
string
Tax category from the category list. Required if no reference_product_id.
string
Your product ID, as created in Numeral. Required if no 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.
string
Your line item ID, echoed back for record keeping.
object
The address the product ships from. Optional, but relevant for tax in some jurisdictions. Same fields as customer.address, without address_type.
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
Response
With fallback_product_category

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.
400