API calls
API calls, at a glance
Every call in this table is live in production today and documented in the API reference. Truemed rate limits the requests you send to these endpoints, per sales channel. See Rate limiting.
The four calls that carry a customer through signup
Four payloads, matching steps 1, 2, 3 and 5 of the first-order diagram. Host tokens resolve to the environment you are reading this on; sandbox and production hosts are listed in Before you begin.
Start the journey
That is the whole of the customer information Truemed needs, and each field does one job:
customer_email: required. Truemed uses it to create the patient record the LMN is written for, and it is where the receipt goes. It is not how you look the customer up afterwards; that is the token’s job, and the distinction matters, because an email address can change while the person does not.customer_name: required. It goes on the LMN, and it pre-fills the name confirmation step in the survey so the customer confirms rather than retypes. It is read once, when the record is first created, so a later name change on your side does not travel through this call.customer_state: optional, and worth sending. It pre-fills the state-of-residence answer, which determines which practitioner can review the case. It is the only survey answer this call can pre-fill.failure_url: where the customer goes when they opt out of HSA/FSA, do not qualify in the survey, or cancel a card update. Withuse_iframeit comes back in the completion message instead of navigating; see Embedded checkout.metadata: an opaque string Truemed stores and hands back to you on the token webhook and on every payment session. This is where your own customer ID goes. There is no dedicated external-ID field on this endpoint today; if you would rather have a first-class one, say so and we will scope it.order_items: deliberately absent. Your channel qualifies against the whole catalog, so there is no basket to declare. (For other partners it is required.)use_iframe:true, which is what makes the returned URL embeddable. See Embedded checkout.
Read what comes back
Use redirect_url as the src of your iframe. That is step 2 of the first-order flow, the health survey
and the two cards, rendered inside a modal on your page.
Persist provision_token_request_id on the customer record before you open the frame. It is the
join key. The decision comes back asynchronously, minutes or hours later, on a webhook that carries no
email and no name, so this id (or your own id inside metadata) is how you know which customer it
belongs to.
Store it once. Truemed issues one provision-request id per token and never replaces it, so a requalification does not hand you a new value to track alongside the token.
Read eligibility, before and after the decision
Retrieve Eligibility by Payment Token takes the payment_token
from the first payment_token.updated delivery, described in Receive the token below:
This is the read behind step 3 of the first-order flow. The practitioner has not decided yet, so
items is what the survey predicts the LMN will cover, plus any items that need no LMN, and there is no
expiry yet. Badge these as pending clinical review. Truemed charges the first order from the same list,
so your badges and the split always agree.
If you read first-order eligibility with Retrieve Eligibility by Provision Request, switch to this read. The
pending token read returns the same response.
This is the same one call whether or not a person picks the meals. If the customer chooses their first box by hand, you use the response to badge the menu they are looking at. If your personalization engine assembles the box for them with no manual selection, you use the identical response to decide which lines are HSA/FSA-payable before you charge. The eligibility call answers the same question in both cases.
Once the practitioner approves, the same read returns the decided coverage and its expiry. This is also the call that every later order opens with:
If the practitioner declines, the same read answers rejected, the same value the webhook below
carries, available here whenever you want to confirm it:
Truemed moves the whole first order onto the regular card in the same payment session and captures the full total there. The token stays active with zero HSA/FSA coverage. Use this outcome for messaging.
The read also works with no key. Called bare, as
GET /api/v1/eligibility with no key, it
returns your whole configured catalog with eligibility_status and lmn_expires_at both null: the
menu-with-no-customer read. The
state table
below spells out items and lmn_expires_at for every value.
Receive the token
Acknowledge with a 2xx; Truemed retries with backoff for up to seven days. The payload is a full
snapshot of current state rather than a delta, so the safe way to consume it is to upsert, overwriting
the token and card details you hold. That stays correct under a retry and under a genuine later update
alike.
payment_token: the value you charge against. Its shape istm_token_<uuid4>, 45 characters; treat it as an opaque string rather than parsing it. It is the only field on this payload guaranteed to be non-null.eligibility_status: the clinical outcome, one ofapproved,pending,expired,rejectedornever_requested. For a new customer, the first delivery carriespendingand the second carriesapprovedorrejected. The other three can reach you on a later delivery for the same token, so branch on the value rather than treating it as a boolean. It is an additive optional field, so a handler written before it existed keeps working unchanged.payment_methods: last four and expiry for both stored cards, HSA/FSA first, so you can render “HSA •••• 4242 · regular •••• 1881” in account settings without a second call.lmn_expires_at: the 12-month LMN expiry described in Subsequent orders. It is the same date you get back on every payment session.- The envelope shown is what a signed endpoint receives, with an HMAC-SHA256 over the timestamp and
body in
x-truemed-signature. We recommend it. An endpoint registered without a signing secret instead receives the innerdataobject at the top level, authenticated withx-truemed-api-key.
The rejected delivery is the same event, and three fields tell it apart. It is worth having side by side with the payload above:
The token is the same one the first delivery carried, so upsert the record you already hold. It covers nothing, and every line of every later charge routes to the regular card.
Where the token lives on your side
One token per customer, stored as a field on the customer or subscription record, in the same place you would keep a payment-method id. It is what every later Create Payment Session call is keyed on, including the unattended weekly ones, so it needs to be readable from your recurring-billing job as well as from a checkout session.
Two properties are worth designing around. The token is long-lived and writable: if the customer
later replaces a card, the token value stays the same and Truemed sends payment_token.updated again,
with the same payment_token, the same provision_token_request_id and refreshed payment_methods. So
handle a repeat delivery as an update to the record you already have. The token is also durable: it
survives LMN expiry. An expired LMN leaves the token valid and means the HSA/FSA portion stops
being eligible, so everything routes to the regular card until a new LMN is in place.
Before the token arrives, or when a delivery fails
The token exists by the time Truemed redirects the customer to your success_url, but
payment_token.updated can arrive a few seconds
later. If the customer reaches your menu first, or a delivery never reaches you, two reads give you everything the
webhook carries:
- Call Retrieve Provision Token Request
with the
provision_token_request_idthatcreate_payment_tokenreturned. It returns thepayment_tokenyou charge against, and you store it the same way you store a webhook delivery. Anullpayment_tokenmeans the customer has not entered both cards yet, so there is nothing to charge. - Call Retrieve Eligibility by Payment Token with that
token.
pendingmeans the practitioner has not decided yet.approvedorrejectedmeans the decision is in.
Truemed adds no id to the redirect. Keep provision_token_request_id against your own customer record when
create_payment_token returns it, and put your own customer reference in success_url if you need to recognize who
landed.
If your endpoint was down or returned an error, an admin can find the delivery under Developers → Webhooks and select Resend, which appears while the endpoint is enabled. Truemed sends the same event again, so your existing handler runs unchanged.
Reading the comparable amount
The catalog reads return each meal’s comparable amount as comparable_item_price_cents, in cents per
meal. Both get_catalog_item and
list_catalog_items include it. For one line, the
personal card carries comparable_item_price_cents × quantity, up to the line total, and the HSA/FSA
card carries the rest.
Truemed omits comparable_item_price_cents for an ineligible meal, a meal still awaiting review, and a
meal with no comparable product on file. A missing value is not a zero deduction: the line goes entirely
to one card, so read the eligibility field alongside it.
Truemed reviews comparable amounts about monthly. A reprice triggers no webhook and does not advance
updated_at, so re-read the full catalog at least monthly. Truemed settles the exact split at charge.
Catalog reads count against your catalog limit of 600 requests per minute for each sales channel. Your payment session calls draw from a separate limit, so a catalog sync never slows a capture or a refund. See Rate limiting.
Caching the two reads
Each read changes on a different trigger, so each one needs its own cache rule. If your cache calls Truemed only on a miss, the eligibility reads stay off your hot path.
The two eligibility reads share a limit of 600 requests per minute for each sales channel. Caching keeps you well under it. See Rate limiting.
Clear a cached token-keyed response whenever your menu changes, and never hold it past
lmn_expires_at. The date limits how long the practitioner’s decision lasts. The items list changes
each time your menu changes, because a meal you add next month can be relevant to a customer who
qualified last month. If you hold the response until lmn_expires_at, that customer sees no badge on
any meal you added after the cache entry.
Five states, five different things to do
Every form of GET /api/v1/eligibility, whether bare or keyed on /token/{token_id},
answers with the same three-field response shape:
eligibility_status, items, lmn_expires_at. The field tells you where the customer stands, and you
decide what your lifecycle messaging does about it. First, what each value carries:
The bare catalog read, GET /api/v1/eligibility with no key, returns every item configured for you with
eligibility_status and lmn_expires_at both null: there is no shopper to have either.
The states are not interchangeable, and one of them is a reason to hold back:
Never requested is usually yours to know without asking. The read takes the token, which only you hold.
If you hold neither a token nor a provision_token_request_id for a customer, they have never started. If you
hold only the provision_token_request_id, they finished the survey but never entered cards, so prompt them to
finish rather than to start. A customer can also hold a token while no LMN was ever requested for them, for
example when your catalog needs no LMN. In that case Truemed answers never_requested rather than expired,
because there is no LMN to renew.
Rejected is the one worth handling carefully. A customer whose LMN lapsed, who requalified and was
then declined, still has a live token and a working regular card, so everything keeps shipping and keeps
charging. What should not happen is another renewal nudge: a practitioner has already reviewed and
declined, and Truemed has already emailed them about it. Reading eligibility_status, rather than
inferring from an empty items list, is what keeps you from asking twice. A first-order rejection lands
in the same place from day zero: the token arrives covering nothing, and the subscription starts on the
regular card instead of dying at the gate.