Skip to main content
POST
Calculate taxes for marketplace/platform transactions where a merchant (seller) is involved. This endpoint is designed for marketplaces, payment processors, and other platforms that facilitate transactions between buyers and sellers.
New in 2026-11-01:
  • Every tax_jurisdictions row in line_items and fee_line_items has a note that says why it came out the way it did.
  • totals.order.effective_tax_rate, and totals.fees.effective_tax_rate when fee_details is sent. Each is that bucket’s tax_amount / amount_excluding_tax. There’s no combined order-plus-fees rate.
The order and the fees are taxed separately, so their rows can come from different states. In the “With Fees” example below, the order is taxed where the customer is (Colorado) and the fee where the merchant is (California).

​
Headers

​
string
required
Bearer token authentication.
​
string
required
API version, e.g. 2026-11-01. Overrides your account’s default version for this request.

​
Request Body

​
object
required
The customer (buyer) information.
​
object
required
The merchant (seller) involved in this transaction.
​
object
required
Order details including line items.
​
array
required
Your role(s) in this transaction. One or more of:
  • marketplace_provider - You operate a marketplace connecting buyers and sellers
  • payment_processor - You process payments for the transaction
  • merchant_of_record - You are the legal seller of record
​
object
Optional: Details for platform fees to be taxed separately. Same structure as order_details, except automatic_tax only accepts auto or disabled — fees represent the platform’s own tax event toward the merchant and must honor the platform’s own nexus configuration.
​
integer
Optional. The time the transaction occurred, as a Unix timestamp in seconds. Used to determine which tax rates and rules apply at the time of the transaction (for example, during a sales tax holiday). If omitted, the calculation uses the current time.
​
string
Optional. CONSUMER or BUSINESS. Used when customer.id is provided but no matching customer exists in Numeral: the order is priced with this customer type instead of failing with customer_not_found. Lets you always pass a customer ID without first ensuring the customer has been created. If the customer is found, its exemptions apply as normal.

​
Line Item Properties

​
integer
required
Per-unit price in the smallest currency unit (e.g., cents for USD).For a $25.00 item: amount: 2500
​
integer
required
Number of units. The taxable base = amount × quantity.
​
string
Tax category code (e.g., GENERAL_MERCHANDISE, SAAS_GENERAL).
​
string
Reference to a pre-created product.
​
string
Your ID for this line item.

​
Response

​
string
The calculation ID.
​
string
Always tax.calculation.
​
array
Tax calculations for order line items.
​
array
Tax calculations for fee line items (only present when fee_details provided).
​
object
Summary totals for order and fees.
​
object
The merchant used in this calculation.
​
array
The roles you specified.

​
Enhanced Response Fields

Platform calculations include additional tax jurisdiction details:
​
string
Name of the tax authority (e.g., “California State”).
​
string
Type of authority: STATE, COUNTY, CITY, or DISTRICT.
​
string
Type of tax: SALES, USE, VAT, or GST.
​
string
New in 2026-11-01. Why the row came out the way it did. Empty string for normally calculated tax. See Notes for every value.

​
IP Resolution Response Fields

​
string
"address" or "ip" — indicates which input was used for tax determination.
​
string
Precision of the resolved location: STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, or APPROXIMATED.
​
object
The address actually used for tax calculation, populated even when using IP-based resolution.
Caution about simply summing tax_rate values. Each tax_rate in tax_jurisdictions is the statutory rate for that jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount. Tennessee’s single article rules are the common example: local rates apply only to the first $1,600 of an item, and the 2.75% state single article rate applies 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%.Always charge the returned tax_amount (or total_tax_amount). If you need an effective rate, compute tax_amount / amount_excluding_tax from the response rather than adding up tax_rate values. The per-jurisdiction tax_due_decimal field shows how much each jurisdiction actually contributed.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-API-Version
enum<string>
required

API version. Must be 2026-11-01 for platform calculations.

Available options:
2026-11-01

Body

application/json

Request body for platform/marketplace tax calculations

​
customer
object
required

Customer details. At least one of address or ip must be provided.

​
merchant
object
required

The merchant (seller) involved in this platform transaction

​
order_details
object
required
​
roles
enum<string>[]
required

Your role(s) in this transaction

Available options:
marketplace_provider,
payment_processor,
merchant_of_record
Example:
​
fee_details
object

Optional: Details for platform fees to be taxed separately

​
transacted_at
integer

Optional top-level field. The time the transaction occurred, as a Unix timestamp in seconds. Used to determine which tax rates and rules apply at the time of the transaction (for example, during sales tax holidays). If omitted, the calculation uses the current time. Available in API version 2026-03-01 and later.

Example:

1772323200

​
default_customer_type
enum<string>

Optional fallback customer type used when customer.id is provided but no matching customer exists in Numeral. Lets platforms always pass a customer ID without first ensuring the customer has been created. When the lookup misses, this value is used as the customer type for the order instead of failing with customer_not_found. If a matching customer is found, the customer's exemptions apply as normal.

Available options:
CONSUMER,
BUSINESS
Example:

"CONSUMER"

Response

Platform calculation response

​
id
string
Example:

"calc_platform_123456789"

​
object
string
Example:

"tax.calculation"

​
testmode
boolean
​
customer_currency_code
string
​
line_items
object[]
​
fee_line_items
object[]

Tax calculations for platform fees (only present when fee_details provided)

​
totals
object
​
merchant
object
​
roles
string[]
​
expires_at
number
​
location_source
enum<string>

Which input was used for tax determination.

Available options:
address,
ip
Example:

"address"

​
resolution_precision
enum<string>

The precision level of the resolved location.

Available options:
STREET,
POSTAL_PLUS,
POSTAL,
PROVINCE,
COUNTRY,
APPROXIMATED
Example:

"POSTAL"

​
address_used
object

The address actually used for tax calculation, populated even for IP-based requests.