> 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.

# The first order

> Follow one customer through their first order, call by call: signup, the survey, a badged menu, a held order, the practitioner's decision, and the charge.

The first order is the only one that waits on Truemed. The customer signs up, picks meals, and places
the order without delay. **You hold that order unpaid until Truemed sends a valid payment token, then
charge it.** The customer never waits on a screen, and later orders reuse the token with no wait.

## How the first order flows

Every call below belongs to one example customer, Jamie Rivera (your customer ID `84213`), whose first
box has two eligible meals and a dessert that is not. Payloads are trimmed; the full versions are in
[API calls](/guides/get-started/use-cases/medically-tailored-meals/api-calls). A dotted underline in the
progress bar marks a step that Truemed runs.

### 1. Jamie chooses to pay with HSA/FSA

1Opt in — 2Survey & cards — 3Pick meals — 4Order held — 5Review — 6Charge

![Payment page with Pay with HSA/FSA selected](/_fern-files/_img/409383a18ccb3c9c9e8b23f31d53df391b731fb15d3578d1fd6ccf8422d9bb3c.webp)

Your page

What the customer sees

Jamie picks a plan, enters delivery details, and selects Pay with HSA/FSA at payment.

What you do

Call [Create Payment Token](/api-reference/payment-tokens/create-payment-token), store the returned `provision_token_request_id` on Jamie's record (it is how you match the decision back later), then open `redirect_url` in an iframe.

[`POST /api/v1/payment_tokens/create`](/api-reference/payment-tokens/create-payment-token) returns:

```json
{
  "provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
  "redirect_url": "https://dev.truemed.com/survey/6c2d9e41-7b83-4f52-a0d1-3ea95c6b8f27"
}
```

### 2. Jamie completes the survey and enters both cards

✓Opt in — 2Survey & cards — 3Pick meals — 4Order held — 5Review — 6Charge

![HSA/FSA card and personal card entry forms](/_fern-files/_img/b551340ff746eb84f41691d23f8cd2dbd978f6542f00bb79b7cde8bcf42db114.webp)

Truemed-hosted

What the customer sees

Truemed's health survey, then a form for an HSA/FSA card and a personal card, all inside your iframe. Card data never reaches your servers.

What you do

Wait for the frame to report it is done, then close it and send Jamie to the menu.

The frame posts `{ success: true }` to your page when Jamie finishes. See [Embedded checkout](/guides/setup/api/payment-sessions/i-frame-payment-session).

### 3. Jamie picks meals from a badged menu

✓Opt in — ✓Survey & cards — 3Pick meals — 4Order held — 5Review — 6Charge

![Meal selection page with HSA/FSA Eligible badges on meals](/_fern-files/_img/210024f278dfe019aa8067fde25d0a4bec2b67426af681b3821371bc7e44c6d5.webp)

Your page

What the customer sees

The menu, with HSA/FSA badges on the meals that fit Jamie's survey answers.

What you do

Read eligibility by provision request and badge the returned items. The practitioner has not reviewed the case yet, so the status is pending.

[`GET /api/v1/eligibility/provision_request/{provision_token_request_id}`](/api-reference/eligibility/retrieve-provision-request-eligibility) returns:

```json
{
  "eligibility_status": "pending",
  "items": ["salmon-teriyaki-bowl", "chicken-pesto-plate", "protein-breakfast-box"],
  "lmn_expires_at": null
}
```

`items` lists the meals Jamie is **pre-qualified** for, available right away. The final say comes later,
when a practitioner approves Jamie's LMN.

### 4. Jamie places the order, and you hold it

✓Opt in — ✓Survey & cards — ✓Pick meals — 4Order held — 5Review — 6Charge

Your order pipeline · no new customer screen

**What you do:** Accept the order without charging it. Mark it as waiting for the token and keep it in your fulfilment queue.

Jamie sees your order confirmation, ideally with an estimate of what goes on each card.

> **Warning**
>
> **Your pipeline must be able to hold a placed, unpaid order.** If it cannot, raise it with your Truemed
> contact before you build.

#### Showing the payment breakdown in the order summary

Confirmation is the natural place to show Jamie how the order will split. Build the estimate from two reads you already have:

* **Which meals are eligible:** `items` from the eligibility read in step 3.
* **The comparable amount per meal:** `comparable_item_price_cents` on each item from the
  [catalog read](/api-reference/product-catalog/list-catalog-items). Cache it, and re-read the catalog
  at least monthly.

For each line, an eligible meal puts `comparable_item_price_cents × quantity` on the personal card and the
rest on HSA/FSA. A meal that is not in `items` goes entirely on the personal card. Jamie's box, with an
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 |
| Chocolate lava cake (not eligible) |      \$6.50 |        \$6.50 |       \$0.00 |
| **Meals total**                    | **\$35.50** |   **\$18.50** |  **\$17.00** |

Three things are specific to the first order:

* **The estimate assumes approval.** Eligibility is still `pending` when Jamie confirms. If the
  practitioner declines, the whole order goes on the personal card, so word the estimate as "if approved".
* **Show it as an estimate, not a promise.** Truemed settles the exact split when you charge in step 6.
  If the HSA/FSA balance is short, the charge fails unless auto-retry is on; see
  [When HSA/FSA funds run out](/guides/get-started/use-cases/medically-tailored-meals/subsequent-orders#when-hsafsa-funds-run-out).
* **Truemed sends the final numbers.** Jamie's itemized receipt in step 6 shows what went to each card.

### 5. A practitioner reviews the case

✓Opt in — ✓Survey & cards — ✓Pick meals — ✓Order held — 5Review — 6Charge

Truemed review · no new customer screen

**What you do:** Wait for [`payment_token.updated`](/api-reference/payment-tokens/payment-token-updated-webhook). It arrives whether the practitioner approves or declines, so it is always your signal to charge.

Jamie has already left checkout. If the case is declined, Truemed emails Jamie directly.

#### Approved

```json
{
  "event_type": "payment_token.updated",
  "data": {
    "payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42",
    "provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
    "eligibility_status": "approved",
    "lmn_expires_at": "2027-08-06"
  }
}
```

Store `payment_token` on Jamie's record. Every later order charges against it.

#### Rejected

```json
{
  "event_type": "payment_token.updated",
  "data": {
    "payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42",
    "provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
    "eligibility_status": "rejected",
    "lmn_expires_at": null
  }
}
```

The token still arrives but covers nothing. Charge the same way; it all goes to the personal card.

### 6. You charge the held order

✓Opt in — ✓Survey & cards — ✓Pick meals — ✓Order held — ✓Review — 6Charge

Your fulfilment worker · no new customer screen

**What you do:** Charge the held order against the token. Truemed classifies each line and splits the total across the two cards.

The box ships, and Jamie gets an itemized receipt showing what went to each card.

[Create Payment Session](/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": 3550,
  "order_items": [
    { "item_id": "salmon-teriyaki-bowl", "name": "Salmon teriyaki bowl", "price": 1450, "quantity": 1 },
    { "item_id": "chicken-pesto-plate", "name": "Chicken pesto plate", "price": 1450, "quantity": 1 },
    { "item_id": "chocolate-lava-cake", "name": "Chocolate lava cake", "price": 650, "quantity": 1 }
  ]
  // …plus the required fields listed in API calls
}
```

Send every line in cents, including the dessert; Truemed works out the split. Jamie's next box starts
here, skipping steps 1 to 5. See [Subsequent orders](/guides/get-started/use-cases/medically-tailored-meals/subsequent-orders).

## What your integration needs

Before you build the first order, confirm you can:

* [ ] Store `provision_token_request_id` on the customer record at signup.
* [ ] Listen for the iframe completion message and close the frame.
* [ ] Badge the menu from the provision-request read.
* [ ] Hold a placed, unpaid first order in your fulfilment queue.
* [ ] Receive [`payment_token.updated`](/api-reference/payment-tokens/payment-token-updated-webhook) on a subscribed webhook endpoint and store the token.
* [ ] Charge the held order with [Create Payment Session](/api-reference/payment-sessions/create-payment-session) once the webhook lands, in either outcome.
* [ ] Recover a missed webhook. See [API calls](/guides/get-started/use-cases/medically-tailored-meals/api-calls#recovering-a-missed-webhook).