ITMS accepts familiar sales and use tax concepts while making environment, tenant scope, transaction history, and calculation authority explicit. Use this guide to plan an evaluation without assuming that similarly named operations have identical persistence semantics.
Connection and environment
| AvaTax | ITMS |
|---|---|
| Separate sandbox and production hosts | One host; each key has an immutable sandbox or production environment |
| Basic authentication | Bearer or X-API-Key authentication with itms_test_ and itms_live_ prefixes |
X-Avalara-Client | X-ITMS-Client: app-name/version |
| Company/location selected in URL or model | Organization and optional location derive from the key and cannot be overridden |
Operation mapping
| AvaTax operation | ITMS operation | Behavior |
|---|---|---|
| ResolveAddress | POST /api/v1/addresses/resolve | Standalone normalization and precision metadata |
| CreateTransaction for an order or quote | POST /api/v1/tax/calculate | Stateless; never persisted |
| CreateTransaction with commit=false | POST /api/v1/transactions with a saved order type | Saved until commit or cancel |
| CreateTransaction / commit invoice | POST /api/v1/transactions | Send Idempotency-Key for safe retries |
| CreateOrAdjustTransaction | POST /api/v1/transactions/create-or-adjust | Identical payload replays; changed payload creates immutable revision lineage |
| Get/List transactions | GET /api/v1/transactions/{code} and GET /api/v1/transactions | Key scope and environment enforced |
| VoidTransaction | POST /api/v1/transactions/{code}/void | Idempotent where lifecycle permits |
| RefundTransaction | POST /api/v1/transactions/{code}/refund | Full, partial, percentage, and tax-only modes |
| AdjustTransaction | POST /api/v1/transactions/{code}/adjust | Atomic immutable reversal and replacement |
| Consumer/vendor use tax | POST /api/v1/tax/use/calculate | Reconciles expected tax against vendor-paid tax |
| CreateTransactionBatch | POST /api/v1/batches/calculations | Up to 500 deterministic calculations; poll by batch ID |
| Create or adjust item/customer | PUT /api/v1/items/{item_code} and /customers/{customer_code} | Scoped durable integration identity |
Field compatibility
Common spellings such as date, customerCode, addresses.shipTo, itemCode, taxCode, taxIncluded, customerUsageType, and AvaTax document-type names are accepted where documented. ITMS native responses use snake_case.
exemptionNomust match an active certificate assigned to the scoped customer; an arbitrary value never suppresses tax.customerUsageTypeis retained as classification context but does not create exemption evidence.- Item mappings establish product identity; use
product_identity_policy=require_knownto fail closed. - Specialized sourcing addresses require an explicit
sourcing_basis; ITMS does not guess the legal sourcing decision.
Nexus, accuracy, and retries
- Configured nexus is the default. A state without configured nexus returns zero tax with an explicit suppression reason.
nexus_mode=referenceis stateless-only and cannot be committed.- Use
accuracy_policy=deterministic_onlyandminimum_address_precisionfor fail-closed evaluation. - Send a unique
Idempotency-Keyon every write and reuse it only for an identical canonical payload. - Honor
Retry-After; retry 429, 502, 503, and 504 with bounded exponential backoff and jitter. - After a timeout, reconcile by document code before generating a new document code.
Evaluation checklist
- Create a least-privilege location-scoped sandbox key; use an organization key only for organization-wide administration.
- Read
/api/v1/configand/api/v1/coverage/states, then resolve representative addresses. - Upsert representative item and customer mappings before comparing product, exemption, discount, shipping, and marketplace cases.
- Exercise no-nexus, strict identity, minimum precision, validation, rate-limit, timeout, and idempotent-retry cases.
- Save and commit an order, then test void, adjustment, partial refund, percentage refund, and tax-only credit.
- Verify sibling location and environment isolation and retain request IDs with the evaluation record.
Continue with the endpoint reference and transaction lifecycle for operation-level behavior.