> 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 > Step-by-step guide to installing and configuring Truemed on your Shopify store. This guide walks you through installing and configuring Truemed on your Shopify store, from prerequisites through a final verification pass. A video walk through of the process to install the payment app can be found [here](https://www.loom.com/share/449ca418ea6b4210a4f394201a50e53a). --- ## Prerequisites Complete these before your onboarding call so nothing blocks activation. * [ ] **Upload your product catalog.** Export your **active** Shopify products as a Plain CSV file, with a SKU on every variant. See [SKU upload](/guides/troubleshooting/sku-upload) for the export steps. * [ ] **Complete Stripe onboarding.** This connects the bank account Truemed pays out to. See [Stripe onboarding and payouts](/guides/get-started/stripe-onboarding). * [ ] **Shopify account owner or admin permissions.** Required to install and manage third-party payment apps. --- ## Step 1: Install the Truemed Payments App Installation typically happens live during your onboarding call with your Truemed contact. 1. Open the [Truemed app listing](https://apps.shopify.com/truemed) on the Shopify App Store 2. Review the app permissions and click **Install** ![Shopify install app permissions dialog for Truemed](/_fern-img/bbc042fbe3721640457b8ac38187de5427827be74746fc7b7fcae992a96111e7.webp) 3. Most merchants are still logged in from their initial account setup and will land on an onboarding checklist. Click **Connect Store** > **Note** > > If you are not already logged in, do not create a new account. Click **Login** at the bottom of the page and sign in to the account you already have. ![Truemed account login screen](/_fern-img/064861fe7aa58cda3fa99a18f53111b79e783c65c774384556c331bd7436df58.webp)![Connect Store button on the onboarding checklist](/_fern-img/6062d367861a38ec03067619e706ceac9078d1ea7cdeb7bf4e0c881efcbaa603.webp) 4. Click **Go to Shopify Admin**. You'll land on the Truemed app settings page ![Go to Shopify Admin button](/_fern-img/55c15908b05fd19a3bf4ddcfdb713ff25d5f3a47e35aad41ff6b277d10168fa1.webp) > **Warning** > > **Do not activate the app yet** if your Truemed coordinator has instructed you to wait. You'll be told when it's time to activate. --- ## Step 2: Activate the Truemed Payments App Once your Truemed account is configured and your products have been categorized: 1. Return to the app settings page (or navigate to **Settings > Payments > Additional payment methods** and search for "Truemed") 2. Click **Activate** The app shows an **Active** badge once it's live. ![Truemed Payments App settings page showing the Active status](/_fern-img/5d5e6da670ab7240443b09788789a975e51a79d5c6e0aedadfeea761080b4e5e.webp) > **Note** > > After activation, the Truemed payment option is live immediately. Customers can begin checking out with HSA/FSA funds right away. To enable, disable, or uninstall the app later, see [Manage the Truemed Payments App](/guides/setup/shopify/manage-payment-app). --- ## Step 3: Add the product page widget The product page widget tells customers a product may qualify for HSA/FSA spending while they're deciding whether to buy. It's the highest-impact promotion you can add. Full installation, dark mode, tag-based visibility, and styling options are on the [product page widget](/guides/setup/shopify/widgets) page. To carry the same message into checkout, install the [Truemed Extensions App](/guides/setup/shopify/extensions-app) and add its HSA/FSA checkout widgets. The app also syncs your catalog to Truemed and shows each variant's eligibility in your Shopify admin. --- ## Step 4: Set up reimbursements (subscription and hybrid merchants only) The Truemed Payments App doesn't support subscription carts. If you sell subscriptions, set up the post-purchase reimbursement flow: the qualification link on your thank you page and your order status page, plus the confirmation email link. See [Subscriptions and reimbursement setup](/guides/setup/shopify/subscriptions). Skip this step if you only sell one-time products. --- ## Step 5: Verify your setup After completing setup, run through these checks: * [ ] Visit a product page and confirm the HSA/FSA widget appears * [ ] Start a test checkout and verify "Truemed" appears as a payment option * [ ] Open a product variant in Shopify and confirm the **HSA/FSA Eligibility** field shows a value ([Truemed Extensions App](/guides/setup/shopify/extensions-app) only) * [ ] Place a test order and verify it appears in your [Truemed dashboard](https://app.truemed.com) * [ ] Check your thank you page and your order status page for the qualification link (if reimbursement flow is enabled) For a full walkthrough of placing test orders without charging real funds, see [How to test](/guides/setup/shopify/how-to-test). --- ## Need help? * **Technical issues:** [merchants@truemed.com](mailto:merchants@truemed.com) * **Dashboard access:** [app.truemed.com](https://app.truemed.com) * Refer to the [Shopify Issues](/guides/troubleshooting/shopify-issues) article for common issues