Getting Started

First API Calls

Now that you’ve set up your account, generated an API key, and verified connectivity with the Ping endpoint, you’re ready to send your first real requests to TaxCloud. This page walks through the core sequence of calls every integration will use. Think of it as a “Hello World” for sales tax: light examples that show the flow end to end, with links to the full Workflow guides for deeper details.

The Core Sequence

Most integrations with TaxCloud follow this pattern:

  1. Look up tax on a cart: Send the items, prices, and addresses to get a tax calculation before checkout.
  2. Convert the cart into an order: Once payment is captured, convert the transaction into an order.
  3. Handle refunds or returns: Adjust previously completed orders to account for partial or full refunds.
  4. Upload existing orders: Backfill or reconcile transactions that happened outside your integration.

Doing Tax Lookups with Carts

The cart is the primary object for calculating tax. Create one with your customer, destination, and line items. A successful response includes the tax amount. Use this to display estimated tax in your checkout.

See Calculating Tax with Carts for more comprehensive information.

Converting Carts to Orders

Once checkout completes, convert the cart to an order. This is a crucial step; once an order is created, it becomes part of your taxable record and is eligible for reporting and filing in TaxCloud.

See Convert Carts to Orders for detailed information.

Handling Refunds and Returns

If a customer returns an item or you issue a refund, use the Refunds API to adjust the completed order.

See the Processing Refunds guide for partial refunds, multi-item adjustments, and more.

Uploading Existing Orders

If you have transactions that occurred outside your integration (for example, through another sales channel), you can upload them directly as orders to TaxCloud. This ensures your TaxCloud account has a complete record of all taxable and exempt sales.

See the Order Upload flow here for details on bulk uploads.

Where to Go Next

The next step is to learn how to test your integration safely and prepare it for production. Continue to Testing and Going Live for guidance on:

  • Separating test and production connections
  • Using trial keys versus live keys
  • Managing data between environments