Conditionally Show Truemed's PDP Widget

The Product Detail Page (PDP) widget lets customers know—right on the product page—that they might be eligible to pay with their HSA/FSA. The widget should only appear when the product qualifies—not every product is HSA/FSA eligible.

Why this matters

Showing the HSA/FSA badge or widget on ineligible products creates a confusing experience: customers click through to checkout expecting to pay with their benefits, only to find out the item isn’t covered. Conditionally rendering the widget based on real eligibility data keeps the storefront accurate and builds trust.

How the widget works

The widget is a JavaScript bundle served from Truemed’s CDN. Add a placeholder <div> to the PDP template and load the script tag—the widget self-initializes by finding the placeholder and injecting the HSA/FSA badge and “Learn more” modal into it.

1
<div id="truemed-instructions" style="font-size: 14px;" icon-height="12" data-public-id="{{ INSERT PUBLIC ID HERE }}"></div>
2
<script src="https://static.truemed.com/widgets/merchant-pdp-widget.min.js" defer></script>

The eligibility check controls whether the placeholder div is rendered at all. The widget does not need to be called manually.

How to implement

Option 1: Use stored eligibility data (recommended)

The most performant approach is to store each product’s Truemed eligibility status (see Build HSA/FSA-Eligible Collections) and use it to conditionally render the placeholder server-side or at page load.

1
if (product.truemedEligibility === 'hsa_fsa_eligible' ||
2
    product.truemedEligibility === 'eligible_with_lmn') {
3
  document.getElementById('truemed-widget-slot').innerHTML =
4
    '<div id="truemed-instructions"></div>';
5
}

Option 2: Use the Checkout Method endpoint

For a real-time eligibility check, call check_truemed_checkout_method from your server with the item’s SKU and return the result to the frontend. The response indicates whether Truemed should be shown as a checkout option for that item. This endpoint evaluates item type only—it does not account for prices, discounts, or additional charges.

Because this call requires your Truemed API credentials, it must never be made directly from the browser.

Server (your backend):

1
// Example: Express route
2
app.get('/api/truemed/eligibility', async (req, res) => {
3
  const { sku, name } = req.query;
4
  const response = await fetch('https://api.truemed.com/api/v1/product_catalog/truemed_checkout_method', {
5
    method: 'POST',
6
    headers: { 'X-Truemed-Api-Key': process.env.TRUEMED_API_KEY, 'Content-Type': 'application/json' },
7
    body: JSON.stringify({ items: [{ sku, name }] }),
8
  });
9
  const { enabled } = await response.json();
10
  res.json({ enabled });
11
});

Client (your storefront):

1
const { enabled } = await fetch(
2
  `/api/truemed/eligibility?sku=${product.sku}&name=${encodeURIComponent(product.name)}`
3
).then(r => r.json());
4
5
if (enabled) {
6
  document.getElementById('truemed-widget-slot').innerHTML =
7
    '<div id="truemed-instructions"></div>';
8
}

Single-page application (SPA) support

For SPAs where the product page re-renders client-side without a full navigation, call reloadWidget() after the new product loads to reinitialize the widget:

1
if (window.TruemedProductPageLib) {
2
  window.TruemedProductPageLib.reloadWidget();
3
}

Configuration options

The placeholder element accepts the following attributes:

1
<div
2
  id="truemed-instructions"
3
  icon-height="16"
4
  dark-mode
5
  data-enable-debugging="true"
6
></div>