Skip to navigation

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

StepTodayAfter the change
Customer finishes the survey and enters both cardsTruemed starts the LMN reviewTruemed sends the payment token right away
First payment_token.updatedArrives with the clinical decision, hours to days laterArrives right after card entry, with eligibility_status: "pending"
First orderYou hold it until the token arrivesYou charge it with Create Payment Session at your usual cutoff
LMN reviewAlready finishedStarts with the first order
Clinical decisionArrives with the tokenArrives on a second payment_token.updated

What happens to the first order

1

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.

2

You badge the menu

Retrieve Eligibility by Payment Token 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.

3

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.

4

The practitioner decides

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

5

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