Skip to main content

Embedded Widget

Enable customers to complete the TaxWisp tax exemption form directly inside your ecommerce application using the TaxWisp Embedded Widget.

Overview​

The TaxWisp Embedded Widget opens a modal inside your storefront or customer account page, allowing customers to submit their tax exemption request without leaving your application.

Integration Flow​

  1. Customer clicks Request Tax Exemption.
  2. Your backend creates a TaxWisp customer session.
  3. TaxWisp returns both a token and redirectUrl.
  4. Your frontend calls window.showTaxExemptionForm().
  5. The TaxWisp modal opens inside your application.
  6. Customer completes and submits the tax exemption request.

Important: The Customer Session API must be called from your backend because it requires your TaxWisp API key (X-TaxWisp-Api-Key). Never expose your client secret in frontend code.

Step 1: Add the TaxWisp CDN Assets

Include the TaxWisp stylesheet and JavaScript bundle in your application.

Stylesheet​

Add the stylesheet inside the <head> section of your application.

<link
  rel="stylesheet"
  href="https://cdn.taxwisp.ai/content/widget/prod/tax-exemption-manual-form.min.css"
/>

JavaScript​

Load the widget JavaScript before the closing </body> tag or after your application finishes loading.

<script src="https://cdn.taxwisp.ai/content/widget/prod/tax-exemption-manual-form.min.js"></script>

Once loaded, the CDN exposes the following global function:

window.showTaxExemptionForm(...);

Step 2: Create a Customer Session

Your backend creates a TaxWisp customer session.

Endpoint​

POST https://taxwisp.ai/api/v1/external/customer-sessions

Authentication​

Pass your TaxWisp Client Secret in the request header.

HeaderValue
Content-Typeapplication/json
X-TaxWisp-Api-KeyYOUR_CLIENT_SECRET

Request Body​

{
  "customerId": "customer-12345",
  "customerEmail": "customer@example.com"
}

Request Parameters​

FieldTypeRequiredDescription
customerIdStringYesYour unique customer identifier.
customerEmailStringYesCustomer's email address.

Step 3: Handle the API Response

Your backend receives the customer session details from TaxWisp.

Success Response​

{
  "redirectUrl": "https://customer.taxwisp.ai/session/abc123...",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields​

FieldDescription
redirectUrlURL that opens the TaxWisp Customer Portal if needed.
tokenAuthentication token required to open the embedded widget.

Important: Unlike the Customer Portal integration, both token and redirectUrl are required for the Embedded Widget integration.

Step 4: Open the Embedded Widget

After your backend returns the response, call the TaxWisp widget.

Frontend Example​

window.showTaxExemptionForm({
  authToken: token,
  redirectUrl: redirectUrl
});

Widget Configuration​

PropertyRequiredDescription
authTokenYesToken returned by the Customer Session API.
redirectUrlYesPortal URL used if the customer chooses to continue in the TaxWisp Customer Portal.

The widget opens as an embedded modal inside your application.

Complete Frontend Example​

async function requestTaxExemption(customerId, customerEmail) {
  const response = await fetch("/api/request-tax-exemption", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      customerId,
      customerEmail
    })
  });

  const { token, redirectUrl } = await response.json();

  window.showTaxExemptionForm({
    authToken: token,
    redirectUrl: redirectUrl
  });
}

Complete Backend Example (Node.js / Express)​

app.post("/api/request-tax-exemption", async (req, res) => {
  const response = await fetch(
    "https://taxwisp.ai/api/v1/external/customer-sessions",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-TaxWisp-Api-Key": process.env.TAXWISP_CLIENT_SECRET
      },
      body: JSON.stringify({
        customerId: req.body.customerId,
        customerEmail: req.body.customerEmail
      })
    }
  );

  const data = await response.json();

  res.json({
    token: data.token,
    redirectUrl: data.redirectUrl
  });
});

Customer Experience​

The customer completes the tax exemption request without leaving your application.

StepCustomer Action
1Clicks Request Tax Exemption.
2Your backend securely requests a customer session from TaxWisp.
3Your frontend calls window.showTaxExemptionForm().
4The TaxWisp modal opens inside your application.
5Customer selects the exemption jurisdiction.
6Customer uploads exemption certificates and supporting documents.
7Customer reviews and submits the exemption request from the modal.

Continue in TaxWisp Customer Portal​

The embedded widget includes a Continue in TaxWisp Portal option.

If the customer chooses this option:

  • The widget automatically uses the provided redirectUrl.
  • The customer is redirected to the TaxWisp Customer Portal.
  • The customer can continue the exemption process outside your storefront without restarting the session.

No additional integration work is required for this fallback experience.

Security Best Practices​

  • Always call the Customer Session API from your backend.
  • Never expose your X-TaxWisp-Api-Key or client secret in frontend or client-side JavaScript.
  • Pass only the returned token and redirectUrl from your backend to the frontend widget.
  • Use HTTPS for all communication between your application and TaxWisp.

API Summary​

MethodEndpointPurpose
POST/api/v1/external/customer-sessionsCreate a customer session and receive the token and redirectUrl required for the embedded widget.

CDN Assets Summary​

AssetURL
Stylesheethttps://cdn.taxwisp.ai/content/widget/prod/tax-exemption-manual-form.min.css
JavaScripthttps://cdn.taxwisp.ai/content/widget/prod/tax-exemption-manual-form.min.js