Migrating from API v1 to v3

This guide covers the key changes between API v1 and API v3 so you can update your integration efficiently. If you are building a new integration from scratch, skip this page and start with the Welcome to the TaxCloud API guide instead.

What Changed at a Glance

Authentication

v1 passed apiLoginID and apiKey inside every request body:

1
{
2
  "apiLoginID": "XXXXXXX",
3
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
  ...
5
}

v3 uses an X-API-KEY header for authentication. The connectionID (which replaces apiLoginID) is part of the URL path:

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/carts" \
>
  -H "X-API-KEY: your-api-key" \
>
  -H "Content-Type: application/json" \
>
  -d '{ ... }'

Migration Steps

1. Generate a new API key in the TaxCloud portal under Developer > API.
2. Locate your existing connectionID (your v1 connection works in v3) or create a new Custom API Connection under Integrations > Custom API.
3. Remove apiLoginID and apiKey from all request bodies.
4. Add the X-API-KEY header to every request.
5. Insert the connectionID into each endpoint URL.

For full setup details, see Setup and Authentication.

Tax Calculation: Lookup to Carts

The v1 Lookup endpoint is replaced by the v3 POST /carts endpoint. The core concept is the same (send items and addresses, receive tax amounts), but the request structure and field names have changed.

v1 Request

$
POST api.taxcloud.net/1.0/TaxCloud/Lookup

1
{
2
  "apiLoginID": "XXXXXXX",
3
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
  "customerID": "customer-33",
5
  "cartID": "B0DABCEE-34EE-4A76-B4C5-B5F32F430B74",
6
  "deliveredBySeller": false,
7
  "origin": {
8
    "Address1": "162 East Ave",
9
    "City": "Norwalk",
10
    "State": "CT",
11
    "Zip5": "06851",
12
    "Zip4": "5715"
13
  },
14
  "destination": {
15
    "Address1": "255 S King St",
16
    "City": "Seattle",
17
    "State": "WA",
18
    "Zip5": "98104",
19
    "Zip4": "2832"
20
  },
21
  "cartItems": [
22
    {
23
      "Index": 0,
24
      "ItemID": "prod23523",
25
      "TIC": 20010,
26
      "Price": 21.95,
27
      "Qty": 3
28
    }
29
  ]
30
}

v3 Request

$
POST https://api.v3.taxcloud.com/tax/connections/{connectionId}/carts

1
{
2
  "items": [
3
    {
4
      "currency": { "currencyCode": "USD" },
5
      "customerId": "customer-33",
6
      "origin": {
7
        "line1": "162 East Ave",
8
        "city": "Norwalk",
9
        "state": "CT",
10
        "zip": "06851-5715"
11
      },
12
      "destination": {
13
        "line1": "255 S King St",
14
        "city": "Seattle",
15
        "state": "WA",
16
        "zip": "98104-2832"
17
      },
18
      "lineItems": [
19
        {
20
          "index": 0,
21
          "itemId": "prod23523",
22
          "tic": 20010,
23
          "price": 21.95,
24
          "quantity": 3
25
        }
26
      ]
27
    }
28
  ]
29
}

Key Differences

v3 Response (excerpt)

1
{
2
  "items": [
3
    {
4
      "cartId": "ce4a...ccefdd",
5
      "customerId": "customer-33",
6
      "lineItems": [
7
        {
8
          "itemId": "prod23523",
9
          "price": 21.95,
10
          "quantity": 3,
11
          "tax": {
12
            "rate": 0.1025,
13
            "amount": 6.75
14
          }
15
        }
16
      ]
17
    }
18
  ]
19
}

Tip: v3 returns the tax rate alongside the amount for each line item. v1 only returned the tax amount.

Order Completion

Both v1 and v3 require you to authorize/capture a tax lookup to create an order. The core workflow is the same; the main change is terminology and endpoint structure. What v1 called AuthorizedWithCapture is now “creating an order from a cart” in v3.

v1: AuthorizedWithCapture

$
POST api.taxcloud.net/1.0/TaxCloud/AuthorizedWithCapture

1
{
2
  "apiLoginID": "XXXXXXX",
3
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
  "customerID": "customer-33",
5
  "cartID": "B0DABCEE-34EE-4A76-B4C5-B5F32F430B74",
6
  "orderID": "order-123"
7
}

v3: Convert Cart to Order

$
POST https://api.v3.taxcloud.com/tax/connections/{connectionId}/carts/orders

1
{
2
  "cartId": "ce4a...ccefdd",
3
  "orderId": "order-123",
4
  "completed": true
5
}

Key Differences

• Unified endpoint. v1 had three separate endpoints (Authorized, Captured, AuthorizedWithCapture). v3 consolidates these into a single POST /carts/orders endpoint that handles all three cases. The number of API calls in a given workflow stays the same.
• Deferred completion. Set completed: false at creation time, then PATCH /orders/{orderId} with a completedDate later. This supports cash-basis accounting, fulfillment-based workflows, and pre-orders.
• No customerID needed. Customer data is already captured in the cart.

For the full workflow, see Convert Carts to Orders.

Returns and Refunds

v1 used a single Returned endpoint. v3 introduces a dedicated Refund API and adds standalone credits for adjustments not tied to an existing order.

v1: Returned

$
POST api.taxcloud.net/1.0/TaxCloud/Returned

1
{
2
  "apiLoginID": "XXXXXXX",
3
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
  "orderID": "order-123",
5
  "returnedDate": "2025-08-01"
6
}

For partial returns, you included a cartItems array with the items being returned and adjusted Qty values.

v3: Refund Order

$
POST https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}

Full return (empty body):

1
{}

Partial return (specify items):

1
{
2
  "items": [
3
    {
4
      "itemId": "prod23523",
5
      "quantity": 1
6
    }
7
  ]
8
}

Key Differences

Note: Standalone credits let you reduce tax liability without referencing an original order. Set kind: "credit" on the Create Order endpoint. See Standalone Credits.

Exemptions

The approach to exemptions has been simplified in v3.

v1

Pass an exemptCert object inside the Lookup request, containing either a CertificateID (for a previously saved certificate) or a full Detail object to create a new certificate inline.

v3

Add an exemption object to the cart or order payload:

Direct attach (recommended):

1
{
2
  "exemption": {
3
    "exemptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
4
  }
5
}

Auto-match:

1
{
2
  "exemption": {
3
    "isExempt": true
4
  }
5
}

Key Differences

• v3 does not support creating certificates inline during tax calculation. Create certificates separately using the Create Exemption Certificate endpoint, then reference them by ID.
• Auto-match (isExempt: true) searches by customerID, connectionID, and destination state. If no match is found, the order is flagged Exempt—No certificate and requires manual resolution before filing.
• Direct attach by exemptionId is the recommended approach for production integrations.

For details, see Managing Tax Exemptions.

Error Handling

v1 returned HTTP 200 for every response, using a ResponseType field to indicate success or failure. v3 uses standard HTTP status codes.

Migration Steps

1. Replace any logic that checks ResponseType === 3 with standard HTTP status code checks.
2. Parse error details from the JSON response body instead of the Messages array.
3. Implement retry logic with exponential backoff for 500 errors. See Handling Errors for a sample pattern.

Address Format

Address fields have been renamed and simplified.

Note: v3 still requires two-character state abbreviations. Do not pass full state names.

Note: The plus-4 extension is optional. If you only have the 5-digit ZIP, pass it as-is (e.g., "zip": "98104"). TaxCloud will still calculate tax correctly.

Testing and Environments

The testing and environment model is largely the same between v1 and v3. The main difference is that v3 uses a connectionID instead of apiLoginID to identify the environment.

Create a dedicated test connection for development and QA. When you go live, switch to your production connectionID. Archive the test connection afterward to prevent accidental use.

For details, see Testing and Going Live.

New in v3

These capabilities are new or significantly improved in v3:

• Order Upload flow. A significantly improved version of the v1 AddTransactions capability. Submit pre-existing or historical orders directly, bypassing the cart step. See Order Upload Overview.
• Deferred order completion. v1 supported a two-step flow via separate Authorized and Captured endpoints. v3 streamlines this into a single endpoint: create the order with completed: false, then finalize later with a completedDate via PATCH.
• Standalone credits. Issue tax credits not tied to a specific order. See Standalone Credits.
• excludeFromFiling flag. Mark orders that should not be included in TaxCloud’s filed returns (e.g., orders already filed elsewhere).
• Management API. A separate set of endpoints for account and connection management.
• Tax rate in responses. Every tax calculation now returns both the rate and the amount per line item.

Migration Checklist

Use this checklist to track your migration progress:

1. Generate a new X-API-KEY and create a test connectionID in the TaxCloud portal.
2. Update your HTTP client to send X-API-KEY as a header and remove credentials from request bodies.
3. Replace Lookup calls with POST /carts.
4. Update address objects to use camelCase fields and the combined zip format.
5. Update line item fields: ItemID to itemId, TIC to tic, Qty to quantity.
6. Replace AuthorizedWithCapture (or Authorized + Captured) with POST /carts/orders.
7. Replace Returned calls with POST /orders/refunds/{orderId}.
8. Update exemption handling to use the exemption object with exemptionId or isExempt.
9. Replace ResponseType checks with HTTP status code handling.
10. Test the full flow (cart, order, refund) against your test connection.
11. Switch to your production connectionID and verify end-to-end.

Need Help?

If you run into issues during migration, reach out to the TaxCloud support team or explore the full API Reference.