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