Getting Started

Setup and Authentication

Getting a live TaxCloud response takes only a few minutes, but there are a few account setup tasks you must complete first. This page walks you through them step by step and ends with a quick “Ping” call so you know everything is wired correctly.

Create or sign in to your TaxCloud account

If you do not already have an account, register for a free trial at https://app.taxcloud.com/register. Trial mode gives full API access for your first 30 days with TaxCloud.

Complete your business profile and nexus details

Before you can access TaxCloud’s services, we need to know who you are and where you sell. Sign in, create your business Profile, and fill in legal name, FEIN, addresses, and contact email. Then visit the Locations & States tab and add at least one origin address plus every state where you have nexus. If no states are marked active, the API will reply with zero tax for every request.

Generate an API key

  1. In the left navigation, choose Developer > API.
  2. Click Generate new key. Copy the value that appears; this is your X-API-KEY. You will set this key in the X-API-KEY header for authorization in every API call.

Migrating from API v1?

In this new version, connectionID is used in the URL path and has replaced API Login ID in all endpoints.

Create a Custom API connection

  1. Go to Integrations > Custom API.
  2. Click New connection, give it a name like “My-Store-Prod”, and save.
  3. The dashboard shows a UUID-style ConnectionID (for example, 2f9a1d0e-ab12-4bcd-8f09-456789e0cdef). Copy it, as every request URL will include this ID.

Connecting a custom API integration with TaxCloud

Please see this guide on how to connect or create a custom API integration with TaxCloud.

Store credentials safely

Store your X-API-Key securely and rotate it regularly to protect your integration. The ConnectionID can be referenced directly from your TaxCloud integration page.

Verify with the Ping endpoint

Open your terminal and run the following smoke test, replacing the placeholders with real values. You can also call this endpoint directly from TaxCloud API reference documentation.

A successful response looks like this:

1https://api.v3.taxcloud.com/tax/connections/25eb9b97-5acb-492d-b720-c03e79cf715a/ping \
2-H "X-API-KEY: <apiKey>"
3-H “Accept: application/json”
4{“status”: “ok”, “connectionId”: “2f9a1d0e-ab12-4bcd-8f09-456789e0cdef”, “time”: “2025-07-01T21:14:06Z”}\

If you see “401 Unauthorized” check the X-API-KEY header. A “404 Connection not found” means the ConnectionID in your URL is mistyped or belongs to another account.

Production and testing use the same host

TaxCloud does not provide a separate sandbox environment. Instead, you use your trial API keys and connection for testing, then switch to production keys when you’re ready to go live.

To keep test and live data separate, we recommend creating two distinct connections:

  • Test connection: Used for ongoing development, QA, and sandbox-style testing.
  • Production connection: Used once you are ready to process real transactions.

While the same API key works for both test and live traffic, the connectionID in your request determines which environment you’re working in. Any exemption certificates or settings added in your test connection will not transfer to production.

Next steps

A successful Ping call completes the setup phase. You now have working credentials, a valid ConnectionID, and proof that the API accepts your calls.

The next step is to move from connectivity to actually using TaxCloud. Start with the First API Calls guide, where you’ll learn how to:

  • Do real-time tax calculation
  • Capture existing orders for copmpliance reporting
  • Handle refunds and returns

Once you understand this basic sequence, you’ll be ready to dive deeper into the full Workflows section for advanced use cases and edge cases.