Subscriptions

Charge a customer every week, month or year without sending an invoice each time.

A subscription bills one or more recurring prices on the same schedule. Each period, Bias creates an invoice and charges the customer’s saved card or bank account (or emails the invoice, if you prefer). When a payment fails, Bias retries it on a schedule and tells the customer how to fix it.

The counts at the top of the Subscriptions tab show how many subscriptions are in each status. Click one to see only those. Needs attention groups the past-due, incomplete and unpaid subscriptions. Each row shows the plan, the amount per period, the billing schedule, and the next thing that will happen on its own: a renewal, a trial ending, a resume date or a cancellation.

Create a recurring price

Subscriptions bill recurring prices. In Products, create a product (or open one) and add a price with Billing set to Recurring. Pick a billing period: weekly, every 2 weeks, monthly, every 3 or 6 months, yearly, or a custom number of days, weeks, months or years.

Prices can’t change after they’re created, so existing subscribers keep the price they signed up at. To charge new subscribers more, add a new price.

Start a subscription

Customers usually subscribe through checkout, which saves their card and records their agreement to renew. To start one yourself, click New subscription on the Subscriptions tab, or Create in the Subscriptions card on a customer’s page.

1. Choose the customer.
2. Add one or more items. Only prices on the same billing period as the first can be added.
3. Optionally add a free trial. The first charge happens when it ends.
4. Choose how it’s paid: Charge automatically to one of the customer’s saved cards or bank accounts, or Send invoices that are due the number of days after invoicing you set in Payment due.
5. Under More options, optionally add a shipping address, taxes or metadata.

Free trials at checkout

To sign customers up with a free trial, create a checkout session in subscription mode with subscription_data.trial_period_days:

const session = await bias.checkoutSessions.create({
    mode: "subscription",
    line_items: [{ price: "price_...", quantity: 1 }],
    subscription_data: { trial_period_days: 14 },
});

During the trial, recurring prices cost nothing at checkout. The customer still enters their card, and the button reads Start trial. Next to it, the renewal terms show when billing starts: “By starting your trial, you agree that after your 14-day free trial, you’ll be automatically charged $40.00 every month until you cancel. You can cancel anytime.” Bias checks a card with a $0 verification and saves it for the renewals. A bank account is saved with the customer’s debit authorization and isn’t debited until the trial ends. One-time prices in the same cart are charged right away, on an invoice of their own.

When the session completes, the subscription starts as Trialing. It works like any other trial: subscription.trial_will_end goes out 3 days before the trial ends, and the first period is invoiced and charged when it does.

• trial_period_days counts from when the session completes, up to 730 days.
• Discounts and shipping options can’t be added to a session with a trial. Set the subscription’s shipping rate once it starts.

Read a subscription

A subscription’s page starts with one sentence about what happens next: “Renews November 11 for $79.00”. Below it, the billing schedule shows paid periods (click one to open its invoice), the current period, and the next renewals. Hover a period for its dates and amount.

The rest of the page shows:

• Items: the prices it bills and the amount per period. Click Edit to change quantities, remove items or add prices. With Prorate checked, the unused time is credited and the rest of the period is billed right away. See plan changes and proration.
• Next invoice: a preview of the next renewal, with tax at today’s rates and when it will be charged.
• Scheduled change: a change that takes effect at the next renewal, such as a downgrade a customer chose in the billing portal. Click Cancel scheduled change to keep the current plan.
• Invoices and Activity: every invoice created for it, and everything that happened to it. Leave notes for your team in the activity feed. For a subscription paid from a bank account, the activity includes when the customer authorized ACH debits; click it to read the authorization they accepted.

From Actions, choose Change payment method to charge a different saved card or bank account, Edit shipping to change the shipping address and charge from the next renewal, or End trial now to start a trialing subscription’s first paid period and bill it right away.

A card or bank account saved only to pay a subscription isn’t offered back to the customer on checkout and invoice payment pages. To offer it, choose Show on payment pages from its menu on the customer’s page.

Renewals

Billing periods are counted in UTC from the subscription’s billing anchor, usually when it started. A monthly subscription that starts on January 31 renews on February 28, then March 31. Archiving a price doesn’t affect subscriptions on it: they keep renewing at that price.

At each renewal, Bias creates the period’s invoice as a draft. An hour later (a minute in a sandbox), Bias finalizes it and charges it or emails it.

The event stream carries invoice.created when the draft is created, subscription.trial_will_end 3 days before a trial ends, and subscription.will_renew ahead of each renewal: 7 days ahead for billing periods of 28 days or more, 1 day ahead for periods of 7 to 27 days, and not at all for shorter periods. To see what a renewal will charge, preview the upcoming invoice.

Subscription statuses

Pause, skip or cancel

Click Pause to stop renewals. You can skip just the next renewal, pause until a date, or pause until you resume it. Choose Cancel subscription from Actions to end it at the end of the current period, immediately, or on a date. Both dialogs preview the new schedule before you confirm.

When you cancel immediately, choose what happens to the Unused time on a paid period:

• Don’t credit: nothing is credited.
• Credit toward future invoices: the unused time goes to the customer’s balance.
• Refund to original payment: the unused time is refunded to the payment it came from. Credit already on the customer’s balance stays there.

A cancellation scheduled for later can be undone with Don’t cancel. Pausing or canceling deletes a renewal invoice that’s still a draft and stops retries of unpaid invoices. A paused subscription has a Resume button. If its paid period hasn’t ended, billing continues on schedule; otherwise a new period starts and is billed right away. Its oldest unpaid invoice is charged again.

Customers can also cancel on their own in the billing portal, and pause or skip if you allow it.

Failed payments

When a renewal is declined, the subscription becomes Past due and Bias retries the payment 1, 3, 7 and 14 days after the first failure, or 3 and 7 days after for a bank debit. After each failure, Bias emails the customer a link to pay or update their payment method. A new payment method is charged as soon as it’s added. With Send invoices, the subscription becomes Past due once an invoice is overdue.

A bank debit takes a few business days to settle. The invoice is marked Paid once it does. A returned debit counts as a declined payment.

The Payment retries card shows each attempt, why it was declined, and when the next one runs. Some declines, such as a lost or stolen card, aren’t retried. Bias then waits for a new payment method, which is noted on the card.

Choose what happens when retries run out, or 15 days after the subscription became past due, in Settings → Subscriptions → Failed renewals: Cancel the subscription, Pause the subscription, or Mark the invoice uncollectible, which makes the subscription Unpaid until the customer pays. If a payment is still processing then, Bias waits for it to finish. If a payment that was already processing succeeds after the subscription is canceled for nonpayment, it’s refunded.

Emails to customers

Bias emails subscribers the reminders that state auto-renewal laws call for. Each one lists what they’re subscribed to, the next charge and its date, the payment method, and how to cancel: with a Manage subscription button that opens the billing portal, or, if email sign-in is off, by contacting you at the contact email in your branding settings.

• Trial ending: 7 days before a free trial converts to paid, or 3 days before for trials of a week or less. No reminder is sent for trials of 3 days or less.
• Upcoming renewals: 30 days before each renewal of a plan billed less often than monthly, such as quarterly or yearly.
• Yearly reminders: on each anniversary of the signup, for plans billed monthly or more often, and between renewals of plans billed less than once a year.

They also get a receipt for each payment, an email when a renewal charge fails, and, for bank debits, 10 days’ notice before a debit of a different amount. Turn any of these off in Settings → Customer emails, where you can also preview them. If you turn off a reminder, you’re responsible for sending it yourself. See customer emails.

Test in a sandbox

Renewals and retries in a sandbox run on the same schedule as in live mode, so a daily price is the quickest way to watch a subscription renew. Use the test cards that save but fail later, such as 4000 0000 0000 0341 (insufficient funds) and 4000 0000 0000 0358 (lost card), to see failed payments end to end. A renewal paid from bank account 000555555501 succeeds and is then returned for insufficient funds after settling, which creates a lost dispute and leaves the subscription active.

To build subscriptions into your own app, see the Subscriptions API.