Frequently Asked Questions
Common questions about integrating with the TaxWisp Standalone API.
General
What is the TaxWisp Standalone integration?
The TaxWisp Standalone integration lets you connect any ecommerce application to TaxWisp. Your application communicates with TaxWisp via REST APIs to manage tax exemption requests, sync exemption records, and power analytics.
Is TaxWisp available outside the United States?
No. TaxWisp is currently available only for stores operating within the United States and covers US sales tax exemption requirements.
Where do I find my API key?
Your API key (X-TaxWisp-Api-Key) is available from the Settings page of your TaxWisp account. Keep it secure and never expose it in frontend code or commit it to source control.
Can I invite other team members to my TaxWisp account?
Yes. From your TaxWisp account you can invite additional members. Invited members can view all tax exemption requests and take action on them (approve or reject).
Can I add my store location in TaxWisp?
Yes. Sellers can add and manage their store location directly from within the TaxWisp app. Note that a store can only exempt sales tax for a jurisdiction where it has a physical presence.
Authentication
How do I authenticate API requests?
Pass your TaxWisp API key in the X-TaxWisp-Api-Key request header on every call to the TaxWisp Integration API.
X-TaxWisp-Api-Key: YOUR_API_KEY
Should I call TaxWisp APIs from my frontend?
No. All TaxWisp API calls must be made from your backend server. Never expose your API key in frontend or client-side JavaScript.
Customer Portal Redirect
What does the Customer Portal Redirect integration do?
It redirects your customers from your storefront to the hosted TaxWisp Customer Portal, where they can securely upload and submit their tax exemption documents. TaxWisp handles the entire document collection flow.
What do I need from my backend to start the redirect?
Your backend must call POST https://taxwisp.ai/api/v1/external/customer-sessions with the customer's customerId and customerEmail. TaxWisp returns a redirectUrl that you send to your frontend to redirect the customer.
Do I need the token field returned by the Customer Session API for the redirect flow?
No. Only the redirectUrl is needed for the redirect integration. The token field is used by the Embedded Widget integration.
Embedded Widget
What is the Embedded Widget?
The Embedded Widget opens a modal inside your application so customers can complete their tax exemption request without being redirected away. It is loaded via a CDN JavaScript bundle.
How do I load the Embedded Widget?
Add the TaxWisp CDN stylesheet and script to your application:
<link rel="stylesheet" href="https://cdn.taxwisp.ai/content/widget/prod/tax-exemption-manual-form.min.css" />
<script src="https://cdn.taxwisp.ai/content/widget/prod/tax-exemption-manual-form.min.js"></script>
Then call:
window.showTaxExemptionForm({ authToken: token, redirectUrl: redirectUrl });
Do I need both token and redirectUrl for the Embedded Widget?
Yes. Unlike the redirect flow (which only needs redirectUrl), the Embedded Widget requires both fields returned by the Customer Session API. The token authenticates the widget session and the redirectUrl is used if the customer chooses to continue in the full TaxWisp Customer Portal.
What happens if a customer clicks "Continue in TaxWisp Portal" from the widget?
The widget automatically uses the redirectUrl you provided to redirect the customer to the TaxWisp Customer Portal. The session continues seamlessly — the customer does not need to restart the exemption process.
Tax Exemption Data Sync
How do I retrieve approved tax exemption records from TaxWisp?
Call the Data Sync API from your backend:
GET https://taxwisp.ai/api/v1/external/tax-exemptions
X-TaxWisp-Api-Key: YOUR_API_KEY
What is the nextToken and why should I store it?
The nextToken is a pagination cursor returned by TaxWisp after each sync response. Pass it in your next request to fetch only new or updated records since your last sync. Store it in persistent storage (not in-memory) so your sync can resume correctly after a restart or failure.
Can I sync exemption records for a single customer only?
Yes. Use the cid query parameter with your customer's ID:
GET https://taxwisp.ai/api/v1/external/tax-exemptions?cid=customer-12345
What does the state field in a tax exemption record mean?
It represents the current status of the exemption request in TaxWisp (for example, OPEN for pending requests). Use it to keep your local customer records aligned with the current exemption status in TaxWisp.
Analytics Data Sync
What is the Analytics Data Sync?
TaxWisp periodically pulls order data from your Orders API to generate tax-exemption analytics and reporting. You expose a single paginated GET endpoint; TaxWisp handles the rest.
What endpoint does my application need to expose?
A single HTTP GET endpoint that returns paginated order data, for example:
GET https://your-store.com/api/orders?page=1
How does TaxWisp paginate through my orders?
TaxWisp sends a page query parameter (starting at 1) and reads the pageMetadata object in your response to determine if more pages exist. Increment pageNumber and continue until pageNumber equals totalPages.
What fields are required in the Orders API response?
At minimum each order must include:
| Field | Notes |
|---|---|
id | Stable, unique order ID |
createdAt | ISO-8601 timestamp |
updatedAt | ISO-8601 timestamp — update when the order changes |
taxExempt | Boolean |
lineItems | Array with id, quantity, taxable, totalPrice |
totalPrice | Object with amount and currencyCode |
And the response must include a pageMetadata object with pageNumber, totalPages, totalRecords, and currentRecords.
Can my Orders API require authentication?
Yes. Configure your API key or auth token in TaxWisp during setup. TaxWisp will include it as a header or query parameter on every request.