Getting Started

How does TaxCloud work?

At its core, TaxCloud follows a simple four-step process that ensures sales tax is calculated accurately, orders are properly recorded, and returns are reconciled without compliance risk. Developers only need to implement a minimum set of APIs in order: VerifyAddress → Lookup → Order Completion → Returned. Together, these cover the entire sales tax lifecycle.

The four basic steps in TaxCloud’s process, are outlined below:

Address Verification (API: VerifyAddress)

Before calculating tax, confirm that the delivery address is complete and accurate. If your system already performs address validation, you can skip this step.

IMPORTANT: Do not proceed to tax lookup if the address is incomplete or invalid. Incorrect address data will always result in incorrect tax results.

Tax Amount Lookup (API: Lookup)

Next, call the Lookup API to calculate the exact sales tax due for each line item in the order. TaxCloud handles the jurisdiction rules, rounding, and thresholds automatically, removing the need to manually apply tax rates. TaxCloud responds with the exact dollars and cents of tax proceeds due for each line item.

NOTE: Our Lookup API does not respond with tax rates or jurisdiction/sub-jurisdiction details. Why?

  • Providing rates would require developers to do math, respecting varied rounding rules and knowledge of varied caps and thresholds.
  • Providing jurisdiction details would add payload unnecessary for time-of-sale tax collection—jurisdiction details are needed for tax reporting and are automatically included in standard TaxCloud tax reports and transaction records available from the TaxCloud website.

The Lookup endpoint in the current API version returns tax amounts based on the provided information but does not include jurisdiction/sub-jurisdiction breakdown in the response. If your current use-case requires detailed jurisdictional data (e.g. for display, reporting, or compliance purposes), be aware that this data is not currently returned by this endpoint.

Order Completion (APIs: Authorized and Captured; or AuthorizedWithCapture)

After checkout, notify TaxCloud that the order is final. This step records the transaction for compliance and ensures it is included in your tax reports.

IMPORTANT: Order completion is required. If you skip it, the transaction will not be included in reporting or remittance. We recommend using the simplified AuthorizedWithCapture method, which completes the order in one call.

Merchandise Returns (API: Returned)

This step occurs when an order is cancelled or modified after it was completed (after Order Completion).

  • If the Returned API is called in the current period, it will cancel-out the tax remittance for the period.

  • If the Returned API is called in a subsequent period, TaxCloud will automatically record the tax credit amount(s) for each jurisdiction of record, and automatically apply such credits to reduce future tax remittances to each applicable jurisdiction. The Returned API allows specification of a ReturnedDate. For example: If you had accepted and completed an order in February, and the order was returned in April, any sales tax due would have been reported and remitted with the February sales tax return.

  • If you pass the ReturnedDate parameter using the date of the original sale (or any date outside the current period), TaxCloud will recognize this as a change to the previously filed sales tax return, triggering an Amended Sales Tax Return to be generated and filed, including every intervening sales tax return from the period of the original sale to the current period. This will incur Late or Amendment Fees from TaxCloud, as well as filing obligations and charges from your CPA or accountant if TaxCloud is not filing on your behalf (via Automated Compliance). This should be avoided, unless your accountant or tax counsel has advised you to do this.

Testing

You do not need a separate sandbox account. Every new TaxCloud account starts in test mode by default, allowing you to send API requests safely using your live credentials. When you are ready to go live, simply switch your store to production mode, no code changes required.

Conclusion

TaxCloud’s order flow is designed to match how sales tax actually works: validate the address, calculate tax, finalize the order, and handle any returns. By following these four steps, you ensure your integration is fully compliant and your business stays audit-ready.