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
The response has the totals and a breakdown for each line item. Most integrations charge total_tax_amount and keep the details for when they need them.
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 when not 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.
number
Statutory rate for the jurisdiction, as a decimal fraction (0.07 = 7%), rounded to 6 decimal places. Some rates apply to only part of the amount, so don’t sum these. See Effective tax rate.
number
Unrounded tax due for this jurisdiction, in the currency’s smallest unit. Can be fractional. 0 for flat-fee jurisdictions; see fee_amount.
number
Fixed fee charged by this jurisdiction.
string
Name of the tax, e.g. GENERAL STATE SALES TAX or FOOD_AND_DRUG CITY LOCAL SALES TAX.
string
Taxing jurisdiction, e.g. Tennessee or DAVIDSON.
string
Type of authority, e.g. STATE, COUNTY, CITY, or DISTRICT. Often empty.
enum
SALES, USE, VAT, or GST.
integer
Tax for this line item, in the currency’s smallest unit.
integer
Line amount before tax (amount × quantity).
integer
amount_excluding_tax + tax_amount.
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.
integer
Total including tax. What you charge your customer.
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, after default_customer_type or invalid_tax_id_customer_fallback_type is applied.
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 customer address matched:
  • EXACT: exact street-level match.
  • POSTAL_FALLBACK_1: fell back to a postal code match.
  • POSTAL_ONLY: only the postal code was used.
object
The address the tax was calculated for, after resolution.
string
string
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

Effective tax rate

This version has no effective tax rate field. Don’t add up the tax_rate values to get one. Each is the statutory rate for its jurisdiction, and in some jurisdictions a rate applies to only part of the line amount.
  • Always charge the returned tax_amount or total_tax_amount.
  • For a line’s effective rate, divide its tax_amount by its amount_excluding_tax. For the whole order, divide total_tax_amount by total_amount_excluding_tax.
  • tax_due_decimal shows how much each jurisdiction actually contributed.
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 applies only to the part between $1,600 and $3,200. For the $10,000 Nashville item on the right, the four tax_rate values sum to 12.25%, but tax_amount is $788.00: an effective rate of 78800 / 1000000 = 7.88%.
Tennessee single article

Create a calculation

Quotes tax for a cart. Send X-API-Version: 2026-03-01 on every request. Accounts with no default version configured fall back to 2024-09-01, not this version. Try it in the API reference.
amount on line items is the per-unit price. The taxable base is amount × quantity. Before 2026-01-01, amount was the line total. For 3 items at $25.00 each, send "amount": 2500, "quantity": 3 (before 2026-01-01: "amount": 7500, "quantity": 3).

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 first and the IP is the fallback for address problems.
string
string
string
string
ISO 3166-2 subdivision code. Required for US and Canadian addresses, along with address_postal_code. Always send it: if it’s missing on a US address, Numeral tries to infer the state from a valid 5-digit ZIP, and an unrecognized ZIP returns MALFORMED_ADDRESS.
string
string
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.
object
New in 2026-03-01. 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 to track the customer or apply their tax exemption.
enum
default:"CONSUMER"
CONSUMER (individuals not registered for VAT/GST) or BUSINESS (entities registered for VAT/GST).
array of objects
Required when type is BUSINESS and the address is outside the US (not enforced for IP-only requests). Not allowed for CONSUMER. Each has type, a Stripe-style tax ID type (e.g. us_ein, eu_vat, gb_vat, au_abn, ca_bn, jp_cn), 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 have an active registration. 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 (2000 = $20.00). 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. See Products. 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 creating the product first. Must be a valid category. 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
New in 2026-03-01. When the sale happened, Unix seconds (not milliseconds). Rates, rules such as sales tax holidays, and other time-dependent inputs such as out-of-state-seller status are evaluated as of this time. Defaults to now.
enum
New in 2026-03-01. CONSUMER or BUSINESS. Used when customer.id isn’t found in Numeral, instead of returning a 400. It drives exemption logic and business tax ID validation as if it were customer.type. 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 business tax ID validation fails, instead of returning a 400.
object
String key-value pairs, echoed back in the response. Up to 50 keys; keys and values up to 255 characters. Non-string values are rejected.

Returns

A Calculation object.
Response

IP-based tax resolution

New in 2026-03-01. Send customer.ip instead of (or with) customer.address when you don’t have a full address. Numeral resolves the IP to a taxable location. With both, the address is used first and the IP is the fallback.
Numeral strongly recommends strict mode to stay as compliant as possible.
The response shows how the location was found: location_source is ip, resolution_precision shows how far the IP resolved, and address_used is the resolved address.IP resolution errors happen only in strict mode. To get a zero-rate response instead of an error, use best_effort or zero.

Changes from earlier versions

If you’re upgrading, these are the request and response changes that carry into 2026-03-01.New in 2026-03-01
  • customer.ip for IP-based tax resolution, with location_source and resolution_precision in the response.
  • transacted_at and default_customer_type.
From 2026-01-01
  • amount is the per-unit price. Taxable base is amount × quantity.
  • tax_jurisdictions rows have tax_due_decimal, tax_authority_name, tax_authority_type, tax_type, and descriptive rate_type values. jurisdiction_name and note are no longer returned.
  • origin_address sets the ship-from location for origin-based jurisdictions.
  • address_resolution_status and address_used show how the address was resolved.
  • Tax ID types expanded from VAT and GST to 439+ Stripe-style types, such as us_ein, eu_vat, gb_vat, au_abn, ca_bn, jp_cn, in_gst, and br_cnpj.
  • Errors use a flat format, replacing the nested { "error": { "code", "message" } } format.
From 2025-05-12
  • origin_address is required unless a default origin is set for the destination on your account.
  • order_details.automatic_tax is required, and must be auto for US addresses.
Error format (2026-01-01 and later)

Errors

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