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

# Create a subscription (existing subscriber)

> Qualify a customer who already subscribes with you, and store their HSA/FSA card without charging them.

When a customer already has an active subscription with you and wants to start paying with HSA/FSA
funds, you provision a token on its own—no charge, no order. `create_payment_token` runs the same
survey and card entry as a new subscriber, minus the payment.

This flow is a variant of [New Subscriber](/guides/setup/api/subscriptions/create-a-subscription-new-subscriber). Read that page for
the shared parts; this page covers only what differs.

## When to use this flow

Use `create_payment_token` when the customer is mid-subscription and there's nothing to charge right
now—you're switching their payment method for future billing periods. If you're charging them today,
use `create_payment_session` with `tokenize: true` instead.

## How this differs from a new subscriber

|                     | New subscriber                                             | Existing subscriber                             |
| ------------------- | ---------------------------------------------------------- | ----------------------------------------------- |
| Endpoint            | `create_payment_session` with `tokenize: true`             | `create_payment_token`                          |
| Amount charged      | The first order                                            | Nothing                                         |
| `total_amount`      | Required                                                   | Ignored                                         |
| Identifier returned | `id`, the payment session                                  | `provision_token_request_id`, the setup request |
| Webhooks fired      | `payment_session_complete` **and** `payment_token_updated` | `payment_token_updated` only                    |

Because no payment session exists, there's no `payment_session_complete` webhook and nothing to
fulfill. The only outcome that matters is whether a token gets provisioned.

## Create the token

`order_items` still matters: the LMN is scoped to what the customer is subscribed to, so send the
items in their current subscription.

```bash
curl https://api.truemed.com/api/v1/payment_tokens/create \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
  -d '{
    "idempotency_key": "sub_12345_token_setup",
    "customer_name": "Alex Smith",
    "customer_email": "alex@example.com",
    "success_url": "https://example.com/account/payment-method/success",
    "failure_url": "https://example.com/account/payment-method/canceled",
    "metadata": "subscription_12345",
    "order_items": [
      {
        "sku": "b12-monthly"
      }
    ]
  }'
```

```json
{
  "provision_token_request_id": "8a1f0c2e-77b4-4f0a-9c31-2f5c7a9d4e10",
  "redirect_url": "https://app.truemed.com/..."
}
```

Store the `provision_token_request_id` against the customer. It comes back on the
`payment_token_updated` webhook, and it's how you match the eventual token to the right subscription.

On failure, the response carries an `error` enum and a `message` describing the problem—useful while
you're building.

## What happens next

Redirect the customer to the `redirect_url`. From here the flow is identical to a new subscriber:
they complete the health survey, enter their HSA/FSA card, and return to your `success_url`, where you
show a "payment method saved" message. See [How the flow works](/guides/setup/api/subscriptions/create-a-subscription-new-subscriber#how-the-flow-works).

> **Note**
>
> There's no need to poll
> [`retrieve_provision_token_request`](/api-reference/payment-tokens/retrieve-payment-token-provision-request)
> for status. The
> [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook tells
> you when the token is ready.

> **Warning**
>
> Wait for `payment_token_updated` before charging. A token isn't guaranteed—if the customer abandons the
> survey or no LMN is issued, the webhook never fires and no token exists. Returning to your
> `success_url` is not confirmation.

## Next steps

#### [Recurring Charges](/guides/setup/api/subscriptions/subsequent-billing-periods)

Charge the stored token on your billing schedule.

#### [Token Lifecycle](/guides/setup/api/subscriptions/token-lifecycle)

What to do when a charge fails and the customer has to act.