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 and keep the breakdown for their records.
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 when not sent.
​
string
The product ID in your system. When the line fell back to fallback_product_category, a default product such as default-general-merchandise.
​
string
The name of the product.
​
string
The product category used to decide taxability.
​
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
Type of rate: sales_tax for US Streamlined Sales Tax (SST) states, general state sales tax / general county local sales tax for other US states, standard for VAT countries. Zero-rate placeholder rows, e.g. when automatic_tax is disabled, 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. Zero-tax placeholder rows carry a reason instead, e.g. automatic_tax_disabled, or no_collection_exempt_customer for a tax-exempt customer.
​
number
Tax for this line item, in the currency’s smallest unit.
​
number
Line amount excluding 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.
​
enum
auto or disabled. Echo of the request.
​
object
The customer as used for the calculation.
​
enum
CONSUMER (private individuals) or BUSINESS (companies or legal entities registered for VAT/GST).
​
array of objects
Echo of the tax_ids you sent, when present. Each has type (VAT, GST, or EIN) and value.
​
enum
How the customer address was resolved: EXACT (exact address match), POSTAL_FALLBACK_1 (fell back to the postal code), or POSTAL_ONLY (only the postal code was used).
​
object
The address the tax was calculated for, after resolution.
​
string
​
string
Only present when there is one.
​
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. Only present when sent.
The Calculation object

​
Effective tax rate

Each tax_rate is the statutory rate for its jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount, so adding up tax_rate values can overstate the tax.
  • 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 portion 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 carry a note other than RATE_FRAC, such as PROGRESSIVE_RATE.
  • There’s no effective rate field in this version. For a line, compute tax_amount / amount_excluding_tax.
Always charge the returned tax_amount (or total_tax_amount).

​
Create a calculation

Quotes tax for a cart. Send X-API-Version: 2025-05-12 on every request; without it, requests fall back to 2024-09-01 unless your account has a default version set. Try it in the API reference.
In this version, line item amount is the total for the line, not the per-unit price. quantity doesn’t multiply it.

​
Parameters

​
object
required
Who is buying. customer.address is required.
​
object
required
Destination address. This version supports 82 destination countries: US, Canada, the EU member states, and more (full list in the API reference).
​
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 for physical goods, billing for software and digital goods. Only valid on customer.address.
​
string
The customer’s id or your reference_customer_id, for a customer you created in Numeral. Used for record keeping and tax exemptions.
​
enum
default:"CONSUMER"
CONSUMER for private individuals not registered for VAT/GST. BUSINESS for companies, sole proprietors, or other legal entities registered for VAT/GST. See Business customers and tax IDs.
​
array of objects
Required when type is BUSINESS and the address is outside the US. Not allowed for CONSUMER. Each has type (VAT, GST, or EIN) and value, both required.
​
boolean
default:"false"
Skip format and registry checks on tax_ids.
​
object
required
The cart.
​
string
required
ISO 4217 currency code. This version supports 126 currencies. 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. See Automatic tax.
​
array of objects
required
One entry per 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 (2000 = $20.00 in USD, ¥2000 in JPY). Tax is calculated on this value as is.
​
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. Must be a valid 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
Ship-from address. Required unless a default origin address is set for the destination jurisdiction on your account; without either, the request returns a 400. Same fields as customer.address, without address_type.
​
object
Up to 50 keys, each up to 255 characters. Values must be strings of up to 255 characters.

​
Returns

A Calculation object.
POST /tax/calculations
Response

​
Business customers and tax IDs

customer.type switches on business-to-business (B2B) tax logic.
  • CONSUMER (default): standard business-to-consumer tax. tax_ids aren’t allowed.
  • BUSINESS: send valid tax_ids (not needed for US addresses). This enables B2B exemptions and reverse charge where they apply.
Tax IDs are validated in real time, unless you send skip_tax_id_validation: true:
  • VAT IDs are checked against the EU VIES database.
  • GST IDs are validated for the countries where they apply.
  • An invalid tax ID returns an error.
This version accepts only the VAT, GST, and EIN tax ID types.
Business request
Business response

​
Automatic tax

order_details.automatic_tax controls whether tax is collected. Neither setting registers you anywhere.With disabled, line items get zero-rate placeholder rows with rate_type: "VAT" and note: "automatic_tax_disabled".

​
Errors

Errors return an error object with error_code, error_message, and sometimes error_meta (details such as the offending field and the expected and received types). Handle them by error_code. The request ID is in the X-Request-Id response header.Also returned:
  • 400 when there’s no origin_address and no default origin address for the destination.
  • 400 when fallback_product_category isn’t a valid category.
  • 404 when reference_product_id doesn’t exist and no fallback_product_category was sent.
400