Upcoming first-order change
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
What happens to the first order
The token arrives
payment_token.updated arrives as soon as the
customer enters both cards. The token is final and ready to charge. Only eligibility_status is pending.
You charge the first order
Call 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 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
pendingwith 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 beforepayment_token.updatedarrives, or a delivery never reaches you, get the token from Retrieve Provision Token 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 onlyeligibility_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
- Charge the first order when the token arrives, instead of holding it for the clinical decision.
- Treat a repeat
payment_token.updatedas an update. The second delivery carries the samepayment_token, so update the record you hold rather than storing a new token. - Drive decision messaging and badges from the second delivery. The first
payment_token.updatedcarrieseligibility_status: "pending", and the second carriesapprovedorrejected. 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. - Handle a regular-card decline after a rejection. Truemed cancels the order, and the
Payment Session Complete webhook reports the
session as
rejected. - 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.