> 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.
# Setup guide
> How to set up Truemed's post-purchase reimbursement flow for subscription products, non-Shopify storefronts, or alongside direct HSA/FSA card payments.
This guide walks you through setting up Truemed's post-purchase reimbursement flow. This integration is for merchants who sell subscription products, want to offer HSA/FSA reimbursement alongside direct HSA/FSA card payments, or don't have a storefront on Shopify, BigCommerce or WooCommerce.
---
## How the reimbursement flow works
Instead of paying directly with an HSA/FSA card at checkout, your customers:
1. **Purchase normally** using any payment method on your site
2. **Complete a health survey** via a Truemed qualification link (shown post-purchase)
3. **Receive an LMN:** If eligible, a licensed provider issues a Letter of Medical Necessity within 24-48 hours.
4. **Submit for reimbursement:** The customer submits the LMN and receipt to their HSA/FSA administrator for reimbursement.
Each LMN covers the customer's eligible purchases for a **full year**, so they only need to qualify once annually.
> **Tip**
>
> Watch the [reimbursement flow walkthrough](https://app.trupeer.ai/view/cWXd99QzH) video for a step-by-step overview.
---
## Prerequisites
Before you begin setup:
* [ ] You've created your Truemed account at [app.truemed.com](https://app.truemed.com)
* [ ] You've uploaded your product catalog (CSV with Name, SKU, and Description columns)
* [ ] Your products have been reviewed and categorized by Truemed's compliance team
---
## Step 1: Create your Truemed account
If you haven't already, create your Truemed account using the link provided by your Truemed contact. This gives you access to the Truemed Dashboard, where you can:
* View **Qualifications** to see customer qualification activity and LMN status
* Manage **Settings** to add team members and update your payment method
* Upload **Products** to submit new products for eligibility review
---
## Step 2: Provide payment for LMN fees
Truemed charges a flat fee for each LMN issued through your qualification link. Fees are collected in batches every Thursday.
1. Go to [app.truemed.com/merchants/qualifications](https://app.truemed.com/merchants/qualifications)
2. Add a payment method (credit card)
3. Once saved, your **Qualification Link** will appear on this page
> **Warning**
>
> You are charged each time an LMN is issued. Do not place the qualification link on pre-purchase pages (landing pages, marketing emails, etc.). It should only appear **after** a customer has completed a purchase.
---
## Step 3: Add the qualification link to your post-purchase pages
This is the most important touchpoint. Showing the qualification link immediately after purchase gives customers the smoothest path to reimbursement.
> **Warning**
>
> **Put it on both post-purchase pages. Neither one is optional.** The **thank you page** is a single moment, and most shoppers are not ready to fill out a health survey the second they buy. The **order status page** is where they come back — often days later, when they are ready. Placing only the thank you link loses every one of those shoppers.
### Shopify stores: checkout extensibility (recommended)
If your Shopify store uses Checkout Extensibility:
1. Visit [apps.shopify.com/truemed-extensions](https://apps.shopify.com/truemed-extensions) and click **Install**
2. On the app home page, open the **Complete the reimbursement setup** card
3. In the checkout editor, add the **Thank You** block on the **Thank you** page
4. Switch the page dropdown to **Order status** and add the **Order Status** block
5. Save your changes, then confirm the app home page reads **2 of 2** reimbursement links
You do not need to enter a Public ID — Truemed sets it for you.
> **Tip**
>
> Each link has a **Display only for Subscription Orders** toggle in the checkout editor. Turn it on to show the qualification link only for subscription orders.
The same app adds HSA/FSA widgets to your checkout and keeps your catalog in sync with Truemed. See [Truemed Extensions App](/guides/setup/shopify/extensions-app).
### Shopify stores: additional scripts (legacy)
If you haven't migrated to Checkout Extensibility:
1. Find your Qualification Link at [app.truemed.com](https://app.truemed.com)
2. In Shopify, go to **Settings > Checkout > Additional Scripts**
3. Paste in the "Order status page" section:
```html
```
### Non-Shopify stores
Add a CTA on your post-purchase/order confirmation page:
```html
This order might be eligible for HSA/FSA reimbursement. Get Reimbursed.
```
---
## Step 4: Add the qualification link to your order confirmation email
This acts as a backup in case a customer misses the Thank You page. Add the link to your transactional order confirmation email template.
**Example snippet:**
```html
{% assign skus = "" %}
{% for line_item in order.line_items %}
{% assign skus = skus | append: line_item.sku %}
{% unless forloop.last %}
{% assign skus = skus | append: "," %}
{% endunless %}
{% endfor %}
This order might be eligible for HSA/FSA reimbursement. Qualify Here
```
---
## Step 5: Install the product page widget
The PDP widget informs customers about HSA/FSA eligibility directly on the product page. This is the highest-impact promotion you can implement.
1. Get your **Public Qualification ID** from [app.truemed.com/merchants/qualifications](https://app.truemed.com/merchants/qualifications)
2. Add this code near the "Add to Cart" or "Buy" button on your product pages:
```html
```
The widget auto-detects your merchant profile and displays the appropriate messaging for the reimbursement flow.
---
## Step 6: Add checkout messaging for subscriptions (Shopify, optional)
If you sell subscriptions through Shopify, add a checkout banner so customers know about the reimbursement opportunity before completing their order.
1. Install [Checkout Blocks](https://apps.shopify.com/checkout-blocks)
2. Create a Dynamic Content Block with a Banner template
3. Set display rule: show when any line item has a selling plan
4. Use this approved copy:
> **Title:** Save an average of 30% when you use your HSA/FSA funds through Truemed.
>
> **Content:** Once you've purchased, fill out the Truemed health intake form on your order confirmation page to check if you qualify for HSA/FSA reimbursement. HSA/FSA tax savings vary. Learn more at [truemed.com/disclosures](https://www.truemed.com/disclosures).
5. Limit publishing region to **United States**
6. Save and add the block to your checkout
---
## Reimbursement attribution (optional but recommended)
Track which customers are getting reimbursed and how they discover Truemed by adding query parameters to your qualification links.
### Source parameter
Indicates where the customer clicked the link. Use a different value for each placement:
```text
https://app.truemed.com/qualify/[QUALIFICATION_ID]?source=order_confirm
```
Common values: `email_receipt`, `order_confirm`, `email_payment_reminder`, `reactivate_campaign`
### User ID parameter
For more granular user-level attribution:
```text
https://app.truemed.com/qualify/[QUALIFICATION_ID]?source=order_confirm&user_id=customer@example.com
```
### SKU parameter
To tailor the health survey to specific purchased items (contact [merchants@truemed.com](mailto:merchants@truemed.com) to enable):
```text
https://app.truemed.com/qualify/[QUALIFICATION_ID]?skus=product123,product456
```
> **Note**
>
> All parameter values should be URL-encoded. Source and user_id values are reflected in the Truemed Dashboard and CSV reports.
---
## Verify your setup
* [ ] Visit a product page and confirm the HSA/FSA widget appears
* [ ] Complete a test purchase and verify the qualification link appears on the Thank You page
* [ ] Check your order confirmation email for the qualification link
* [ ] Log in to [app.truemed.com](https://app.truemed.com) and confirm your Qualifications tab shows activity
---
## Need help?
* **Account & setup support:** [merchants@truemed.com](mailto:merchants@truemed.com)
* **Customer support (for your customers):** [support@truemed.com](mailto:support@truemed.com)
* **Truemed Dashboard:** [app.truemed.com](https://app.truemed.com)