> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.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.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.truemed.com/_mcp/server.

# Upcoming first-order change

> Charge the first order as soon as the customer enters both cards, and read eligibility from the payment token alone.

Truemed is simplifying the first order for Medically Tailored Meals. You get a payment token you can charge as soon as
the customer finishes the survey and enters both cards. The Letter of Medical Necessity (LMN) review starts when you
place the first order, not before. Your integration keeps working without changes, and a few small updates let you
fulfill the first order without delays.

## Why this is better

* You can fulfill the first order without delays. Today you hold the first order until a practitioner reviews the
  case. After this change, you charge at your usual cutoff and the review runs alongside fulfillment.
* You read eligibility in one place. The payment token exists before the first order, so Retrieve Eligibility by
  Payment Token answers every eligibility question you used the provision request read for.
* A declined LMN does not change the customer experience. Truemed moves the order onto the regular card inside the
  same payment session, so the box still ships and the customer pays the same way as today.

## Today and after the change

| Step                                               | Today                                                   | After the change                                                     |
| -------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------- |
| Customer finishes the survey and enters both cards | Truemed starts the LMN review                           | Truemed sends the payment token right away                           |
| First `payment_token.updated`                      | Arrives with the clinical decision, hours to days later | Arrives right after card entry, with `eligibility_status: "pending"` |
| First order                                        | You hold it until the token arrives                     | You charge it with Create Payment Session at your usual cutoff       |
| LMN review                                         | Already finished                                        | Starts with the first order                                          |
| Clinical decision                                  | Arrives with the token                                  | Arrives on a second `payment_token.updated`                          |

## What happens to the first order

#### The token arrives

[`payment_token.updated`](/api-reference/payment-tokens/payment-token-updated-webhook) arrives as soon as the
customer enters both cards. The token is final and ready to charge. Only `eligibility_status` is `pending`.

#### You badge the menu

[Retrieve Eligibility by Payment Token](/api-reference/eligibility/retrieve-token-eligibility) returns
`pending` and lists the items that may be eligible for the HSA/FSA card while the review runs. Badge them as
pending clinical review.

#### You charge the first order

Call [Create Payment Session](/api-reference/payment-sessions/create-payment-session) at your usual cutoff. The
payment session reports `processing` until the practitioner decides. Ship the box on schedule, because the
decision does not hold up fulfillment.

#### The practitioner decides

A second `payment_token.updated` reports `approved` or `rejected`, and its `payment_session_id` names the first
order's payment session.

#### Truemed settles the first order

If the practitioner approves, Truemed captures the first payment session split across both cards. If the
practitioner declines, which is rare, Truemed cancels the HSA/FSA portion and charges the whole order to the
regular card inside the same payment session. The session reports `captured` for the full total, and you take no
action. The token stays usable, and later orders charge the regular card.

## Read eligibility from the payment token

Retrieve Eligibility by Provision Request exists so you can read eligibility before a token exists. After this
change, the token exists before the first order, and both endpoints return the same response for it.

* Read eligibility with [Retrieve Eligibility by Payment Token](/api-reference/eligibility/retrieve-token-eligibility)
  for the first order and every order after it.
* Switch every read of Retrieve Eligibility by Provision Request to the token read. For the first order, the
  token read returns `pending` with the items the survey predicts, the same response the provision request read
  gives. The provision request endpoint keeps working, so nothing breaks while you switch.
* Keep storing `provision_token_request_id`. If the customer reaches your menu before `payment_token.updated`
  arrives, or a delivery never reaches you, get the token from
  [Retrieve Provision Token Request](/api-reference/payment-tokens/retrieve-payment-token-provision-request) first.
  Truemed mints the token before it redirects the customer, so the token is always there.

## What stays the same

* The same endpoints, webhooks, payload fields and payment session statuses.
* The token itself. The first delivery carries the final `payment_token`, and the clinical decision changes only
  `eligibility_status`.
* A worker that charges when a token arrives keeps working with no changes.
* Later orders, the two-card split and receipts work as they do today.

## What to update

1. Charge the first order when the token arrives, instead of holding it for the clinical decision.
2. Treat a repeat `payment_token.updated` as an update. The second delivery carries the same `payment_token`, so
   update the record you hold rather than storing a new token.
3. Drive decision messaging and badges from the second delivery. The first `payment_token.updated` carries
   `eligibility_status: "pending"`, and the second carries `approved` or `rejected`. Use the second delivery to
   confirm HSA/FSA coverage and update the menu badges, or to explain that Truemed charged the order to the
   customer's regular card.
4. Handle a regular-card decline after a rejection. Truemed cancels the order, and the
   [Payment Session Complete](/api-reference/payment-sessions/payment-session-completed-webhook) webhook reports the
   session as `rejected`.
5. Switch every eligibility read from the provision request to the payment token, as described above.

Truemed will confirm the go-live date with your team. Questions? Reply to your Truemed contact.