Platform SetupAPISubscriptionsSubscription Behavior

Update an active subscription

Two things change over the life of a subscription: the card on file and the items being delivered. Both go through update_payment_token, and both can require the customer to take an action before the token is chargeable again.

Calling this endpoint when items change is not optional. Eligibility is scoped to the items covered by the customer’s LMN, so an uncovered change will block the next charge instead.

update_card_info: true cannot be combined with order_items or with renew_eligibility: true. Either combination is rejected with a 400—when 'update_card_info' is True, 'order_items' must not be provided or when 'update_card_info' is True, 'renew_eligibility' must be False. Make two separate calls.

Update the card on file

Call update_payment_token with update_card_info: true. The response comes back with next_action: "UpdatePaymentMethod" and a redirect_url where the customer can enter new card details.

$curl https://api.truemed.com/api/v1/payment_tokens/{payment_token}/update \
>  -X POST \
>  -H "Content-Type: application/json" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>  -d '{
>    "update_card_info": true,
>    "success_url": "https://example.com/account/payment-method/success",
>    "failure_url": "https://example.com/account/payment-method/canceled"
>  }'
1{
2  "next_action": "UpdatePaymentMethod",
3  "redirect_url": "https://app.truemed.com/..."
4}

In a subscription dashboard, put this behind a button like “Update payment method” that calls the endpoint from your backend and redirects the customer to the returned URL.

Change the subscribed items

Send the new order_items. Whether the customer has to requalify depends on how far the change moves them from what their LMN covers, and that determination can change over time—so always call the endpoint and read the response rather than guessing.

$curl https://api.truemed.com/api/v1/payment_tokens/{payment_token}/update \
>  -X POST \
>  -H "Content-Type: application/json" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>  -d '{
>    "success_url": "https://example.com/account/subscription/success",
>    "failure_url": "https://example.com/account/subscription/canceled",
>    "order_items": [
>      { "name": "Monthly B12", "sku": "b12-monthly" },
>      { "name": "Monthly Magnesium", "sku": "magnesium-monthly" }
>    ]
>  }'

Read next_action to decide what to do:

next_actionWhat it meansWhat to do
"None"The change is covered by the existing LMN.Confirm the change to the customer.
TakeHealthSurveyThe customer must requalify before the next charge.Mark the change pending and send them to redirect_url. Confirm once payment_token_updated arrives.
UpdatePaymentMethodThe new items introduce a category that needs a credit or debit card as backup, and the token doesn’t have one on file.Mark the change pending and send them to redirect_url, the same as TakeHealthSurvey.

next_action is the string "None", not JSON null. Only treat a change as confirmed when it comes back as "None".

For example: a customer subscribed to monthly B12 who adds magnesium may need a new LMN covering both items. Confirming the change in your system without checking next_action leaves you with a subscription that fails at the next billing period.

Renew eligibility before the LMN expires

An LMN that is still valid covers the subscription, so a plain update_payment_token call for unchanged items comes back next_action: "None" with redirect_url: null—there is no link to send. To get a survey link ahead of the expiry, send renew_eligibility: true. It treats an LMN expiring within the next 30 days as needing requalification, and returns TakeHealthSurvey with a redirect_url you can email the customer.

$curl https://api.truemed.com/api/v1/payment_tokens/{payment_token}/update \
>  -X POST \
>  -H "Content-Type: application/json" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>  -d '{
>    "renew_eligibility": true,
>    "success_url": "https://example.com/account/subscription/success",
>    "failure_url": "https://example.com/account/subscription/canceled",
>    "order_items": [
>      { "name": "Monthly B12", "sku": "b12-monthly" }
>    ]
>  }'
1{
2  "next_action": "TakeHealthSurvey",
3  "redirect_url": "https://app.truemed.com/..."
4}

Two constraints:

  • order_items is required and must be non-empty. Send the subscription’s current items—the survey is scoped to them. Omitting them is rejected with a 400—when 'renew_eligibility' is True, 'order_items' must be provided.
  • It cannot be combined with update_card_info: true. If a customer needs both a new card and a renewed LMN, make two calls.

Outside the 30-day window, renew_eligibility: true changes nothing: a comfortably valid LMN still returns "None".

Show subscription status to customers

If you’re building a customer-facing subscription dashboard, fetch the current token state with retrieve_payment_token:

$curl https://api.truemed.com/api/v1/payment_tokens/{payment_token} \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY"
1{
2  "payment_token": "dev_tm_token_8a1f0c2e-77b4-4f0a-9c31-2f5c7a9d4e10",
3  "customer_name": "Alex Smith",
4  "customer_email": "alex@example.com",
5  "created_at": "2026-02-14T18:22:05+00:00",
6  "lmn_expires_at": "2027-02-14",
7  "payment_methods": [
8    {
9      "last4": "4242",
10      "expiration": "09/2028",
11      "payment_method_updated_at": "2026-02-14T18:24:41+00:00"
12    }
13  ]
14}
FieldUse it to
payment_methods[].last4Show the customer which card is on file.
payment_methods[].expirationShow and monitor the card expiry. MM/YYYY.
payment_methods[].payment_method_updated_atShow when the customer last changed their card. Timestamp, offset-formatted +00:00.
lmn_expires_atShow and monitor when requalification will be needed. A date (YYYY-MM-DD), not a timestamp.
customer_name, customer_emailConfirm you’re displaying the right subscription.
created_atShow when HSA/FSA payment was set up. Timestamp, offset-formatted +00:00.

This response does not include the card brand, the next billing date, or the next billing amount. Truemed doesn’t own your billing schedule—those come from your own subscription records.

Warn customers before their card or LMN expires, escalating as the date approaches: a dismissible banner at 30 days, a more prominent notice at 14, a required acknowledgment at 7. Pair the update button with a way to view billing history and cancel.

NeedRead this
Recover a subscription after a failed chargeToken Lifecycle
Run the expiration-monitoring jobPartner Operations
Cancel or terminate a subscriptionPartner Operations
Charge the token each billing periodRecurring Charges