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.
This guide covers the most common Shopify-specific issues merchants encounter with Truemed, including payment visibility, order management, manual capture, and theme changes.
Payment Option Not Showing at Checkout
If your customers can’t see the Truemed payment option at checkout, check the following:
1. Confirm the App Is Activated
Go to Shopify Admin > Settings > Payments
Look for “Truemed” under Additional payment methods
If it’s not listed, you may need to reinstall or activate it. See the Shopify Setup Guide article.
2. Check That Products Have Approved SKUs
If a product hasn’t been reviewed by Truemed’s compliance team, it will default to ineligible at checkout. Upload your latest product catalog through the Truemed Dashboard.
See the SKU Upload troubleshooting article for details.
3. Ensure the Customer Is Checking Out as Guest
Truemed’s payment option does not appear when customers use Shop Pay or accelerated checkout. Customers must select “Guest checkout” to see Truemed as a payment method.
4. Verify Stripe Account Status
Your Stripe account must be at least Enabled for the payment app to work. Check your Stripe connection status in your onboarding plan or contact merchants@truemed.com.
5. Check Geographic Restrictions
Truemed is currently available to US customers only. If a customer’s billing or shipping address is outside the US, the Truemed option may not appear.
Missing Orders in Shopify
Truemed orders are processed through our payment system, not through Shopify’s standard payment flow. Here’s what to know:
Truemed orders do appear in Shopify but may behave differently from standard orders
Orders start in a “Pending” state until a Letter of Medical Necessity (LMN) is issued
Status transitions can take a few hours, and this is normal
Manual capture is a Shopify setting that allows you to authorize a charge but delay the capture (collection) of funds until later. Some merchants use this for preorders or custom fulfillment workflows.
Truemed is optimized for automatic capture, which is Shopify’s default.
How to Check Your Capture Setting
Go to Shopify Admin > Settings > Payments
Look for Payment capture method
If set to “Automatically capture payment for orders”, you’re all set. No action needed.
If You Use Manual Capture
Manual capture works with Truemed, but requires special attention because Truemed orders have unique status transitions:
The Manual Capture Flow
Order created: Customer places order through Truemed. Payment is authorized but not captured.
LMN review: The order remains in “Pending” state while the health survey is reviewed.
LMN issued: Order transitions to “Authorized” status (this can take several hours).
Capture window: You must capture payment within 5 days of authorization, or it expires.
Payment captured: Order moves to “Paid” and is ready to fulfill.
How to Capture Payment
Bulk capture: From the Shopify Orders list, select eligible orders and use bulk actions
Individual capture: Open the order and click “Capture payment”
You can only capture payment once per order. Partial captures are not supported.
Common Manual Capture Issues
Issue
Cause
Solution
Missed captures
Automation ran before the order transitioned to “Authorized”
Add retry logic to check for delayed status changes
Expired authorization
Payment not captured within 5 days
Customer must re-place the order. Expired authorizations cannot be recovered.
False fraud flags
Fraud detection ran before order reached “Paid” status
Wait for correct status before fraud evaluation
Recommended: Shopify Flow for Auto-Capture
If you want to use manual capture but still auto-capture Truemed orders, create a dedicated Shopify Flow:
Trigger: Order payment status changes
Condition: Payment gateway contains “Truemed” AND order is “Authorized”
Action: Capture payment
A downloadable example Shopify Flow template is available. Reach out to merchants@truemed.com to request it. Test thoroughly in your specific environment before going live.
Theme Changes
Will changing my Shopify theme affect Truemed?
Payment app: No. The Truemed payment integration is independent of your theme.
Product page widget: Yes. If you switch themes, you’ll need to re-add the PDP widget to your new theme template. See the Shopify Setup Guide article for installation instructions.
Thank You page widget: If using the Truemed Extensions app (Checkout Extensibility), no action is needed. If using Additional Scripts, verify your scripts are still in place after the theme change.
Refunds for Truemed Orders
Shopify merchants using the Truemed payment integration process refunds through Shopify’s standard refund flow, the same way you’d refund any other order:
Open the order in Shopify Admin and click Refund
Refund amounts are deducted from your Stripe payout balance
Processing time follows standard Stripe timelines
If you run into an issue refunding a Truemed order in Shopify, contact merchants@truemed.com.
Merchants on the post-purchase reimbursement flow (not Shopify’s payment integration) process refunds through the Truemed Dashboard instead.
Quick Troubleshooting Checklist
Symptom
First Thing to Check
Truemed not showing at checkout
App activated? Stripe enabled? Customer using Guest checkout?
Order stuck in “Pending”
LMN review in progress. Check Truemed Dashboard for status
Can’t capture payment
Is the order “Authorized”? Has the 5-day window expired?
Product showing as ineligible
Upload latest SKU list via Truemed Dashboard
Widget not appearing on product page
Check theme template. Widget may need to be re-added after a theme change
