Update Customer Payment Card

When a customer's card is about to expire, they need a way to update it before the next renewal fails. This guide creates a Stripe-hosted billing portal link where the customer can update the card themselves.

Prerequisites

The Owner must have an associated Stripe customer. Salable attaches one when you create a checkout session for that Owner, so an Owner who has never been through checkout, or whose Subscriptions are all Salable-only, returns a 400.

Create the portal session

Call POST /api/owners/{id}/portal with the paymentMethodUpdate feature enabled. The response contains a url that you redirect the customer to.

import { Salable } from '@salable/sdk';
const salable = new Salable(process.env.SALABLE_SECRET_KEY);
 
const { data } = await salable.api.owners.byId('owner_01KJXR7QK4ZP2VN8DHT3MEBS9G').portal.post({
    features: {
        paymentMethodUpdate: { enabled: true }
    }
});

const response = await fetch('https://salable.app/api/owners/owner_01KJXR7QK4ZP2VN8DHT3MEBS9G/portal', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.SALABLE_SECRET_KEY}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        features: {
            paymentMethodUpdate: { enabled: true }
        }
    })
});
 
const { data } = await response.json();

Stripe portal sessions are short-lived and single-use, so generate a fresh one on each request rather than storing it. The same API call can enable other portal features, see the endpoint documentation for details.

Handle access on failed renewals

If configured in your Stripe connected account with Salable, a failed renewal moves the Subscription to past_due rather than cancelling it immediately. Past Due Entitlements is enabled by default on the Product, so the customer keeps their Entitlements while Stripe retries the payment. If you have disabled the setting, access is revoked as soon as the subscription becomes past_due.

During the retry period, direct the customer to a newly generated portal URL so they can replace the failed payment method.

Related

• Subscriptions & Billing Recovering failed payments and the wider billing lifecycle.
• Owner The reference definition of an Owner in the Salable model.