ITMS API — Schemas

POST /api/v1/tax/calculate and POST /api/v1/transactions share one request shape; committed transactions add code and type.

Request fields

Field	Type	Required	Description
`transaction_date`	date	Required	Date the transaction occurs; drives rate selection.
`code`	string	Committed only	Your transaction code on POST /transactions. Unique per organization, location, and environment — acts as the duplicate guard.
`type`	string	Optional	sale (default), refund, or credit on POST /transactions.
`tax_override.type / tax_override.tax_amount / tax_override.reason`	string / decimal / string	Optional, committed sales_invoice only	Set type=tax_amount to preserve an exact caller-calculated document tax without invoking the ITMS tax engine. A reason is required for audit. The amount is allocated to lines deterministically and is never replaced.
`customer_code`	string	Optional	Your customer identifier. Matched to customers on file to apply exemption certificates automatically.
`certificate.customerCode`	string	Certificate create	Existing scoped customer that owns and receives the new Sales ECM certificate.
`certificate.jurisdiction / reasonCode / blanket`	string / boolean	Certificate create	The state, exemption reason, and blanket-certificate posture recorded by the shared certificate manager.
`certificate.effectiveFrom / effectiveTo`	date	effectiveFrom required	Certificate validity window. Out-of-window records cannot activate or suppress tax.
`certificate.signedBy / signerTitle / signatureType / customerEmail`	string	Activation requires signedBy and signatureType	Certificate signature and contact metadata retained in the shared Sales ECM record.
`activation.attestedValid / evidenceReference / evidenceSha256`	boolean / string	Activation	A create always remains pending. Activation requires explicit attestation plus a durable reference and SHA-256 for the reviewed evidence.
`activation.reviewedBy / reviewAuthority`	string	Activation	Named human reviewer and either authorized_service_provider or taxpayer_authorized_reviewer authority. A bare API-key boolean never activates coverage.
`certificateCode`	string	Assignment	The active, currently effective certificate to assign to its exact customer. Cross-customer and cross-tenant assignments fail closed.
`exemption_certificate_code`	string	Optional	Requires a specific active ITMS certificate already assigned to customer_code. It never creates or self-attests an exemption.
`entity_use_code`	string	Optional	Customer usage classification supplied to exemption coverage evaluation and retained for audit.
`ship_to`	address	Required	Destination address: line1, line2, city, state (2-letter), zip_code (ZIP or ZIP+4), country (US). State + ZIP drive jurisdiction resolution.
`ship_from`	address	Optional	Origin address, accepted for your records.
`bill_to`	address	Optional	Billing address, accepted for your records.
`currency`	string	Optional	USD. The API rejects other currencies.
`discount`	decimal	Optional	Currency-cent document discount allocated proportionally across discounted lines (or all item lines) before tax. Residual cents use largest remainder, then ascending line number.
`calculation_type`	string	Optional	sales_tax (or omitted), consumer_use, vendor_use, or reverse_charge. Use-tax modes reconcile expected destination tax against lines[].tax_paid. reverse_charge additionally requires reverse_charge_basis.
`use_tax`	boolean	Deprecated compatibility alias	true maps only to calculation_type=consumer_use. New integrations should send calculation_type and prefer POST /tax/use/calculate.
`reverse_charge_basis / direct_pay_permit_number`	string	Reverse charge	reverse_charge_basis must be direct_pay_permit, self_assessed_use_tax, or other_us_statutory. A direct-pay basis also requires the permit number.
`validation_mode`	string	Optional	lenient (default): calculate with warnings at degraded precision. strict: fail invalid addresses and unknown tax codes.
`nexus_mode`	string	Optional	configured (default) returns zero tax without configured nexus. reference calculates anyway for stateless analysis and is rejected for committed transactions.
`accuracy_policy`	string	Optional	standard or deterministic_only. deterministic_only rejects degraded rate or precision fallback.
`product_identity_policy`	string	Optional	allow_generic (default) or require_known. require_known fails closed unless every item resolves through a known tax code or SKU.
`exemption_certificate_code / exemption_number`	string	Optional with customer_code	Select an existing active certificate assigned to the customer. exemption_number is a migration-friendly alias; neither field creates or self-attests an exemption.
`minimum_address_precision`	string	Optional	any (default), zip5, zip9, street, or rooftop. The request fails closed when a destination resolves below the required precision.
`transaction_kind`	string	Required for specialized state rules	unknown (default) or retail_sale. ITMS does not infer a retail-sale posture from a sales document name.
`seller_class`	string	Required when seller posture changes treatment	unknown (default), in_state, remote, or marketplace. This is a caller-supplied transaction fact, distinct from marketplace tax responsibility.
`retail_delivery`	object	CO/MN delivery-fee output	Explicit seller-threshold status, qualifying-items amount, delivery count, cancellation status, fee collected, and (for Colorado) motor-vehicle delivery fact. The seller fee is calculated and returned separately from buyer sales tax.
`washington_business_activity`	object	WA B&O output	Explicit retailing, wholesaling, or service_and_other activity with gross receipts, deductions, and required service rate tier. ITMS does not infer an activity class or tier.
`tx_single_local_use_tax_rate_elected / txSingleLocalUseTaxRateElected`	boolean	Explicit Texas election only	Texas remote sellers may send true only after electing the Comptroller-published single local use-tax rate and when sourcing is not origin. ITMS never infers this election.
`tax_sourcing / taxSourcing`	string	Required when state law requires an explicit sourcing decision	unknown (default), origin, or destination. This legal outcome is distinct from sourcing_basis, which selects the address used after sourcing is decided.
`single_article / singleArticle`	string	Required for single-article rules	unknown (default), yes, or no. ITMS never infers statutory single-article identity from quantity, description, or amount.
`tax_regime / taxRegime`	string	Required for nonstandard regimes	unknown (default) or hawaii_get. An explicit regime fails closed if its guarded deterministic resolver is unavailable; it never falls through to ordinary ZIP sales-tax content.
`business_activity_code / businessActivityCode`	string	Required for hawaii_get	Official G-45 activity-class key. ITMS does not infer the seller activity from a product description or generic taxable code.
`taxation_district / taxationDistrict`	string	Required for hawaii_get	Official GET allocation district: oahu, maui, hawaii, or kauai. A destination ZIP is not treated as seller activity situs.
`seller_tax_pass_through / sellerTaxPassThrough`	boolean	Explicit true for customer-visible GET	Affirmative seller election to visibly pass a seller-liability tax to the customer. Omission or false never becomes consent; Hawaii GET is not labeled ordinary sales tax.
`Migration aliases`	compatibility	Optional	date, customerCode, currencyCode, exemptionNo, customerUsageType, itemCode, taxCode, taxIncluded, taxPaid, region, postalCode, addresses.shipTo/shipFrom/billTo, and SalesOrder/SalesInvoice/PurchaseOrder/PurchaseInvoice type names are accepted.
`sourcing_basis / sourcingBasis`	string	Required with specialized addresses	Explicitly selects ship_to, ship_from, point_of_order_origin, point_of_order_acceptance, or goods_place_or_service_rendered as the tax situs. Specialized document or line addresses fail closed without this selector.
`addresses.pointOfOrderOrigin / pointOfOrderAcceptance / goodsPlaceOrServiceRendered`	address	Optional	Avalara-style specialized address blocks. ITMS retains them and applies only the address explicitly selected by sourcing_basis; it never guesses sourcing intent.
`research_fallback`	string	Sandbox stateless only	auto, disabled, or required. Experimental results are explicitly marked non-authoritative and can never be committed or used for returns.
`marketplace`	object	Optional	Document-level channel and responsibility facts. Omission means unknown; a provider or vendor name never infers legal responsibility.
`marketplace.sales_channel_type / channel_id / channel_account_id`	string / integer	Optional	Classify the document as direct, marketplace, or unknown and identify the tenant-scoped channel and account when known.
`marketplace.marketplace_seller_identifier / merchant_of_record`	string	Optional	Preserve the marketplace seller or merchant identifier and whether the seller, facilitator, or both acted as merchant of record.
`marketplace.taxpayer_role / facilitator_identifier`	string	Optional	Select the taxpayer capacity for this document or line (seller or facilitator). A both-role account must resolve each marketplace line to one capacity; reviewed state posture can provide the default.
`marketplace.calculation_responsibility / collection_responsibility / remittance_responsibility / reporting_responsibility`	string	Optional	Record each independent legal/operational owner as seller, facilitator, shared, or unknown. Unknown values fail closed instead of becoming direct.
`marketplace.facilitator_collected_tax_amount / facilitator_remitted_tax_amount / seller_collected_tax_amount`	decimal	Optional	Supply explicit non-negative responsibility allocations when the source provides them; omitted amounts remain unresolved rather than inferred.
`marketplace.designation_source / designation_confidence / designation_evidence`	string / decimal / object	Optional	Trace the designation to its source, confidence, and retained evidence.
`lines[]`	array	Required	1–100 lines per request; caller line identifiers must be unique.
`lines[].number`	integer or string	Required	Unique caller line identifier. Positive integers remain native numbers; arbitrary text is preserved as external_number while ITMS assigns a stable internal integer.
`lines[].amount`	decimal	Required	Extended line amount subject to tax.
`lines[].quantity`	decimal	Optional	Defaults to 1.
`lines[].sku_code`	string	Optional	Your product identifier. Matched to SKUs on file for product taxability.
`lines[].description`	string	Optional	Line description retained for audit and used by automated product identity when a known SKU or tax code is unavailable.
`lines[].line_type`	string	Optional	item (default), shipping, or handling. Separately stated shipping lines follow the destination state's shipping taxability rule content.
`lines[].tax_code`	string	Optional	ITMS tax code (e.g. TAXABLE, EXEMPT, SHIPPING). Drives line taxability; unknown codes warn in lenient mode and fail in strict mode. API-key integrations read the active registry from GET /api/v1/config.
`lines[].tax_code_system / lines[].source_tax_code`	string	Optional pair	Caller namespace and source code, such as avalara plus a customer tax code. The pair resolves through your saved mapping before product classification. It cannot be combined with tax_code, and an unmapped value fails closed rather than invoking AI judgment.
`lines[].discount_amount`	decimal	Optional	Line-level discount subtracted from the line amount before tax.
`lines[].discounted`	boolean	Optional	Opts the line into document-level discount allocation.
`lines[].tax_included`	boolean	Optional	The amount includes tax; the engine backs tax out of the gross amount so taxable + tax equals the amount.
`lines[].ship_to / lines[].ship_from`	address	Optional	Line-level situs overrides for multi-destination documents; omitted values inherit the document addresses.
`lines[].transaction_kind / seller_class / tax_sourcing / single_article`	string	Optional	Line-specific overrides for mixed-fact documents; omitted values inherit the explicit document facts.
`lines[].tax_regime / business_activity_code / taxation_district / seller_tax_pass_through`	string / boolean	Optional	Line-specific nonstandard-regime overrides. Omitted values inherit document facts; an explicit false pass-through overrides document true.
`lines[].tax_paid`	decimal	Purchase/use tax	Vendor tax already paid. Expected tax minus tax paid becomes use tax due; overpayment is reported separately.
`lines[].qualifying_use_percentage`	decimal 0–100	Supported documented allocations only	Caller-supplied qualifying-use percentage used only by supported fact-aware treatments, such as documented Wisconsin manufacturing utility use. It does not create an exemption certificate and remains non-filing-safe.
`lines[].marketplace`	object	Optional	Line-specific responsibility override for mixed or multi-merchant documents; omit to inherit the document marketplace facts.

Freight, discounts, tax-included & preserved tax

Freight / handling. Set line_type to shipping or handling. Separately stated shipping lines follow the destination state's shipping taxability rule content; the response carries a warning whenever a shipping rule is applied so you can retain the applied treatment with the transaction.
Discounts. Use lines[].discount_amount for a line-level discount, or a currency-cent document-level discount allocated proportionally across lines flagged discounted (residual cents use largest remainder, then ascending line number) (or all item lines). Discounts reduce the taxable base before tax.
Tax-included. Set lines[].tax_included when the amount already includes tax; the engine backs tax out of the gross so taxable_amount + tax_amount equals the submitted amount. Stateless quotes and committed transactions produce identical results.
Preserve tax already calculated elsewhere. On a committed sales_invoice, send tax_override with type: "tax_amount", the exact document tax_amount, and an audit reason. ITMS records that amount without invoking the tax engine. With tax-exclusive lines, the preserved tax is added to the subtotal. When every line has tax_included: true, it is backed out of the submitted gross so the document total does not change. Mixed inclusive and exclusive lines are rejected because a document-level allocation would be ambiguous.

Response fields

Field	Description
`request_id`	Unique id for the request; include it when contacting support.
`environment`	sandbox or production, derived from the API key.
`subtotal / discount_total / total_tax / total`	Document totals. Monetary and rate values are JSON strings to preserve decimal precision.
`lines[].status`	calculated, preserved, not_taxable, or rate_unavailable. preserved means caller tax was recorded without an ITMS tax calculation.
`lines[].number / external_number`	Stable internal integer plus the original textual line identifier when one was supplied.
`lines[].taxable_amount / discount_applied`	The amount tax was computed on, and the discount netted from the line before tax.
`lines[].tax_rate / tax_amount`	Combined rate applied and resulting tax for the line.
`tax_override`	The caller-authoritative tax contract on a committed transaction: type, exact tax_amount, and audit reason. Omitted on ordinary ITMS-calculated transactions.
`lines[].jurisdiction`	Resolved jurisdiction with state, combined_rate, and the state / county / city / special effective-rate composition. A component rate can be an effective whole-line rate when a statutory cap limits that component base.
`lines[].jurisdiction_taxable_bases / jurisdiction_tax_amounts`	Component bases and tax amounts when a statutory cap or fact-sensitive allocation, such as Florida item caps or mixed-item NY/FL freight, produces different state/local bases. Component tax amounts reconcile to line tax_amount; use these bases and amounts, rather than multiplying an effective rate by a different component base, to audit capped calculations.
`lines[].nexus`	Whether the destination state is one where you have nexus on file.
`lines[].line_type / tax_code`	The line classification and applied ITMS tax code.
`lines[].product_metadata`	Tax-code and SKU treatment plus the governed automated product-identity decision, provenance, confidence, and fallback tier used for the line.
`lines[].transaction_context`	The normalized transaction kind, seller posture, legal sourcing outcome, single-article fact, and any explicit nonstandard-regime facts supplied to the state calculation seam.
`lines[].ship_to / address_metadata`	Effective line destination and its normalization, precision, county, geocode, and provider provenance.
`lines[].exemption_applied / suppression_reason`	Whether tax was suppressed and why: exempt_certificate_on_file, legacy_customer_exempt, product_not_taxable, tax_code_exempt, or shipping_not_taxable.
`marketplace / lines[].marketplace`	Resolved document and line channel, merchant identity, calculation, collection, remittance, reporting, designation provenance, and responsibility warnings.
`expected_tax / seller_remittable_tax / unresolved_responsibility_tax`	Expected tax remains independent from seller liability; facilitator-remitted tax never enters seller-remittable tax, and incomplete ownership is quantified as unresolved.
`lines[].marketplace.expected_tax_amount / facilitator_collected_tax_amount / facilitator_remitted_tax_amount / seller_collected_tax_amount / seller_remittable_tax_amount / unresolved_responsibility_amount`	Per-line allocation proves how tax was expected, collected, remitted, assigned to the seller, or left unresolved.
`status / parent_code / voided_at / refunded_total`	Committed-transaction lifecycle: committed, voided, partially_refunded, or refunded; refunds link to their original via parent_code.
`revision_of_code / revision_number / adjustment_reason / document_type`	Committed adjustment and tax-only-credit lineage, kept distinct from refund parent_code.
`metadata.address_basis / rate_basis / rate_source_detail`	Customer-visible resolution categories for the address, jurisdiction, and rate content used. These values describe the result contract without exposing internal processing.
`metadata.rate_snapshot_month`	The effective content period when the selected calculation source publishes a period-specific value; otherwise null.
`metadata.address_validation_status / address_provider / normalized_address / geocode`	Address resolution outcome (validated, corrected, unverified, invalid), the provider that resolved it, and the normalized address and coordinates when a validating provider is configured.
`metadata.jurisdiction_precision / jurisdiction_source`	The precision and customer-visible jurisdiction-resolution category used for the calculation, such as ZIP, street/geocode, or registered location.
`metadata.rate_realtime / fallback_used / fallback_reason / cass_grade_available`	Whether the selected source was evaluated in real time, whether an alternate supported calculation path served the request, why that path was selected, and whether CASS-grade address validation backed the result.
`metadata.rate_content_metadata.rate_source_key / rate_extract_sha256 / boundary_source_key / boundary_extract_sha256 / boundary_provenance`	Owned rate and boundary lineage. Boundary provenance is manifest when a real checksummed boundary package selected the answer; a governed synthesized boundary is labeled synthesized and carries null boundary source/hash values rather than implying manifest lineage.
`warnings`	Per-line and document-level notices about how the calculation was resolved (e.g. shipping-rule applied, no-nexus reference tax, fallback used).
`metadata.calculation_authority / experimental / evidence_sources`	Distinguishes deterministic results from explicitly non-authoritative sandbox estimates and identifies supporting public evidence.
`total_expected_tax / total_tax_paid / total_use_tax_due / total_overpayment`	Purchase/use-tax reconciliation totals; line-level equivalents appear on each line.
`supplemental_compliance`	Separate seller-side compliance outputs. Calculation and transaction responses can include retail_delivery_fee and washington_bo; return packages can additionally include use_tax and california_schedule_c. None of these amounts is silently added to buyer sales-tax totals.
`calculation_type / liability_basis`	Sales-tax calculate returns gross expected tax. The dedicated use-tax endpoint returns net use tax due after reconciling vendor tax paid; the two totals must not be compared as if they were the same liability basis. liability_basis is seller_gross_receipts when the tax is imposed on the seller rather than collected from the buyer.
`tax_incidence / lines[].tax_incidence`	Who the law imposes the tax on: purchaser (every ordinary US sales tax) or seller_gross_receipts (Hawaii General Excise Tax, HRS ch. 237). This is a different question from the marketplace fields above, which answer who REMITS rather than who bears the tax. Null at document level when lines disagree; the per-line value is always authoritative.
`total_seller_liability_tax / lines[].seller_liability_tax`	Tax imposed on the seller rather than collected from the buyer. Never included in tax_amount or total_tax: a Hawaii sale with no visible pass-through election charges the buyer nothing, while the seller still owes GET on the gross receipts. A seller may instead elect to pass the GET on visibly, in which case the buyer is charged at the lawful maximum grossed-up rate and that charge appears in tax_amount; the line stays tax_incidence=seller_gross_receipts because the tax is still imposed on the seller, and seller_liability_tax is null there because the buyer charge already equals the seller GET exactly — reporting both would double-count the same dollar.
`certificateCode / customerCode / jurisdiction / reasonCode`	Certificate identity, exact customer ownership, jurisdiction scope, and exemption reason from the shared Sales ECM.
`certificate.status / assigned / effectiveFrom / effectiveTo`	Governed lifecycle and assignment state. Only an active, in-window, matching certificate can suppress tax.
`metadata.rate_content_metadata.reverse_charge`	For US reverse-charge calculations, records the validated statutory/direct-pay basis and whether permit evidence was supplied.

Resolution metadata

The metadata block describes the customer-visible provenance of each calculation: authority, address outcome, jurisdiction precision and source category, rate-basis category, content period when applicable, and whether an alternate supported path served the request. The ITMS API covers United States sales and use tax in USD. See Environments and Coverage for integration guidance.

Service-provider client fields

Provider onboarding creates ordinary Prophit organizations and locations. The provider engagement is the authorization boundary. Prefer its stable external reference on subsequent taxpayer-data calls.

Field	Type	Required	Description
`external_client_id`	string	Required	Stable client identifier from the provider system. Reusing it makes onboarding retries idempotent.
`name`	string	Required	Taxpayer organization name. The created organization is canonical and can later be used directly.
`legal_name / federal_tax_id`	string	Optional	Taxpayer legal identity used by readiness and return preparation.
`address_line1 / address_line2 / city / state / zip_code / country`	string	Optional	Organization mailing address. State is a two-letter code and country defaults to US.
`primary_location`	object	Optional	Creates the first canonical client location in the same idempotent onboarding request.
`client_context_ref`	string	Response	Recommended stable value for X-ITMS-Client-Ref. It matches the provider-owned external_client_id.
`client_context_id`	integer	Response	Backward-compatible numeric value for X-ITMS-Client-Id.
`id`	integer	Response	Provider engagement record ID. It currently matches client_context_id; use an explicit client_context field in integrations.
`organization_id`	integer	Response	Canonical taxpayer organization ID returned for reconciliation, not provider authorization.
`status`	string	Response	Engagement status. Paused or offboarded engagements cannot authorize taxpayer-data calls.

Service-provider location fields

Field	Type	Required	Description
`name`	string	Required	Client-visible location name, such as Main or Warehouse.
`address_line1 / address_line2 / city / state / zip_code / country`	string	Required	Canonical taxpayer location address.
`external_location_id`	string	Optional	Stable provider-system identifier for reconciliation and retry-safe administration.
`is_primary / active`	boolean	Optional	Primary-location designation and operational status.
`id / organization_id`	integer	Response	Canonical location and taxpayer organization identifiers.

Portfolio return-job fields

Field	Type	Required	Description
`idempotency_key`	string	Required	Provider-and-environment unique retry key for the portfolio job.
`items[]`	array	Required	Up to 5,000 independently isolated client, state, and filing-period requests.
`items[].reference_id`	string	Required	Provider correlation identifier returned with the item result.
`items[].client_id`	integer	Required	Authorized provider engagement ID.
`items[].state / period_start / period_end / filing_frequency`	string / date	Required	Return worksheet jurisdiction and filing period.
`status / total_items / completed_items / failed_items`	string / integer	Response	Durable job state and portfolio progress counters.
`results[].worksheet`	object	Response	Gross, exempt, and taxable sales; tax due and collected; credits, remittance, jurisdiction lines, and zero-return status.
`results[].requirements / validation_results / artifact_paths`	array	Response	Setup blockers, validation findings, and authorized output paths for each isolated item.

See Service-provider portfolios for the complete onboarding, client-context, readiness, and polling workflow.

PreviousRate limits NextErrors