> 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.

# Overview

> How the Product Catalog API classifies your SKUs for HSA/FSA eligibility and powers storefront integrations.

The Product Catalog API enables merchants to submit SKUs to Truemed for HSA/FSA eligibility
evaluation and tracking. Once Truemed classifies a product, that eligibility data powers a richer
storefront experience—surfacing Truemed as a payment option only where it's relevant and keeping
customers informed.

## Why it matters

Not all products are eligible for HSA/FSA spending. By keeping Truemed up to date on your catalog,
merchants unlock a richer set of integrations:

* **Eligible collections** — Tag and group your HSA/FSA-eligible products for dedicated landing
  pages, email campaigns, or storefront filters.
* **PDP widget** — Conditionally show or hide the Truemed widget on product detail pages based on
  each product's eligibility status.
* **Checkout messaging** — Display "Pay with your HSA/FSA" copy on the checkout page only when the
  cart contains eligible items.
* **Accurate checkout decisions** — Prevent customers from being sent to a Truemed flow for a cart
  that won't qualify.

## How it works

#### Submit your SKUs

Call [`create_catalog_item`](/api-reference/product-catalog/create-item) for each product,
or [bulk-upload via your Truemed Partner Dashboard](/guides/troubleshooting/sku-upload).

#### Truemed evaluates eligibility

Truemed reviews and classifies each item. This happens asynchronously after submission—
classification is not immediate.

#### Receive the result via webhook (recommended)

When a product's eligibility status is determined or updated, Truemed sends a
[`product_catalog_item_eligibility_updated`](/api-reference/product-catalog/item-eligibility-updated-webhook)
webhook with the classification result. Store this status to power collections, PDP widgets,
and more.

**OR:** For checkout page messaging only, call
[`check_truemed_checkout_method`](/api-reference/product-catalog/truemed-checkout-method)
at cart assembly time to evaluate eligibility in real time—no stored status or webhook required.

#### Use the eligibility data

Use stored eligibility statuses or real-time API responses to power the storefront
experience—collections, PDP widgets, checkout messaging, and more.

## Eligibility statuses

Each catalog item will receive one of the following statuses:

| Status              | Meaning                                                                                                                      |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `eligible`          | The item is eligible for HSA/FSA spending without a Letter of Medical Necessity.                                             |
| `eligible_with_lmn` | The item may be eligible for qualified individuals with a doctor-issued Letter of Medical Necessity.                         |
| `ineligible`        | The item is not eligible for HSA/FSA spending.                                                                               |
| `null`              | The item has been submitted and is awaiting review. The `eligibility` field will be `null` until classification is complete. |

## Related guides

* [Build HSA/FSA-Eligible Collections](/guides/setup/api/product-catalog/use-cases/build-hsa-fsa-eligible-collections)
* [Conditionally Show the PDP Widget](/guides/setup/api/product-catalog/use-cases/conditionally-show-the-pdp-widget)
* [Checkout Page Messaging](/guides/setup/api/product-catalog/use-cases/checkout-page-messaging)
* [Managing Your Catalog via API](/guides/setup/api/product-catalog/managing-your-catalog)