Update Payment Method

This API endpoint initiates a payment method update for the authenticated user's subscription. On success, the system returns a hosted Stripe URL to which the customer should be redirected to securely enter their new payment details. No card data passes through your server — the entire payment capture happens on Stripe's hosted page.

This endpoint is typically triggered in two scenarios: when a user wants to proactively update their card, or when payment_failed: true is returned from the Get All Subscriptions endpoint and you need to prompt the user to fix their billing before access is revoked.

Common use cases:

• Failed payment recovery — When payment_failed: true is detected on a subscription, call this endpoint and redirect the user to the returned URL to update their card before their account is suspended.
• Proactive card update — Allow users to replace an expiring card from your billing settings page before it causes a payment failure.
• Payment method switch — Let users switch from one card to another or between supported payment methods without your app ever handling raw card numbers.
• Post-trial conversion — When a trial ends and no payment method is on file, use this endpoint to redirect the user to add billing details and convert to a paid plan.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

• On success, the system returns a session-scoped url inside data. Redirect the user to this URL immediately — the session expires after a short period.
• After the user completes the payment method update on the hosted page, Stripe notifies the system automatically. You do not need to make any additional API calls to confirm the update.
• If the authenticated user has no active subscription, a 404 is returned with data.fields.common containing the reason.
• If authorization fails, a 401 error will be returned.