Compute tax for an order

POST

/v1/portability/orders

• Production

Computes line-by-line tax for an order given ship-from, ship-to, line items, and shipping. Respects the calling account’s nexus profile (managed via /v1/portability/nexus); pass nexus_states in the body to override for a single call.

The response includes a per-line tax breakdown plus an order-level summary, with advisories under _categories.

Parameters

Header Parameters

X-API-Key

Any of:

string

string

null

null

Request Body ^required

OrderRequest

Compute total tax for an order with one or more line items.

Sourcing (which address the rate is resolved at) is derived from from_* (ship-from) and to_* (ship-to) plus the calling account’s nexus profile.

object

from_country

From Country

Ship-from ISO-3166 country code. Only US is supported today; international orders return HTTP 400.

string

default: US /^[A-Za-z]{2,3}$/

from_state

required

From State

Ship-from state. Two-letter USPS code preferred; full state name accepted and normalised.

string

>= 2 characters <= 40 characters

from_zip

required

From Zip

Ship-from postal code (5-digit or ZIP+4).

string

>= 5 characters <= 10 characters

from_city

Any of:

string

string

null

null

from_street

Any of:

string

string

null

null

to_country

To Country

Ship-to ISO-3166 country code. Only US supported.

string

default: US /^[A-Za-z]{2,3}$/

to_state

required

To State

Ship-to state. Two-letter USPS preferred; full name accepted.

string

>= 2 characters <= 40 characters

to_zip

required

To Zip

Ship-to postal code (5-digit or ZIP+4).

string

>= 5 characters <= 10 characters

to_city

Any of:

string

string

null

null

to_street

Any of:

string

string

null

null

shipping

Shipping

Shipping & handling charge for the order, in USD. Whether shipping is taxable depends on the destination state’s rules; the response includes freight_taxable: true|false.

number

0

line_items

Line Items

Line items in the order. May be empty for a zero-item (quote-only) order; the response then reports zero tax.

Array<object>

OrderLine

A single line item within an order. Quantity × unit_price is the pre-discount taxable subtotal for the line.

object

id

Id

Free-form line identifier (your own SKU, line number, etc). Echoed back in the per-line response so you can match each computed tax amount to its source line.

string

""

quantity

required

Quantity

Number of units of this product on the line. Must be ≥ 0.

integer

unit_price

required

Unit Price

Per-unit price in the order’s currency (USD). Pre-discount, pre-tax. Must be ≥ 0.

number

discount

Discount

Discount applied to this line, subtracted from (quantity × unit_price) before tax. Must be ≥ 0.

number

0

product_tax_code

Any of:

string

string

null

null

nexus_states

Any of:

Array<string>

Array<string>

null

null

Responses

200

Order computed. Returns line-by-line + summary tax breakdown.

Response Compute Order V1 Portability Orders Post

object

key

additional properties

any

400

Invalid input — non-US country, missing state, or malformed line items.

401

Missing or invalid API key.

404

Ship-to address could not be resolved.

422

Validation Error

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

429

Monthly quota exceeded.

503

Upstream temporarily unavailable; retry shortly.