Subsequent orders

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, 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. A dotted underline in the progress bar marks a step that Truemed runs.

1. You read Jamie’s eligibility

GET /api/v1/eligibility/token/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42 returns:

{
  "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

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:

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 for how the split works, and Reading the comparable amount for where the numbers come from.

3. You charge the box at cutoff

Create Payment Session:

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.

4. Truemed splits the charge and sends the receipt

Truemed classifies each line, splits the total across the two cards, and authorizes. See 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 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.

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, 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.
• After expiry, until Jamie requalifies: orders keep shipping, but the personal card 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 with renew_eligibility set to true. You do not need an order or a payment session, and the call does not charge the customer.

POST https://dev-api.truemed.com/api/v1/payment_tokens/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42/update
x-truemed-api-key: <your 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:

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.

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 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.
• Decide what happens to a box whose card is still unfixed at shipping.