Standard Checkout Flow Integration

TaxCloud’s API is designed to integrate seamlessly with eCommerce, order management, point of sale, and many other invoice and transaction management platforms. It enables you to accurately calculate your sales tax, manage exemption certificates, and upload orders for nexus management and filing.

This guide provides you with a complete, detailed walkthrough for integrating TaxCloud into your platform to calculate sales tax at checkout. You will learn cart creation, order conversion, exemption handling all in one single, streamlined checkout flow.

Prerequisites

Before you begin the integration, ensure you have the following:

• A TaxCloud account: You can sign up for a free trial account here.
• Configure your TaxCloud account: To ensure your integration works correctly, set up your TaxCloud account by completing your Business Profile, and configuring locations and states. Without these steps, tax rates will not be returned during API requests.
• API Credentials: Your API ID and API Key from the Developer Portal.
• Connection ID: A unique identifier from your custom API integration setup.

Authentication

Before diving into the integration, you will need to set up your TaxCloud API access. Do that by following these steps:

1. Create a TaxCloud account.
2. Navigate to Developer > API section.
3. Generate an API key.
4. Create a Custom API integration in the integrations section.
5. Copy your ConnectionID.

To verify if your authentication is working correctly for the connectionID, call the Ping endpoint. A successful call shows your connection is accurate.

How to Add Sales Tax Calculation to a Basic Checkout Flow

TaxCloud transforms your sales tax calculation into a seamless, automated experience. Our integrated platform, which combines our powerful APIs with a comprehensive web interface, creates a complete sales tax management ecosystem that does the heavy lifting for you.

There are two primary endpoints for calculating sales tax: /carts and /orders.

If you have been using our API V1, note that the ConnectionID now replaces the previous APIKey in most endpoint paths.

Initiating Sales Tax Calculation with Carts

After creating an account and obtaining your API credentials, you can create a cart by calling the create cart endpoint. A cart lets you show sales tax info for one or more sets of cart items to the customer before they make a purchase.

We support creating a cart for your specific use case- whether a cart with multiple items or multiple carts with multiple line items. To handle deliveries to multiple destinations, create a separate cart for each delivery address, including only the items being shipped to that destination.

Sample code

1
import requests
2
3
4
connection_id = "connectionidplaceholder"
5
api_key = "apikeyplaceholder"
6
7
url = f"https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts"
8
headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
9
payload = {
10
    "items": [
11
        {
12
            "currency": {
13
                "currencyCode": "USD",
14
            },
15
            "customerId": "customer-453",
16
            "destination": {
17
                "city": "Minneapolis",
18
                "line1": "323 Washington Ave N",
19
                "state": "MN",
20
                "zip": "55401-2427",
21
            },
22
            "lineItems": [
23
                {"index": 0, "itemId": "item-1", "tic": 0, "price": 10.75, "quantity": 1.5}
24
            ],
25
            "origin": {
26
                "city": "Minneapolis",
27
                "line1": "323 Washington Ave N",
28
                "state": "MN",
29
                "zip": "55401-2427",
30
            },
31
        }
32
    ]
33
}
34
response = requests.post(url, json=payload, headers=headers)
35
print(response.json())

Response

1
{
2
    "$schema": "https://api.v3.taxcloud.com/tax/schemas/CreateCartsResponse.json",
3
    "connectionId": "placeholderconnectionid",
4
    "transactionDate": "2025-03-17T14:13:08.267265Z",
5
    "items": [
6
        {
7
            "deliveredBySeller": false,
8
            "cartId": "ce4ab9a3-de00-436c-8ccb-20e9c6dcefdd",
9
            "customerId": "customer-453",
10
            "destination": {
11
                "line1": "323 Washington Ave N",
12
                "city": "Minneapolis",
13
                "state": "MN",
14
                "zip": "55401-2427",
15
                "countryCode": "US"
16
            },
17
            "origin": {
18
                "line1": "323 Washington Ave N",
19
                "city": "Minneapolis",
20
                "state": "MN",
21
                "zip": "55401-2427",
22
                "countryCode": "US"
23
            },
24
            "exemption": {
25
                "isExempt": false,
26
                "exemptionId": null
27
            },
28
            "currency": {
29
                "currencyCode": "USD"
30
            },
31
            "lineItems": [
32
                {
33
                    "index": 0,
34
                    "itemId": "item-1",
35
                    "tic": 0,
36
                    "price": 10.75,
37
                    "quantity": 1.5,
38
                    "tax": {
39
                        "rate": 0.09025,
40
                        "amount": 1.46
41
                    }
42
                }
43
            ]
44
        }
45
    ]
46
}

• Multiple Carts: If needed, you can include more than one cart in a single request for different addresses or buyer scenarios.
• TICs: Each line item uses its TIC to determine if the item is taxable.

Converting Carts Into Orders

An ensuing step after creating a cart, or carts as your case may be, is converting each of these carts into an order when the customer completes checkout or makes a purchase. Using the create order from a cartID endpoint, you can show an order was fulfilled and you can now file the tax for that order.

Each orderID must be unique for your connection to ensure accurate tax reporting and prevent duplicate transactions. TaxCloud automatically commits the order at the time of creation, finalizing it for tax filing.

Once a cart is ready and the customer has checked out, convert the cart into an order that is automatically committed (i.e., finalized for tax filing). However, if you need to delay finalizing the order (for example, for fulfillment or payment verification), you can create the order without marking it as complete and update the completed status later using the create order endpoint here.

To create orders from marketplace transactions, pre-existing systems or bulk uploads (which you can not do with the create order from a cartID endpoint), please see our guide here.

Sample Code

1
import requests
2
3
4
connection_id = "connectionidplaceholder"
5
api_key = "apikeyplaceholder"
6
7
url = f"https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts/orders"
8
headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
9
payload = {"completed": True, "cartId": "ce4ab9a3-de00-436c-8ccb-20e9c6dcefdd", "orderId": "my-new-order"}
10
response = requests.post(url, json=payload, headers=headers)
11
if response.status_code == 201:
12
    print("Order Created Successfully:")
13
    print(response.json())
14
else:
15
    print("Failed to Create Order:")
16
    print(response.status_code, response.json())

Managing Exemption Certificates

For tax-exempt customers, you can apply exemption certificates at the order or cart level. However, you must have created certificates, using this endpoint, and ensure they are active before being applied. With the certificates available, there are two options to apply them:

Option A: Direct Attachment

Attach an existing exemption certificate to your cart/order by providing its unique identifier (GUID).

Example Request

1
import requests
2
3
4
connection_id = "connectionidplaceholder"
5
api_key = "apikeyplaceholder"
6
7
url = f"https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts"
8
headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
9
payload = {
10
    "items": [
11
        {
12
            "currency": {
13
                "currencyCode": "USD",
14
            },
15
            "customerId": "customer-453",
16
            "destination": {
17
                "city": "Minneapolis",
18
                "line1": "323 Washington Ave N",
19
                "state": "MN",
20
                "zip": "55401-2427",
21
            },
22
            "exemption": {
23
                "exemptionId": "guidplaceholder"
24
            },
25
            "lineItems": [
26
                {
27
                    "index": 0,
28
                    "itemId": "item-1",
29
                    "tic": 0,
30
                    "price": 10.75,
31
                    "quantity": 1.5,
32
                }
33
            ],
34
            "origin": {
35
                "city": "Minneapolis",
36
                "line1": "323 Washington Ave N",
37
                "state": "MN",
38
                "zip": "55401-2427",
39
            },
40
        }
41
    ]
42
}
43
response = requests.post(url, json=payload, headers=headers)
44
print(response.json())

Option B: Auto-Match

If the certificate exists and matches by connectionID, customerID, and destination state, set the exemption field is_exempt to true and let the system auto-match. If no certificate is found during auto-match, the order is marked as exempt without a certificate—this will need resolution before final tax filing.

Error Handling and Retries

Our API reference doc provides detailed error responses. Always check the HTTP status codes and response body for error messages.

Testing Your Integration

Unlike some systems that use a separate sandbox, TaxCloud testing follows the same endpoints as production. For testing:

• Use your API credentials and connection ID as provided in your TaxCloud account.
• Validate your integration against known test cases.
• Monitor API responses in your TaxCloud dashboard to ensure that calculations and order statuses match expected values.

Tip: Maintain a separate environment (or configuration) for test credentials versus production credentials to avoid accidental live transactions during development.

Going Live

Before switching to production:

1. Review all API endpoints and flows: Ensure that cart and creation, and exemption certificates are correctly implemented.
2. Final Verification: Confirm that orders appear correctly in the TaxCloud dashboard and that tax calculations match your expectations.