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.
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, in the same order.
​
string
Numeral-generated ID for this line item. Use it to reference the line in refunds.
​
object
Product information for this line item.
​
string
Echo of the reference_line_item_id you sent.
​
string
The product ID in your system. default-<category> when the line was sent with product_category.
​
string
The name of the product.
​
string
The product category used to decide taxability.
​
array of objects
One row per taxing jurisdiction. Empty when no tax applies, for example in states with no sales tax.
​
number
Statutory rate for the jurisdiction, as a decimal fraction (0.0625 = 6.25%). Doesn’t include flat fees. Some rates apply to only part of the amount, so don’t sum these; use effective_tax_rate.
​
number
Unrounded tax due for this jurisdiction, in the currency’s smallest unit.
​
number
Flat fee charged by this jurisdiction, in the currency’s smallest unit. 0 on rate-based rows.
​
string
Name of the tax, e.g. GENERAL STATE SALES TAX.
​
string
Taxing jurisdiction, e.g. Illinois or Cook County.
​
string
Type of authority. Often empty; Country on some international rows.
​
enum
SALES, USE, VAT, GST, or PST.
​
string
New in 2026-11-01. Why this row came out the way it did. Empty string for normally calculated tax. See Notes for every value.
​
integer
Tax for this line item, in the currency’s smallest unit.
​
integer
Line amount before tax (amount × quantity). When tax_included_in_amount is true, the tax is backed out of the amount you sent.
​
integer
amount_excluding_tax + tax_amount.
​
number
Echo of the quantity you sent.
​
integer
Total tax to charge, in the currency’s smallest unit.
​
integer
Total excluding tax, in the currency’s smallest unit.
​
integer
Total including tax. What you charge your customer.
​
number
New in 2026-11-01. total_tax_amount / total_amount_excluding_tax, as a decimal fraction (0.105 = 10.5%). Includes flat fees. See Effective tax rate.
​
boolean
Echo of the request: whether line item amounts already include tax.
​
enum
auto or disabled. Echo of the request.
​
object
The customer as used for the calculation.
​
enum
CONSUMER or BUSINESS. The type actually used, which can fall back to CONSUMER when a business tax ID fails validation.
​
array of objects
Echo of the tax_ids you sent, when present. Each has type (e.g. eu_vat) and value.
​
enum
How precisely the address matched: EXACT, POSTAL_FALLBACK_1, or POSTAL_ONLY.
​
object
The address the tax was calculated for.
​
string
​
string
Only present when there is one.
​
string
​
string
ISO 3166-2 subdivision code.
​
string
​
string
ISO 3166-1 alpha-2 country code.
​
enum
address or ip: which input set the location.
​
enum
STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, or APPROXIMATED.
​
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

​
Notes

Every tax_jurisdictions row has a note. It’s an empty string when tax was calculated normally. Otherwise it tells you why the row came out the way it did, so a 0 is never a mystery.
  • All rows on one line item share the same note. Different line items can have different notes, for example a UK order’s goods line ("") and shipping line (shipping_follows_highest_taxed_item).
  • A line item with no rows (tax_jurisdictions: []) has no note.
  • Test API keys skip registration checks by default, so no_collection_no_state_nexus, no_collection_no_vat_registration, no_collection_no_gst_registration and collection_manually_deactivated normally show up only on live calls.
  • Records created before this version was released may return an empty note.

​
Effective tax rate

effective_tax_rate is the whole order’s tax as one rate:
  • Both amounts are the rounded totals in the same response.
  • Decimal fraction (0.077407 = 7.7407%), up to 6 decimal places, rounded half-up.
  • Includes flat fees, such as Minnesota’s retail delivery fee. Row tax_rate values don’t, so effective_tax_rate can be higher than their sum.
  • Can be lower than the sum of row rates when a rate applies to only part of the amount. Tennessee’s single article rules are the common case.
  • With tax_included_in_amount: true, the denominator is the amount with tax backed out: €119.00 including 19% VAT gives 1900 / 10000 = 0.19.
  • 0 when no tax applies, including exempt customers, automatic_tax: "disabled", and zero-rate IP responses.
  • There’s no per-line rate field. For one line, divide its tax_amount by its amount_excluding_tax.
Always charge total_tax_amount. Use effective_tax_rate for display and reporting.
The Tennessee rows sum to 12%, but local tax applies only to the first $1,600 and the 2.75% single article tax only to the $1,600–$3,200 band, so $10,800 is taxed $836.

​
Create a calculation

Quotes tax for a cart. Send X-API-Version on every request. Try it in the API reference.

​
Parameters

​
object
required
Who is buying. At least one of customer.address or customer.ip is required.
​
object
Destination address. Optional when ip is sent; with both, the address is used and the IP is the fallback.
​
string
​
string
​
string
​
string
ISO 3166-2 subdivision code. Always send it for US addresses.
​
string
​
string
ISO 3166-1 alpha-2 country code.
​
enum
shipping or billing. Only valid on customer.address.
​
object
IP address for location lookup when you don’t have a full address. See IP-based tax resolution.
​
string
required
A valid IPv4 or IPv6 address.
​
enum
default:"strict"
What to do when the IP can’t be resolved precisely enough: strict, zero, approximate, or best_effort.
​
string
ID of a customer you created in Numeral. Used for exemptions.
​
enum
default:"CONSUMER"
CONSUMER or BUSINESS.
​
array of objects
Required when type is BUSINESS and the address is outside the US. Not allowed for CONSUMER. Each has type (e.g. eu_vat, gb_vat, au_abn) and value. See tax IDs.
​
boolean
default:"false"
Skip format and registry checks on tax_ids.
​
object
required
The cart.
​
string
required
ISO 4217 currency code. See supported currencies.
​
boolean
required
Whether line item amounts already include tax. Usually false in North America.
​
enum
required
auto returns real rates where you’re registered. disabled always returns 0. Must be auto for US addresses.
​
array of objects
required
One entry per product. Each needs reference_product_id or product_category.
​
integer
required
Per-unit price in the currency’s smallest unit. Taxable base is amount × quantity.
​
integer
required
Quantity sold.
​
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. If the product is found, its stored category wins.
​
string
Your line item ID, echoed back for record keeping.
​
object
Ship-from address, used for origin-based sourcing. Required unless a default origin is set for the destination on your account. Same fields as customer.address, without address_type.
​
integer
When the sale happened, Unix seconds. Rates and rules, such as sales tax holidays, are evaluated as of this time. Defaults to now.
​
enum
CONSUMER or BUSINESS. Used when customer.id isn’t found in Numeral, instead of returning an error. If the customer is found, its stored type wins. BUSINESS on a non-US address still needs customer.tax_ids.
​
enum
CONSUMER. Treat the customer as a consumer when tax ID validation fails, instead of returning a 400.
​
object
String key-value pairs (values up to 255 characters), echoed back in the response.

​
Returns

A Calculation object.
POST /tax/calculations
Response

​
IP-based tax resolution

Send customer.ip instead of (or with) customer.address when you don’t have a full address, for example for digital goods. With both, the address is used and the IP is the fallback.
Numeral strongly recommends strict mode to stay as compliant as possible.
A zero-rate response has tax_jurisdictions: [] on every line (so no note), empty product fields, and effective_tax_rate: 0. location_source is ip, and resolution_precision shows how far the IP resolved.
IP request
Zero-rate response

​
Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.