Skip to navigation

API calls, at a glance

CallWhenWhat it does
Create Payment TokenSignup, onceStarts the survey and dual-card journey. Returns the URL you embed and a provision-request id. Truemed issues that id once and keeps it for the life of the token, through every later requalification.
Payment Token Updated (webhook)Card entry, then LMN decidedArrives with the token and eligibility_status: "pending" as soon as the customer enters both cards, which is your signal to charge the first order. Arrives again with approved or rejected when the practitioner decides, with payment_session_id naming the first order.
Retrieve Provision Token RequestAfter a missed webhookReturns the payment_token value you charge against, which no eligibility read returns. For the outcome, call Retrieve Eligibility by Payment Token.
Retrieve Eligibility by Payment TokenMenu renderReturns eligibility_status, items (the meals this customer may put on their HSA/FSA card) and lmn_expires_at.
Retrieve Catalog EligibilityMenu with no customerYour whole configured catalog, with no customer-specific fields.
Update Payment TokenRequalification or reapplyWith renew_eligibility: true, returns a fresh survey link when the customer has no LMN, or the LMN is rejected, expired, or expires within 30 days. See Getting a fresh survey link.
Create Payment SessionEvery chargeThe whole transaction: classifies each line, splits across both cards, authorizes, echoes the expiry date.
Capture SessionOptionalIf you would rather authorize at selection and capture at fulfilment, this is how.
Payment Session Complete (webhook)Every chargeAsynchronous outcome of the charge.
Create RefundAs neededRefunds return to the originating card, split the same way as the charge.
Create Catalog Item and Update Catalog ItemNew or changed mealSend the full meal with its nutrition, allergens, and labels in blocks. See Nutrition and Structured Data.

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

Create Payment Token:

POST https://api.truemed.com/api/v1/payment_tokens/create
x-truemed-api-key: <your API key>
Content-Type: application/json
{
"idempotency_key": "merchant-signup-84213",
"customer_email": "jamie.rivera@example.com",
"customer_name": "Jamie Rivera",
"customer_state": "CA",
"success_url": "https://www.example.com/hsa/complete",
"failure_url": "https://www.example.com/hsa/cancelled",
"metadata": "{\"merchant_customer_id\":\"84213\"}",
"use_iframe": true
}

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. With use_iframe it 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

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

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:

GET https://api.truemed.com/api/v1/eligibility/token/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42
x-truemed-api-key: <your API key>
{
"eligibility_status": "pending",
"items": ["salmon-teriyaki-bowl", "chicken-pesto-plate", "protein-breakfast-box"],
"lmn_expires_at": null
}

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:

GET https://api.truemed.com/api/v1/eligibility/token/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42
x-truemed-api-key: <your API key>
{
"eligibility_status": "approved",
"items": ["salmon-teriyaki-bowl", "chicken-pesto-plate", "protein-breakfast-box"],
"lmn_expires_at": "2027-08-06"
}

If the practitioner declines, the same read answers rejected, the same value the webhook below carries, available here whenever you want to confirm it:

GET https://api.truemed.com/api/v1/eligibility/token/tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42
x-truemed-api-key: <your API key>
{
"eligibility_status": "rejected",
"items": [],
"lmn_expires_at": null
}

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

payment_token.updated:

POST https://<your webhook endpoint>
x-truemed-signature: t=1785938402,v0=8f4c2ad91e6b...
Content-Type: application/json
{
"webhook_delivery_id": "dlv_9a71c0e4b5d2483f8e6c1a70d94b2f53",
"event_type": "payment_token.updated",
"data": {
"payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42",
"provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
"payment_session_id": null,
"failed_payment_session_id": null,
"eligibility_status": "approved",
"payment_methods": [
{ "last4": "4242", "expiration": "08/2029",
"payment_method_updated_at": "2026-08-06T14:22:07.318000+00:00" },
{ "last4": "1881", "expiration": "03/2028",
"payment_method_updated_at": "2026-08-06T14:22:07.402000+00:00" }
],
"lmn_expires_at": "2027-08-06",
"metadata": "{\"merchant_customer_id\":\"84213\"}"
}
}

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 is tm_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 of approved, pending, expired, rejected or never_requested. For a new customer, the first delivery carries pending and the second carries approved or rejected. 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 inner data object at the top level, authenticated with x-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:

{
"webhook_delivery_id": "dlv_3c7e0b52d1a94f60b8ae1d7f2c05e934",
"event_type": "payment_token.updated",
"data": {
"payment_token": "tm_token_3c7e0b52-d1a9-4f60-b8ae-1d7f2c05e934",
"provision_token_request_id": "f81a4e60-90c7-4d2b-8ab3-71e5c9042fd7",
"payment_session_id": null,
"failed_payment_session_id": null,
"eligibility_status": "rejected",
"payment_methods": [
{ "last4": "1881", "expiration": "03/2028",
"payment_method_updated_at": "2026-08-06T14:22:07.402000+00:00" }
],
"lmn_expires_at": null,
"metadata": "{\"merchant_customer_id\":\"84219\"}"
}
}

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:

  1. Call Retrieve Provision Token Request with the provision_token_request_id that create_payment_token returned. It returns the payment_token you charge against, and you store it the same way you store a webhook delivery. A null payment_token means the customer has not entered both cards yet, so there is nothing to charge.
  2. Call Retrieve Eligibility by Payment Token with that token. pending means the practitioner has not decided yet. approved or rejected means 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.

ReadCache perHold until
Bare catalogYour whole siteA fixed window of your choosing. It carries no customer, so one entry serves all anonymous traffic however many pageviews you get.
Keyed on /token/{token_id}The customerYour menu changes, or payment_token.updated arrives, or lmn_expires_at passes. Whichever comes first.

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:

eligibility_statusitemslmn_expires_at
pendingOn the first order, what the survey predicts the LMN will cover, plus items that need no LMN, pending clinical review until the practitioner decides. During a requalification, empty.null before the first LMN. During a requalification, the previous LMN’s expiry.
approvedThe items the customer may put on the HSA/FSA card.In the future: the date coverage ends.
expiredEmpty.In the past: the date coverage ended.
rejectedEmpty.null on a first order, where no LMN was ever issued; the old LMN’s expiry when a lapsed subscriber was re-declined.
never_requestedEmpty, unless your catalog needs no LMN at all, in which case the pre-approved items, since nothing depends on an LMN.null, because no LMN was ever requested for this customer on this channel.

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:

StateUseful to you?Right behavior
PendingYes. It is what lets you badge the first menu before the LMN is decided.Badge the predicted items and label them pending clinical review. Charge the first order as usual.
ApprovedYes. The steady state, and the only one where the customer can pay with the HSA/FSA card.Badge the listed items as HSA/FSA-payable and charge. Refresh the read when your menu changes.
ExpiredYes, high value. This is the renewal trigger, and the one to build lifecycle messaging on.Nudge to requalify with a fresh survey link, and keep charging the regular card meanwhile.
Never requestedYes. It distinguishes “hasn’t tried” from “tried and was declined”, which calls for an acquisition prompt rather than a re-engagement one.Offer a fresh survey link. The copy differs from the renewal nudge.
RejectedYes, mainly as a suppression signal.Charge the regular card silently. If the customer chooses to reapply, get a fresh survey link. Truemed has no waiting period.

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.