Create a subscription (existing subscriber)

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

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.

curl https://dev-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"
      }
    ]
  }'

{
  "provision_token_request_id": "8a1f0c2e-77b4-4f0a-9c31-2f5c7a9d4e10",
  "redirect_url": "https://dev.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.

Next steps