For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGuidesAPI Reference
HomeGuidesAPI Reference
  • Payment Sessions
    • Payments Overview
    • Manual/Delayed Capture
    • Itemized Fees and Discounts
  • Implementation
    • Stripe Custom Payment Method
    • iFrame Payment Session
  • Product Catalog
    • Overview
    • Managing Your Catalog
  • Qualification Sessions
    • Update a Qualification Session
  • Direct Substantiation
    • Overview
    • TPA Guide
    • Employers Guide
    • Platforms Guide
  • Subscriptions
    • Overview
    • Create a Subscription (New Subscriber)
    • Create a Subscription (Existing Subscriber)
    • Subsequent Billing Periods
    • Partner Administrative Operations
  • Resources
    • Webhooks
    • Developer Tools
LogoLogo
On this page
  • Why it matters
  • How it works
  • Eligibility statuses
  • Related guides
Product Catalog

Product Catalog Overview

Was this page helpful?
Previous

Build HSA/FSA-Eligible Collections

Next
Built with

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

1

Submit your SKUs

Call create_catalog_item for each product, or bulk-upload via your Truemed Partner Dashboard.

2

Truemed evaluates eligibility

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

3

Receive the result via webhook (recommended)

When a product’s eligibility status is determined or updated, Truemed sends a product_catalog_item_eligibility_updated 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 at cart assembly time to evaluate eligibility in real time—no stored status or webhook required.

4

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:

StatusMeaning
eligibleThe item is eligible for HSA/FSA spending without a Letter of Medical Necessity.
eligible_with_lmnThe item may be eligible for qualified individuals with a doctor-issued Letter of Medical Necessity.
ineligibleThe item is not eligible for HSA/FSA spending.
nullThe 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
  • Conditionally Show the PDP Widget
  • Checkout Page Messaging
  • Managing Your Catalog via API