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 totals and a breakdown for each line item. Most integrations charge total_tax_amount; 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.
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 Summing tax rates.
number
Unrounded tax due for this jurisdiction, in the currency’s smallest unit. Can be fractional. 0 on flat-fee rows: see fee_amount.
number
Fixed fee charged by this jurisdiction.
string
Descriptive rate classification, e.g. GENERAL STATE SALES TAX or FOOD_AND_DRUG CITY LOCAL SALES TAX.
string
Name of the tax authority, e.g. Tennessee or ALLEGHENY.
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, 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.
enum
auto or disabled. Echo of the request.
object
The customer as used for the calculation.
enum
CONSUMER or BUSINESS. The type actually used, for example CONSUMER after 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 address matched:
  • EXACT: exact street-level match.
  • POSTAL_FALLBACK_1: fell back to a postal-code-level match.
  • POSTAL_ONLY: only the postal code was used.
object
The address actually used for the calculation, after resolution.
string
string
string
string
ISO 3166-2 subdivision code.
string
string
ISO 3166-1 alpha-2 country code.
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.
tax_jurisdictions rows have no jurisdiction_name or note in this version. Both were in versions before 2026-01-01.
The Calculation object

Summing tax rates

Don’t add up tax_rate values to get a rate. Each one is the statutory rate for its jurisdiction, and some apply to only part of the line amount.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. The second line item in the example is a $10,000 Nashville item: its four rates sum to 12.25%, but its tax_amount is $788.00, an effective rate of 7.88%.
  • Always charge the returned tax_amount or total_tax_amount.
  • For an effective rate, divide tax_amount by amount_excluding_tax.
  • tax_due_decimal shows how much each jurisdiction actually contributed.
Tennessee single article

Create a calculation

Quotes tax for a cart. Send X-API-Version: 2026-01-01 on every request. Try it in the API reference.
Breaking change: from 2026-01-01, a line item’s amount is the per-unit price. The taxable base is amount × quantity.

Parameters

object
required
Who is buying.
object
required
Destination address. Supports US, Canada, the EU member states, and many other countries. See the API reference for the full list of 82.
string
required
string
string
required
string
required
ISO 3166-2 subdivision code. For US and Canada, a valid uppercase state or province code.
string
required
Always required for US and Canadian addresses.
string
required
ISO 3166-1 alpha-2 country code.
enum
required
shipping for physical goods, billing for software and digital goods. Only valid on customer.address.
string
ID of a customer you created in Numeral. Used to log customer information or to mark the purchase tax exempt.
enum
default:"CONSUMER"
  • CONSUMER: a private individual not registered for VAT/GST. Standard B2C tax.
  • BUSINESS: a company or other legal entity registered for VAT/GST. Needs tax_ids for B2B tax logic.
array of objects
Required when type is BUSINESS and the address is outside the US. Not allowed for CONSUMER. Each has type and value. Types are Stripe-style and country-specific, 439+ in all, e.g. us_ein, eu_vat, gb_vat, au_abn, ca_bn, jp_cn, in_gst, br_cnpj. See tax IDs.
boolean
default:"false"
Skip format and registry checks on tax_ids.
object
required
The cart.
string
required
ISO 4217 currency code. 126 currencies are supported. See supported currencies.
boolean
required
Whether line item amounts already include tax. Usually false in North America.
enum
required
auto returns real rates everywhere 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 (e.g. cents for USD). Taxable base is amount × quantity.
integer
required
Quantity sold. At least 1.
string
Tax category from the category list. Required if no reference_product_id.
string
Your product ID, as created in Numeral as a product. 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; an invalid value returns a 400. If the product is found, its stored category wins.
string
Your line item ID, echoed back for record keeping.
object
Ship-from address, used where the seller’s location affects the rate (origin-based sourcing). Required unless a default origin address is set for the destination on your account. Same fields as customer.address, without address_type.
enum
CONSUMER. Treat the customer as a consumer when business tax ID validation fails, instead of returning a 400.
object
Your own key-value pairs, echoed back unchanged. At most 50 keys. Keys up to 255 characters. Values must be strings of up to 255 characters.

Returns

A Calculation object.
POST /tax/calculations
Response

Errors

Errors return code, type, and message. Handle them by type. This flat format replaces the nested error object of earlier versions. Full list in Error Codes.