Billing portal

Let customers manage their own subscriptions without contacting you.

The billing portal is a page Bias hosts on your checkout domain. Customers sign in with a link from you or a code sent to their email. It has three tabs, Subscriptions, Invoices and Wallet, where customers see their subscriptions, invoices and saved payment methods and make the changes you allow. The page and the sign-in email use your logo, icon, accent color, background color and business name.

The portal lives at /account on your custom checkout domain, or at https://checkout.biaspay.com/account/{merchant_id} if you don’t have one. The exact link is under Settings → Billing portal.

What customers can do

• See their subscriptions, with the next payment date and amount, and the payment method each one uses.
• Cancel at the end of the current period or trial, and optionally tell you why. The reason is saved on the subscription’s cancellation_details as feedback and comment, and shown on its page in the dashboard.
• Undo a scheduled cancellation before it takes effect.
• Skip the next renewal. They aren’t charged for the next period, and billing resumes after it.
• Pause until they resume. They aren’t charged while paused.
• Resume a paused subscription. If the paid period is over, a new one starts and is charged right away.
• Change plan or quantity, switching between the prices you list. See plan and quantity changes.
• Change a subscription’s payment method to a saved card or bank account, or a new one. A customer with several subscriptions can use it for all of them. If a subscription is past due, its failed payment is retried with the new method right away.
• Manage their saved payment methods: see which subscriptions each one pays for, add new ones, choose a default that all their subscriptions use, and remove ones they no longer need. A payment method that pays for a subscription can’t be removed until the subscription uses another. Payment methods they add here are also offered when they pay on your checkout and invoice pages.
• See their invoices, including one-off invoices outside subscriptions, with their line items and payment attempts. They can download invoices and receipts and pay open and uncollectible invoices. An invoice whose bank payment is still settling shows as processing.

Choose what customers can do

In Settings → Billing portal, each action under What customers can do has a switch that turns it on or off:

Signed-in customers can always see their subscriptions and invoices, cancel or undo a scheduled cancellation, and manage their payment methods. They can resume a paused subscription when either pausing or skipping is on.

With Email sign-in, which is on by default, customers can sign in with a code sent to their email. While it’s on, the page shows your Portal link, and subscription emails link to the portal. When it’s off, customers on the sign-in page are asked to contact you instead. Links you create from the dashboard or with a billing portal session still work, so you can keep the portal behind your own sign-in.

Plan and quantity changes

Turn on Change plans, then click Allowed for N prices to choose which prices customers can switch to in Plan changes. The portal shows them by interval, then by amount, with each product’s name, description and image. Removing a price stops new switches to it; current subscribers keep it.

With Change quantity on, customers can change how many they subscribe to, from 1 to 9,999.

Before confirming, customers see what the change costs today and what they’ll pay from the next renewal. Upgrades apply right away, and the customer is charged for the rest of the period. Under Downgrades, choose when downgrades apply: At the end of the period (the default), Immediately, with credit for the unused time, or Immediately, without credit. Changes during a trial apply right away, with nothing charged. See plan changes and proration for how changes are billed.

A change charged right away is charged while the customer is in the portal, and applies once the payment goes through. If the payment is declined, the plan doesn’t change. For subscriptions billed by emailed invoice, the change invoice is sent by email.

A downgrade waiting for the end of the period shows in the portal with Keep current plan, and in the dashboard with Cancel scheduled change.

Plan changes work on active and trialing subscriptions with one item, and aren’t available while a renewal is being prepared.

Send customers to the portal

From your server

If customers sign in to your website, create a billing portal session when they ask to manage their subscription, and redirect them to its url:

const session = await bias.billingPortal.sessions.create({
    customer: "cus_...",
    return_url: "https://example.com/account",
});

if (session.object === "error") throw new Error(session.error.message);

return Response.redirect(session.url, 303);

When the customer opens the url, Bias signs them in. The link works once and expires 5 minutes after it’s created, so create it when the customer clicks, not ahead of time. The portal’s return link goes to return_url, or to the website in Settings → Details if you leave it out. Pass subscription to open the portal to one of the customer’s subscriptions.

Open the portal to a change

To add upgrade buttons to your own site, pass a flow naming the subscription and the change. The portal opens straight to confirming it:

const session = await bias.billingPortal.sessions.create({
    customer: "cus_...",
    flow: { type: "change_plan", subscription: "sub_...", price: "price_...", quantity: 5 },
    return_url: "https://example.com/account",
});

A flow can use any of your recurring prices, including ones not listed in the portal, and works even when Change plans and Change quantity are off. price and quantity default to the subscription’s current ones. The flow applies only while the subscription is still on the plan it had when you created the session. proration_behavior and apply_at (now or period_end) override the portal’s settings. When the customer is done, the portal returns them to return_url.

From the dashboard

On a customer’s or subscription’s page, choose Copy billing portal link from Actions. The link works on any device until it expires after 7 days. Anyone with it can sign in as that customer, so share it only with them.

Email sign-in

Customers who open the portal without a link from you, for example from your website or a subscription email, sign in with their email. Customers with a subscription that’s active, trialing, past due, paused or unpaid get an email with a 6-digit code and a sign-in link, both valid for 10 minutes.

Customers are signed out after an hour of inactivity, or 12 hours after signing in, whichever comes first.

What you’ll see

Bias sends the same events for changes made in the portal as for changes you make. Their context names the customer:

"context": { "actor_kind": "customer", "actor_user_id": "cus_..." }

A subscription’s activity marks the changes its customer made, for example “Cancellation scheduled by customer” or “Paused by customer”.

To get an email when a customer subscribes or cancels, turn on New subscriptions and Canceled subscriptions under Notifications in Settings → Profile. Each dashboard user chooses their own.

While Email sign-in is on, subscription reminder emails (trial endings, upcoming renewals and yearly reminders) have a Manage subscription button that opens the portal, in place of instructions to contact you. Failed renewal emails also link to the portal so customers can switch to a new payment method. See customer emails.

Limits

• Customers can’t change their shipping address in the portal. Change it from the dashboard or the API.
• Plan changes are for subscriptions with one item. Change subscriptions with several items from the dashboard or the API.
• Customers can cancel only at the end of the period. A paused subscription whose paid period is over ends right away. To end a subscription now or credit unused time, cancel it yourself.
• Skipping and pausing are available on active subscriptions, not during a trial or while a payment is past due.
• Payment method updates apply to subscriptions charged automatically. For subscriptions billed by emailed invoice, customers choose how to pay each time they pay an invoice.
• Customers can’t save an Apple Pay card in the portal, and the wallet only lists cards and bank accounts saved for future payments.