> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Conditionally show the PDP widget

> How to conditionally render Truemed's HSA/FSA widget on product pages based on real eligibility data.

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.

```html
<div id="truemed-instructions" style="font-size: 14px;" icon-height="12" data-public-id="{{ INSERT PUBLIC ID HERE }}"></div>
<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](/guides/setup/api/product-catalog/use-cases/build-hsa-fsa-eligible-collections)) and use it to conditionally render
the placeholder server-side or at page load.

```js
if (product.truemedEligibility === 'eligible' ||
    product.truemedEligibility === 'eligible_with_lmn') {
  document.getElementById('truemed-widget-slot').innerHTML =
    '<div id="truemed-instructions"></div>';
}
```

### Option 2: Use the checkout method endpoint

For a real-time eligibility check, call
[`check_truemed_checkout_method`](/api-reference/product-catalog/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):**

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

**Client (your storefront):**

```js
const { enabled } = await fetch(
  `/api/truemed/eligibility?sku=${product.sku}&name=${encodeURIComponent(product.name)}`
).then(r => r.json());

if (enabled) {
  document.getElementById('truemed-widget-slot').innerHTML =
    '<div id="truemed-instructions"></div>';
}
```

## 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:

```js
if (window.TruemedProductPageLib) {
  window.TruemedProductPageLib.reloadWidget();
}
```

## Configuration options

The placeholder element accepts the following attributes:

| Attribute               | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `data-public-id`        | **Required.** Your Truemed public ID, provided during onboarding.        |
| `icon-height`           | Sets the height (in px) of the Truemed logo in the badge. Default: `14`. |
| `dark-mode`             | Switches the logo to a white variant for dark backgrounds.               |
| `data-enable-debugging` | Set to `"true"` to enable console logging for initialization and events. |

```html
<div
  id="truemed-instructions"
  icon-height="16"
  dark-mode
  data-enable-debugging="true"
></div>
```