Platform SetupAPISubscriptionsSubscription Behavior

Partner operations

These operations support your own systems and your support team rather than the customer directly. Use them to reconcile subscription state with Truemed, catch expirations before they break a charge, and cancel tokens when a customer leaves.

List subscriptions

list_payment_token returns every token associated with your API key. Use it to reconcile against your own records, to look up a customer for a support agent, or to drive the expiration sweep below.

$curl "https://api.truemed.com/api/v1/payment_tokens?email=alex@example.com" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY"
ParameterFilters by
emailCustomer email. Partial (substring) match.
nameCustomer name. Partial (substring) match.
lmn_expires_beforeTokens whose LMN expires between today and this date. YYYY-MM-DD. Already-lapsed LMNs are excluded.
card_expires_beforeTokens whose card on file expires on or before this month. YYYY-MM, for example 2026-09.
page, page_sizePagination. page_size defaults to 30, maximum 100.

The response includes a pagination object with count, current_page, last_page, and page_size. Iterate page up to last_page to walk the full set.

Monitor expirations

Run a recurring job that filters for LMNs and cards expiring in the next 30 days, and email those customers to update their payment method or retake the survey.

Nothing pushes these expirations to you—there’s no advance-warning webhook—so this job is the only way to catch them before a charge fails.

$curl "https://api.truemed.com/api/v1/payment_tokens?lmn_expires_before=2026-09-10" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY"

Running it daily gets you three things:

  • Expiring cards caught before they cause a declined charge.
  • Expiring LMNs caught before they cause an eligibility block.
  • Customers who have time to act without their subscription being interrupted.

lmn_expires_before returns LMNs expiring between today and the date you pass. An LMN that lapsed yesterday is not returned, even though that’s exactly the state blocking the next charge. Store lmn_expires_at on your own subscription record so already-lapsed tokens stay visible to you.

Generate the link for each affected customer with update_payment_token:

  • Expiring card: send update_card_info: true. It returns an UpdatePaymentMethod redirect_url unconditionally.
  • Expiring LMN: send renew_eligibility: true along with the subscription’s current order_items. Without that flag a still-valid LMN comes back next_action: "None" with no link to email. See Renew eligibility before the LMN expires.

The two cannot be combined in one call—make two.

Cancel a subscription

delete_payment_token permanently cancels a token. Future charges are disabled—any attempt to use it with create_payment_session returns a NotFound error.

$curl https://api.truemed.com/api/v1/payment_tokens/{payment_token}/delete \
>  -X POST \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY"

Deletion is irreversible. A token cannot be reactivated, and the customer has to requalify from scratch to subscribe again. To support pause/resume or grace periods, keep that state in your own system and only delete the token when the cancellation is final.

NeedRead this
Prevent failures ahead of a chargeRecurring Charges
Let a customer update their card or itemsUpdate a Subscription
Understand a failed chargeToken Lifecycle