Tax Exemption Data Sync

The Tax Exemption Data Sync API allows your application to synchronize tax exemption records from TaxWisp into your own database. Use this API to periodically retrieve new or updated tax exemptions and keep your customer records in sync.

---

Overview

The Tax Exemption Data Sync API returns tax exemption records that belong to your store.

You can use this API to:

• Retrieve newly approved or updated tax exemption records.
• Keep your application's customer tax exemption status synchronized with TaxWisp.
• Perform incremental synchronization using a pagination token.
• Retrieve tax exemption records for a specific customer when needed.

Important: This API must be called from your backend server because it requires your TaxWisp Client Secret. Never expose your Client Secret in frontend or client-side applications.

---

Step 1: Call the Data Sync API

Use the following endpoint to retrieve tax exemption records from TaxWisp.

Endpoint

GET https://taxwisp.ai/api/v1/external/tax-exemptions

---

Step 2: Authenticate Your Request

Pass your TaxWisp Client Secret in the request header.

Header

X-TaxWisp-Api-Key: YOUR_CLIENT_SECRET

Your Client Secret is available from your TaxWisp Dashboard under API Credentials.

Example Request

GET https://taxwisp.ai/api/v1/external/tax-exemptions?limit=50
X-TaxWisp-Api-Key: YOUR_CLIENT_SECRET

Important: Never expose your Client Secret in frontend or client-side applications. Always call this API from your backend server.

---

Step 3: Use Query Parameters

The API supports the following query parameters.

Parameter	Required	Description
limit	No	Number of records to return in a single request.
nextToken	No	Token returned by the previous response. Use it to continue incremental synchronization.
cid	No	Customer identifier. Use this to retrieve tax exemption records for a specific customer.

Example

GET https://taxwisp.ai/api/v1/external/tax-exemptions?limit=50

---

Step 4: Handle the API Response

A successful response returns a list of tax exemption records along with a nextToken for incremental synchronization.

Example Response

{
  "taxExemptions": [
    {
      "cId": "customer-12345",
      "cEmail": "customer@example.com",
      "jurisdiction": "Alabama",
      "exemptionCategory": "Reseller",
      "state": "OPEN",
      "updatedAt": "2026-09-10T08:15:30Z"
    }
  ],
  "nextToken": "eyJuZXh0VG9rZW4iOiAiYWJjMTIzIn0="
}

Response Fields

taxExemptions

An array containing the tax exemption records returned by TaxWisp.

Field	Description
cId	Customer identifier associated with the tax exemption.
cEmail	Customer email address.
jurisdiction	Tax exemption jurisdiction.
exemptionCategory	Category of the tax exemption.
state	Current state of the tax exemption record.
updatedAt	Date and time when the tax exemption record was last updated.

nextToken

A pagination token that identifies the position of the current synchronization.

Store this value and use it in the next synchronization request.

---

Step 5: Incremental Synchronization

The nextToken allows your application to synchronize records incrementally rather than retrieving the same records repeatedly.

Synchronization Process

1. Make the initial request without a nextToken.
2. Process the returned tax exemption records.
3. Store the nextToken from the response.
4. Use the stored nextToken in the next request.
5. Process the newly returned or updated records.
6. Store the new nextToken.
7. Repeat the process during each synchronization cycle.

Example

Initial request:

GET https://taxwisp.ai/api/v1/external/tax-exemptions?limit=50

TaxWisp returns:

{
  "taxExemptions": [
    {
      "cId": "customer-12345",
      "cEmail": "customer@example.com",
      "jurisdiction": "Alabama",
      "exemptionCategory": "Reseller",
      "state": "OPEN",
      "updatedAt": "2026-09-10T08:15:30Z"
    }
  ],
  "nextToken": "eyJuZXh0VG9rZW4iOiAiYWJjMTIzIn0="
}

Store the returned nextToken and use it in the next request:

GET https://taxwisp.ai/api/v1/external/tax-exemptions?limit=50&nextToken=eyJuZXh0VG9rZW4iOiAiYWJjMTIzIn0=

Note: Store the latest nextToken only after successfully processing the corresponding response. This helps prevent records from being skipped if your synchronization process fails.

---

Synchronizing a Specific Customer

To retrieve tax exemption records for a single customer, use the cid query parameter.

Example

GET https://taxwisp.ai/api/v1/external/tax-exemptions?cid=customer-12345

You can also combine cid with limit:

GET https://taxwisp.ai/api/v1/external/tax-exemptions?cid=customer-12345&limit=50

---

Recommended Process

1. Schedule a backend job to call the Data Sync API at your preferred interval.
2. On the first synchronization, call the API without a nextToken.
3. Process the returned tax exemption records.
4. Store the nextToken returned by TaxWisp.
5. On subsequent synchronizations, send the stored nextToken.
6. Update your local customer tax exemption records using the returned data.
7. Store the newly returned nextToken.
8. Repeat this process during the next synchronization cycle.

---

Example Backend Implementation

The following example demonstrates a basic synchronization flow using Node.js.

async function syncTaxExemptions() {
  const nextToken = await getStoredNextToken();

  const params = new URLSearchParams({
    limit: "50"
  });

  if (nextToken) {
    params.set("nextToken", nextToken);
  }

  const response = await fetch(
    `https://taxwisp.ai/api/v1/external/tax-exemptions?${params}`,
    {
      method: "GET",
      headers: {
        "X-TaxWisp-Api-Key": process.env.TAXWISP_CLIENT_SECRET
      }
    }
  );

  if (!response.ok) {
    throw new Error(`TaxWisp API request failed: ${response.status}`);
  }

  const data = await response.json();

  for (const exemption of data.taxExemptions) {
    await updateCustomerTaxExemption(exemption);
  }

  if (data.nextToken) {
    await saveNextToken(data.nextToken);
  }
}

The example is intended to demonstrate the synchronization flow. Adapt the database and error-handling logic to your application's architecture.

---

Handling the nextToken

The nextToken is an important part of the synchronization process.

Recommended Storage

Store the token in your application's database or other persistent storage.

For example:

Field	Example
integration	taxwisp
lastSyncAt	2026-09-21T09:30:00Z
nextToken	eyJuZXh0VG9rZW4iOiAiYWJjMTIzIn0=

Important Considerations

• Do not store the token only in application memory.
• Persist the token so synchronization can continue after application restarts.
• Update the stored token after successfully processing the returned records.
• Keep the latest valid token available for the next synchronization cycle.

---

Security Best Practices

• Call the Data Sync API only from your backend server.
• Keep your Client Secret secure and never expose it in frontend code.
• Store your Client Secret in a secure environment variable or secrets manager.
• Never commit your Client Secret to source control.
• Use HTTPS for all communication with TaxWisp.
• Store the latest nextToken after successfully processing the corresponding synchronization response.
• Restrict access to synchronization credentials to the backend services that require them.

---

API Summary

Method	Endpoint	Purpose
GET	/api/v1/external/tax-exemptions	Retrieve tax exemption records from TaxWisp.

Query Parameters

Parameter	Description
limit	Number of records to retrieve.
nextToken	Continue an existing incremental synchronization.
cid	Retrieve records for a specific customer.

Authentication

X-TaxWisp-Api-Key: YOUR_CLIENT_SECRET

---