> This page is for version v1 (default). > For other versions, use one of these documentation indexes: > - v1 (default): https://docs-dev.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://docs-dev.truemed.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.truemed.com/_mcp/server. # Subsequent orders > Follow one customer's later boxes, call by call: two calls per order, the backup card, and what to do when HSA/FSA funds run out. Once the first order is charged, every later order takes **two calls**: an eligibility read and a charge. There is no survey, no new card entry, and no wait. This lasts for the life of the LMN, 12 months. ## How every later order flows Jamie Rivera is back for the next box after the [first order](/v-1/guides/get-started/use-cases/medically-tailored-meals/first-order), on whatever cadence your plan uses for picking meals, typically weekly. Jamie has an approved LMN and a stored payment token. Payloads are trimmed; the full versions are in [API calls](/v-1/guides/get-started/use-cases/medically-tailored-meals/api-calls). A dotted underline in the progress bar marks a step that Truemed runs. ### 1. You read Jamie's eligibility 1Read eligibility — 2Pick meals — 3Charge — 4Split & receipt Your backend · no new customer screen **What you do:** Read eligibility by payment token, and cache the answer until your menu changes, a [`payment_token.updated`](/v-1/api-reference/payment-tokens/payment-token-updated-webhook) arrives, or `lmn_expires_at` passes. Nothing yet. Jamie has not opened the menu. [`GET /api/v1/eligibility/token/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42`](/v-1/api-reference/eligibility/retrieve-token-eligibility) returns: ```json { "eligibility_status": "approved", "items": ["salmon-teriyaki-bowl", "chicken-pesto-plate", "protein-breakfast-box"], "lmn_expires_at": "2027-08-06" } ``` The status is `approved` now, so `items` is final rather than pre-qualified. ### 2. Jamie picks meals, or the week rolls over ✓Read eligibility — 2Pick meals — 3Charge — 4Split & receipt ![Meal selection page with HSA/FSA Eligible badges on meals](/_fern-files/_img/210024f278dfe019aa8067fde25d0a4bec2b67426af681b3821371bc7e44c6d5.webp) Your page What the customer sees This week's menu, badged from Jamie's Truemed eligibility. Jamie picks the next box, skips the week, or lets your plan pick eligible meals automatically. What you do Badge the meals in `items`. If Jamie never visits, keep the box you would have sent anyway; step 3 is identical either way. The payment breakdown works the same as on the first order, without the "if approved" caveat. Jamie's box, with the illustrative comparable amount of \$6.00: | Line | Price | Personal card | HSA/FSA card | | --------------------- | ----------: | ------------: | -----------: | | Salmon teriyaki bowl | \$14.50 | \$6.00 | \$8.50 | | Chicken pesto plate | \$14.50 | \$6.00 | \$8.50 | | Protein breakfast box | \$12.00 | \$6.00 | \$6.00 | | **Meals total** | **\$41.00** | **\$18.00** | **\$23.00** | Shipping, tax, and discounts follow the meals. Truemed splits order-level amounts across the two cards in proportion to the eligible share of the meals, and an amount you send on a specific line stays with that line. Nothing about this is specific to MTM. See [Key rules to know](/v-1/guides/get-started/use-cases/medically-tailored-meals/overview#key-rules-to-know) for how the split works, and [Reading the comparable amount](/v-1/guides/get-started/use-cases/medically-tailored-meals/api-calls#reading-the-comparable-amount) for where the numbers come from. ### 3. You charge the box at cutoff ✓Read eligibility — ✓Pick meals — 3Charge — 4Split & receipt Your fulfilment worker · no new customer screen **What you do:** Charge the final box against the stored token at order cutoff, before it ships. Nothing, whether Jamie is on your site or not. [Create Payment Session](/v-1/api-reference/payment-sessions/create-payment-session): ```http POST /payments/v1/create_payment_session { "payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42", "total_amount": 4100, "order_items": [ { "item_id": "salmon-teriyaki-bowl", "name": "Salmon teriyaki bowl", "price": 1450, "quantity": 1 } // …every line in the box ] // …plus the required fields listed in API calls } ``` An attended order and an unattended weekly rollover send exactly this call. A meal that is not in `items` goes to the personal card rather than blocking the order, so a recurring charge never needs Jamie in a browser. The response echoes `lmn_expires_at`, so you have the date even if you skip step 1. Charging at cutoff, not at shipping, leaves days to recover if a card declines. See [When HSA/FSA funds run out](#when-hsafsa-funds-run-out). ### 4. Truemed splits the charge and sends the receipt ✓Read eligibility — ✓Pick meals — ✓Charge — 4Split & receipt Truemed · no new customer screen **What you do:** Ship the box. An itemized receipt showing what went to each card. Truemed classifies each line, splits the total across the two cards, and authorizes. See [The personal card is the backup](#the-personal-card-is-the-backup) for what the personal card carries. ## The personal card is the backup Every MTM order is a split, so Jamie's personal card is already on file. It **always** carries: * **The comparable amount** on every eligible meal. * **Meals that are not in `items`.** They go to the personal card instead of blocking the order. * **Every line after the LMN lapses.** It carries the HSA/FSA share **only if you enable auto-retry**: * **A short HSA/FSA balance.** With auto-retry on, Truemed moves the shortfall to the personal card. With it off, the charge fails. Other HSA/FSA declines fail either way. See [When HSA/FSA funds run out](#when-hsafsa-funds-run-out). ## When something changes Most weeks are steps 1 to 4. Three events break the routine. ### When HSA/FSA funds run out If Jamie's HSA/FSA card is short on funds or only partially approves, what happens depends on whether you enable **auto-retry on the backup card**. It is opt-in: ask your Truemed contact to turn it on. Both choices need some buildout on your side. #### Auto-retry on Truemed moves the shortfall onto Jamie's personal card within the same charge. You make no second call; the charge succeeds and the box ships. Jamie's itemized receipt shows what went to each card. Auto-retry covers only a short balance or a partial approval. Any other HSA/FSA decline, such as an expired card or a fraud block, fails as in the **Auto-retry off** tab. A small shortfall on a box with no personal-card amount can also fail, when it is below the processor's minimum charge. If the personal card also declines, the charge fails with a `422` ([Create Payment Session](/v-1/api-reference/payment-sessions/create-payment-session)). Handle it as in the **Auto-retry off** tab. #### Auto-retry off The charge fails. Create Payment Session returns HTTP `422`: ```json { "next_action": "UpdatePaymentMethod", "redirect_url": "https://dev.truemed.com/..." } ``` Choose one path, and build it: * **Move Jamie to your own payment rails** for this order, or * **Get Jamie to update the payment method:** 1. **Get Jamie to the link.** If Jamie is on your site, open it in an iframe, as at signup. If not, email it. Card data still never reaches your servers. 2. **Wait for [`payment_token.updated`](/v-1/api-reference/payment-tokens/payment-token-updated-webhook).** It arrives with the same token and refreshed `payment_methods` once Jamie saves a new card. 3. **Resubmit the same Create Payment Session call with the same idempotency key.** Truemed does not resubmit the order for you. > **Note** > > **The time between cutoff and shipping is your retry window.** You decide what happens to the box if Jamie > has not fixed the card by then: ship it, hold it, or skip the week. `payment_methods` on every token > webhook carries each card's expiry date, so you can also prompt Jamie before a card fails. ### Your menu changes New meals usually do **not** send Jamie back to the survey. The survey qualified Jamie against your whole eligible catalog, so none of these trigger a new one: choosing different meals, adding a meal Jamie has never ordered, skipping or pausing weeks, or ordering a meal that is not covered. Clear your cached eligibility read and read it again (step 1); new meals that fit Jamie's answers appear in `items`. The one exception: **new meals that address a dietary need the original survey never asked about.** Jamie's answers cannot cover questions the survey did not ask, so those meals stay off Jamie's `items`. Either send existing customers a [fresh survey link](#getting-a-fresh-survey-link), or let those meals charge to the personal card for them while new customers pick them up at signup. ### The LMN expires Jamie's LMN lasts 12 months, until `lmn_expires_at` (`2027-08-06`). **To keep paying with HSA/FSA after that date, Jamie has to requalify** by taking the health survey again and getting a new practitioner decision. Nothing renews automatically. * **Before expiry:** use `lmn_expires_at` to prompt Jamie to requalify, on whatever lead time suits your lifecycle messaging, and send Jamie back to the survey with a [fresh survey link](#getting-a-fresh-survey-link). * **After expiry, until Jamie requalifies:** orders keep shipping, but the [personal card](#the-personal-card-is-the-backup) carries every line, including meals that were HSA/FSA-eligible. Tell Jamie why the split changed. ## Getting a fresh survey link A customer requalifies on the payment token they already have. Call [Update Payment Token](/v-1/api-reference/payment-tokens/update-payment-token) with `renew_eligibility` set to `true`. You do not need an order or a payment session, and the call does not charge the customer. ```http POST https://dev-api.truemed.com/api/v1/payment_tokens/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42/update x-truemed-api-key: Content-Type: application/json { "renew_eligibility": true, "success_url": "https://www.example.com/hsa/complete", "failure_url": "https://www.example.com/hsa/cancelled", "use_iframe": true } ``` `failure_url` fires as it does at signup: the customer opts out of HSA/FSA, does not qualify in the survey, or cancels a card update. Do not send `order_items`. Your channel qualifies the customer against the whole catalog, so the `order_items` requirement in the subscriptions guide does not apply. The response tells you whether the customer needs a survey: | Customer's LMN | `next_action` | `redirect_url` | | -------------------------------------------------- | ------------------ | ----------------------------------------------------------- | | None, rejected, expired, or expires within 30 days | `TakeHealthSurvey` | The survey URL. Embed it the same way as the signup survey. | | Approved, and more than 30 days from expiry | `None` | Absent. The customer needs no survey. | If you call again while the customer is in the middle of the survey, Truemed returns the same survey, and the customer keeps the answers they already gave. Orders keep charging the regular card until a new LMN is in place. > **Warning** > > Set `renew_eligibility` to `true` whenever you want a survey link. An update without it changes only the > fields you send, such as `metadata`, and does not return a survey. ## What your integration needs Before you build later orders, confirm you can: * [ ] Read eligibility by token and clear the cache when your menu changes, a token webhook arrives, or `lmn_expires_at` passes. * [ ] Charge every box at order cutoff, attended or not, with [Create Payment Session](/v-1/api-reference/payment-sessions/create-payment-session) and the stored token. * [ ] Choose auto-retry on or off with your Truemed contact, and build the matching flow: an update or your-own-rails path for any charge that fails. * [ ] Handle a `422` with `UpdatePaymentMethod`: show or email the link, then resubmit with the same idempotency key after [`payment_token.updated`](/v-1/api-reference/payment-tokens/payment-token-updated-webhook). * [ ] Decide what happens to a box whose card is still unfixed at shipping.