> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.truemed.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.truemed.com/_mcp/server. # Subsequent orders > The steady state: two calls per order, the two-card split, expiring cards, requalification, and what lmn_expires_at is for. ## How every later order flows Customer MTM Merchant Truemed 1 You ask what this customer may put on their HSA/FSA card, and badge your menu accordingly. Refresh the answer whenever your menu changes. returns eligibility\_status + items + lmn\_expires\_at 2 Customer comes back, typically once a week, and picks the meals for the next box, skips the week, or leaves it as it stands. 3 You charge the final basket against the stored token. This works identically whether the customer is on the site or the week rolls over unattended. POST /payments/v1/create\_payment\_session 4 Truemed classifies each line, splits the total across the two cards, authorizes, and returns the outcome, with the expiry date echoed again. 5 Box ships. Itemized receipt goes out. No new survey and no new card entry. Two calls per order. This is the steady state for the life of the LMN. ## The split: how a charge lands on two cards Every charge in this flow splits. Because food is only partially eligible for HSA/FSA spend, even a meal the LMN covers puts only part of its price on the benefits card, and the rest goes to the regular credit or debit card. On top of that, some meals fall outside what the LMN covers, and those lines go entirely to the regular card. Truemed does **not** block an order for an uncovered line, and does **not** ask the customer to take another survey. One call, one order, two cards. ### Comparable meals: why the split is fixed per meal The eligible portion of a meal is not a percentage. HSA/FSA rules let a customer pay for the added cost of a medically tailored meal over an ordinary one, so every meal carries a **comparable amount**: the price of an equivalent grocery-store meal, which is the part that is never HSA/FSA-eligible and always lands on the regular card. The HSA/FSA-eligible amount is the meal price minus that comparable amount. Two consequences follow, and both matter for what you show the customer: * **Every order is a split, always.** The comparable amount is greater than zero, so the regular card always carries at least the comparable amount times the number of meals. There is no all-HSA/FSA order in this flow. * **The comparable amount is a fixed dollar figure per meal, not per dish.** A meal is a meal, so one comparable amount typically applies across your whole menu regardless of which eligibility category a dish falls in. A distinct product line can carry its own comparable amount (a higher-cost line such as high-protein meals, for example), but within a line it is a single number. The catalog reads return the comparable amount as `comparable_item_price_cents`, in cents per meal. Both [`get_catalog_item`](/api-reference/product-catalog/get-item-detail) and [`list_catalog_items`](/api-reference/product-catalog/list-catalog-items) include it on each item. For a single line, the regular card carries `comparable_item_price_cents × quantity`, up to the line total, and the HSA/FSA card carries the rest. Sum across lines for the order estimate. Truemed omits `comparable_item_price_cents` for an ineligible meal, a meal still awaiting review, and a meal with no comparable product on file. A missing comparable amount is not a zero deduction. Those lines go entirely to one card, so read the `eligibility` field alongside it. Truemed reviews comparable amounts about monthly. The catalog eligibility webhook carries the comparable amount as of each delivery, but a reprice triggers no delivery and does not advance `updated_at`. Re-read the full catalog at least monthly. Truemed settles the charged amount at checkout. **Truemed has no screen that shows this split to the customer**, so if you want to show an estimate at selection or confirmation, you compute it from the comparable amount and the meal count on your side. That routing is what makes unattended charging possible: | Cart | What happens | Why it matters | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Attended**: customer is on your site choosing meals | You already know which items are covered from the eligibility read, so you can badge the menu and show the customer which lines will land on which card before they confirm. | No surprises at confirmation. The split you display and the split Truemed charges are computed from the same eligibility data. | | **Unattended**: weekly rollover, no browser session | Exactly the same call, exactly the same split. Uncovered lines go to the regular card automatically. | Because an uncovered item routes rather than blocks, a recurring charge **never** needs to bounce the customer into a browser to fix something. | ### When the HSA/FSA card cannot cover the eligible portion A separate case, and the one you cannot see coming: the items are covered, but the account is short. If the HSA/FSA card partially authorizes or declines for insufficient funds, **the unfunded remainder folds onto the regular card inside the same authorization**, with no second call, no orphaned hold, and no customer action. From your side the charge succeeds; the receipt shows where each dollar went. The trade-off is that the customer needs to be told before it happens rather than discovering it on their statement. Per-item disclosure at selection and at confirmation, plus the itemized receipt Truemed sends, covers it. Exact customer-facing wording is out of scope for this guide. Your Truemed contact will share a short messaging guide that specifies the phrasing for each of these moments. ## Expiring cards: charge before the box ships, and the update link closes the loop Cards expire, get reissued, and get replaced after fraud. When *both* stored cards fail to authorize, the charge has nowhere to fold, and this is the one recurring-flow case where the customer has to act. The design absorbs it with timing rather than interruptions: **charge each box at order cutoff, before it ships.** The first order already works this way for a different reason (it waits for the token); every later order should be charged synchronously at cutoff too, while there is still lead time in the week. When a charge fails this way, the same `create_payment_session` response tells you what to do next: `next_action: UPDATE_PAYMENT_METHOD` plus a `redirect_url` for the card-replacement page. It is the same Truemed-hosted page family as signup, embedded the same way, so card data never touches your servers. Getting the customer in front of that frame is your side of the loop, and it works in both of your worlds: * **Customer is on your site:** open it in a frame right there in the session, exactly as at signup. * **Meals were picked for them**, with no browser session: email them the link. You hold the current address, and this is exactly the nudge your lifecycle messaging already does well. Once the customer saves a new card, Truemed fires `payment_token.updated` again, with the same token and refreshed `payment_methods`. That is your signal to **re-submit the same `create_payment_session`**: Truemed never retries a charge on its own. Re-using the original idempotency key is safe and correct, because it re-attempts the held charge rather than creating a second one. > **Note** > > **The cutoff-to-ship window is your retry budget.** Because the decline surfaces synchronously at > cutoff, you know days before the box must ship. That window is how long the customer has to fix the > card before you decide what to do with the box: ship on whatever authorized, hold it, or skip the week. > That policy is yours, and the loop above supports all three. > > The `payment_methods` snapshot on every token webhook carries each card's expiry date, so you can also > see an expiring card coming and prompt the customer *before* the first failure. Ask us for the on-demand > update link if you want to build that. ## Requalification: an annual event **Between annual renewals, your customers should not need to requalify.** The health survey a customer takes at signup qualifies them against *your whole eligible catalog*, meaning every meal Truemed's clinical team has classified as potentially HSA/FSA-eligible, rather than against the basket they happen to be holding at that moment. Meals outside that set always charge to the regular card. Concretely, none of the following triggers a new survey: * Choosing different meals this week than last week * Adding a meal they have never ordered before * Skipping weeks, pausing, or resuming * Ordering a meal that turns out not to be covered, which simply routes to the regular card There is one case where an existing customer would need to take a survey again: **you add meals that address a dietary need the original health survey never asked about, and you want existing customers to be covered for them.** New clinical ground means new survey questions, and there is no way to answer them retroactively. Even then it is your call: you can also let the new meals route to the regular card for existing customers, and let the next cohort pick them up automatically at signup. > **Tip** > > **Worth flagging early:** the smaller and more stable the clinical ground your menu spans, the simpler > this stays for everyone. Our clinical guidance is to keep it as small as the catalog honestly allows. ## `lmn_expires_at`: how long the decision holds An LMN is valid for 12 months. Truemed returns the expiry date on the eligibility read *and* echoes the same date on every payment session response, so you have it on the one call you make every week even if you never call the eligibility endpoint. It does two jobs: * **It bounds how long the decision holds.** The practitioner's decision for this customer stands until this date, after which coverage lapses and charges route to the regular card. * **It is your renewal trigger.** Use it to prompt the customer to requalify ahead of expiry, on whatever lead time suits your lifecycle messaging: 30 days, 14 days, two nudges, your call. You know your customers' cadence better than we do. > **Warning** > > **Do not cache `items` until `lmn_expires_at`.** The decision holds until that date, and the item list > does not: a meal you add to the menu next month can be relevant to a customer who qualified last month, > and a cached list would keep badging only the old menu. **Refresh the eligibility read whenever your menu > changes**, and re-badge from the response. A short cache between menu changes is fine. If an LMN does lapse, nothing breaks: the customer's orders keep shipping and simply charge to the regular card until a new LMN is in place.