> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Update an active subscription

> Let customers change their card on file or their subscribed items without breaking eligibility.

Three things change over the life of a subscription: the card on file, the items being delivered, and
the customer's email address. All three go through
[`update_payment_token`](/api-reference/payment-tokens/update-payment-token). A card or item change
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.

> **Warning**
>
> `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.

```bash
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"
  }'
```

```json
{
  "next_action": "UpdatePaymentMethod",
  "redirect_url": "https://app.truemed.com/..."
}
```

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.

```bash
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_action`         | What it means                                                                                                           | What to do                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `"None"`              | The change is covered by the existing LMN.                                                                              | Confirm the change to the customer.                                                                    |
| `TakeHealthSurvey`    | The customer must requalify before the next charge.                                                                     | Mark the change pending and send them to `redirect_url`. Confirm once `payment_token_updated` arrives. |
| `UpdatePaymentMethod` | The 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`.               |

> **Note**
>
> `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.

## Update the customer's email

When a customer changes their email address with you, send the new address in `customer_email`.
Truemed sends receipts and LMN notifications for this token to the new address from then on.

```bash
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 '{
    "customer_email": "alex.new@example.com",
    "success_url": "https://example.com/account/success",
    "failure_url": "https://example.com/account/canceled"
  }'
```

```json
{
  "next_action": "None",
  "redirect_url": null
}
```

* Verify that the new address belongs to the same customer before you send it. Truemed does not verify
  it.
* `update_payment_token` is the only way to change the email on a token. When you send `payment_token`
  to `create_payment_session`, Truemed ignores `customer_email` in that request.
* The change applies to this token only. The customer keeps the same Truemed account and dashboard
  login. To change their login email, the customer contacts Truemed Support.
* After the update, [`retrieve_payment_token`](/api-reference/payment-tokens/retrieve-payment-token)
  returns the new address as `customer_email`.

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

```bash
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" }
    ]
  }'
```

```json
{
  "next_action": "TakeHealthSurvey",
  "redirect_url": "https://app.truemed.com/..."
}
```

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`](/api-reference/payment-tokens/retrieve-payment-token):

```bash
curl https://api.truemed.com/api/v1/payment_tokens/{payment_token} \
  -H "x-truemed-api-key: $TRUEMED_API_KEY"
```

```json
{
  "payment_token": "dev_tm_token_8a1f0c2e-77b4-4f0a-9c31-2f5c7a9d4e10",
  "customer_name": "Alex Smith",
  "customer_email": "alex@example.com",
  "created_at": "2026-02-14T18:22:05+00:00",
  "lmn_expires_at": "2027-02-14",
  "payment_methods": [
    {
      "last4": "4242",
      "expiration": "09/2028",
      "payment_method_updated_at": "2026-02-14T18:24:41+00:00"
    }
  ]
}
```

| Field                                         | Use it to                                                                                     |
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `payment_methods[].last4`                     | Show the customer which card is on file.                                                      |
| `payment_methods[].expiration`                | Show and monitor the card expiry. `MM/YYYY`.                                                  |
| `payment_methods[].payment_method_updated_at` | Show when the customer last changed their card. Timestamp, offset-formatted `+00:00`.         |
| `lmn_expires_at`                              | Show and monitor when requalification will be needed. A date (`YYYY-MM-DD`), not a timestamp. |
| `customer_name`, `customer_email`             | Confirm you're displaying the right subscription.                                             |
| `created_at`                                  | Show when HSA/FSA payment was set up. Timestamp, offset-formatted `+00:00`.                   |

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

## Related guides

| Need                                         | Read this                                                                                                     |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Recover a subscription after a failed charge | [Token Lifecycle](/guides/setup/api/subscriptions/token-lifecycle)                                            |
| Run the expiration-monitoring job            | [Partner Operations](/guides/setup/api/subscriptions/partner-administrative-operations#monitor-expirations)   |
| Cancel or terminate a subscription           | [Partner Operations](/guides/setup/api/subscriptions/partner-administrative-operations#cancel-a-subscription) |
| Charge the token each billing period         | [Recurring Charges](/guides/setup/api/subscriptions/subsequent-billing-periods)                               |