Stripe subscription billing

Before you accept paid Stripe subscriptions, make sure you have: 1. Stripe enabled in Booknetic SaaS → Settings → Payment methods. 2. Your Stripe Publishable...

Version:

SaaS
- Regular
- SaaS

Read this first

If you haven't set up the Stripe webhook yet, start with Setting up Stripe webhook. This page explains the full Stripe subscription billing flow after your webhook is wired up.

Stripe billing in Booknetic SaaS depends on two parts working together:

Stripe collects the card payment, stores the card, creates the subscription, renews invoices, retries failed payments, and sends payment receipts.
Booknetic SaaS sends tenants to Stripe Checkout, stores the subscription result, updates the tenant's plan and expiry date, and listens for Stripe webhook events.

In plain English: Stripe owns the payment; Booknetic SaaS mirrors the subscription state your tenant needs inside the SaaS platform.

Before you start

Before you accept paid Stripe subscriptions, make sure you have:

Stripe enabled in Booknetic SaaS → Settings → Payment methods.
Your Stripe Publishable key and Secret key saved in Booknetic SaaS.
A working Stripe webhook endpoint connected to your site.
The required webhook events selected in Stripe:

invoice.paid
customer.subscription.deleted

The webhook is not optional for subscription billing. The first payment can look successful because the tenant returns from Stripe Checkout, but renewals and cancellation updates depend on the webhook.

For webhook setup steps, use the companion guide: Setting up Stripe webhook.

The Stripe billing model in one flow

A Stripe subscription in Booknetic SaaS follows this path:

Tenant chooses plan
→ Stripe Checkout opens
→ Tenant enters card
→ Stripe creates the subscription and first invoice
→ Stripe sends invoice.paid webhook
→ Booknetic SaaS activates or extends the tenant plan
→ Stripe repeats the invoice cycle on the next renewal date

The important detail is that Stripe and Booknetic SaaS do not store the same thing.

Stripe stores	Booknetic SaaS stores
Customer card and payment method	Tenant plan and expiry date
Stripe Customer	Tenant account
Stripe Subscription	Active subscription reference
Stripe Invoice	Billing/payment history reference
Renewal schedule and retry logic	Whether the tenant should have SaaS access

This separation is normal. It means card management, receipts, failed-payment retries, and refunds happen in Stripe, while plan access and tenant expiry happen in Booknetic SaaS.

Tenant signup and first payment

When a tenant chooses a paid plan and selects card payment, Booknetic SaaS sends them to Stripe Checkout.

The tenant flow looks like this:

The tenant opens Billing in their tenant panel.
The tenant chooses a plan and billing cycle, such as monthly or annual.
The tenant selects card payment.
Stripe Checkout opens in the browser.
The tenant enters their card details on Stripe's secure page.
Stripe captures the first payment and creates the subscription.
Stripe redirects the tenant back to Booknetic SaaS.
Booknetic SaaS marks the billing row as paid, saves the active subscription reference, and updates the tenant's expiry date.

Booknetic SaaS does not store the tenant's full card number. Card details are entered and stored on Stripe's side.

Recurring renewal flow

After the first payment, Stripe continues the subscription automatically.

On each renewal date:

Stripe creates the next subscription invoice.
Stripe charges the saved card.
If the charge succeeds, Stripe sends the invoice.paid webhook to your Booknetic SaaS site.
Booknetic SaaS records the paid renewal and extends the tenant's expiry date.

If the webhook is missing, wrong, or rejected, Stripe may show the invoice as paid while Booknetic SaaS does not extend the tenant expiry. In that case, fix the webhook first, then review the affected tenant.

Cancellation flow

Cancellation is where it is especially important to understand which system owns what.

Cancellation from Booknetic SaaS

When a subscription is cancelled from the Booknetic SaaS billing flow, Booknetic SaaS sends a cancellation request to Stripe for the active subscription.

After Stripe deletes/cancels the subscription, Stripe sends this webhook event back to Booknetic SaaS:

customer.subscription.deleted

Booknetic SaaS then clears the active subscription reference and marks the tenant as unsubscribed/cancelled in the SaaS billing state.

A cancellation is not the same as deleting the tenant. The tenant account and tenant data remain unless you delete the tenant separately. For the safe cancellation and deletion order, see How to cancel or delete a tenant in Booknetic SaaS.

Tenant-initiated cancellation and card updates

Booknetic SaaS does not currently provide a Stripe Customer Portal button for tenants.

That means tenants cannot self-serve these Stripe actions from a Stripe-hosted portal inside Booknetic SaaS:

update the card on file;
view or download all Stripe invoices from a portal;
change billing address from a Stripe portal;
pause a subscription from a Stripe portal.

If a tenant wants to use a different card, use one of these options:

Ask the tenant to cancel the current subscription and subscribe to the same plan again. The new Stripe Checkout session lets them enter a new card.
Help the tenant from your Stripe Dashboard if you manage billing manually for them.

Do not tell tenants to look for a Stripe Customer Portal link in Booknetic SaaS, because that self-service portal is not currently wired up.

What Stripe subscription states mean

Stripe may show a subscription state that does not look exactly like the tenant state you see in Booknetic SaaS. Use this table when comparing the two.

Stripe state	What it means in Stripe	What to expect in Booknetic SaaS
`incomplete`	The subscription was created, but the first invoice has not been paid successfully yet.	Booknetic SaaS should not treat the plan as fully paid until payment succeeds. The tenant may remain on their previous, trial, expired, or not-subscribed state.
`active`	The subscription is paying on schedule.	The tenant should have an active plan and an expiry date based on the last confirmed payment.
`past_due`	The latest invoice failed and Stripe is retrying according to your Stripe settings.	Booknetic SaaS does not run Stripe's retry schedule. The tenant may keep access until their current paid period ends, but the expiry will not extend until an `invoice.paid` webhook is received.
`unpaid`	Stripe has stopped retrying or considers the invoice not collectible under your Stripe settings.	Booknetic SaaS does not extend the tenant period without a paid invoice. If the tenant's expiry date passes, their access follows your expired-plan setup.
`canceled`	The subscription was cancelled/deleted in Stripe.	After the `customer.subscription.deleted` webhook is accepted, Booknetic SaaS clears the active subscription reference and treats the tenant as unsubscribed/cancelled.

The key rule is simple: successful payments extend access; failed payments do not. Stripe can retry failed payments, but Booknetic SaaS extends tenant access only when it receives a successful payment event.

Failed payments and dunning

Dunning means the failed-payment recovery process: retries, failed-payment emails, reminders, and final collection rules.

For Stripe subscriptions, dunning is handled by Stripe, not by Booknetic SaaS.

Booknetic SaaS does not send built-in “your payment failed” emails to tenants for Stripe subscription failures. If you want tenants to receive failed-payment reminders, configure that in your Stripe Dashboard using Stripe's billing and email settings.

Booknetic SaaS listens for successful paid invoices and subscription cancellation. It does not replace Stripe's own failed-payment recovery tools.

For Stripe's own subscription concepts and retry behavior, see Stripe's subscription overview: https://docs.stripe.com/billing/subscriptions/overview

Stripe Product sync for plans

When you create or edit paid plans in Booknetic SaaS, Booknetic can sync the plan to Stripe as a Stripe Product/Price so checkout can charge the correct plan and cycle.

In normal use, you do not need to create Stripe products by hand for each Booknetic SaaS plan. Configure your plans in Booknetic SaaS, then let the Stripe checkout flow use the product/price data Booknetic creates.

For plan setup details, including capabilities, limits, default plans, and hidden plans, see Plans and plan capabilities in Booknetic SaaS.

Note: If you change a plan name, product naming in Stripe may update going forward, but historic Stripe invoices will not be rewritten. Treat old invoices as accounting records that keep the details from the time they were created.

Test mode and live mode

Stripe test mode and live mode are separate environments.

If your Stripe account is in test mode but your Booknetic SaaS site is live, real tenants will not be charged successfully. Make sure your live SaaS site uses live Stripe keys:

pk_live_... for the Publishable key;
sk_live_... for the Secret key;
the live webhook signing secret for the live webhook endpoint.

If you switch from test mode to live mode, update the keys in Booknetic SaaS and create/check the matching live webhook endpoint in Stripe. Test-mode webhook secrets and live-mode webhook secrets are not interchangeable.

API version note

The current Booknetic SaaS Stripe integration uses a Stripe API version compatible with:

2025-07-30.basil

Most customers do not need to change anything because of this. If Stripe webhook events are delivered successfully but renewals still do not update in Booknetic SaaS, contact support with the Stripe event ID and affected tenant so the payload can be reviewed.

Common questions

How do I refund a tenant?

Process the refund in your Stripe Dashboard.

Booknetic SaaS does not automatically adjust the tenant expiry date, plan period, or billing access after a Stripe refund. If you refund a tenant, review whether you also need to adjust that tenant manually in Booknetic SaaS.

Example: if you refund a renewal but want the tenant to keep access until a specific date, check the tenant's plan and expiry state after the refund.

Can a tenant pause their subscription?

There is no native pause flow in Booknetic SaaS for Stripe subscriptions.

The practical options are:

cancel the subscription and let the tenant subscribe again later;
handle an exceptional pause manually in Stripe and adjust the tenant state manually if needed.

Do not describe this as a built-in pause feature unless your product version adds one later.

What if Stripe says `past_due` but the tenant still looks active in Booknetic SaaS?

That can happen.

past_due means Stripe is retrying the failed invoice. Booknetic SaaS may still show the tenant as active because the tenant already paid for the current period. If Stripe later succeeds, the invoice.paid webhook extends the expiry. If Stripe never succeeds, the tenant will not receive the next extension.

Check both places:

Stripe subscription/invoice state.
Tenant expiry date in Booknetic SaaS.

Why did a renewal payment not extend the tenant expiry date?

Renewals reach Booknetic SaaS through the invoice.paid webhook.

Check:

the webhook URL is correct;
the endpoint is subscribed to invoice.paid;
the webhook signing secret in Booknetic SaaS is current;
Stripe shows a successful 2xx delivery for the invoice event.

If those all look correct, contact support with the Stripe event ID and affected tenant.

Why doesn't my tenant get an email after the first payment?

Payment receipts and many billing emails are controlled by Stripe settings.

Booknetic SaaS workflow notifications are separate. If you want a tenant email from Booknetic after subscription events, review your Booknetic SaaS workflow events and notification setup. If you want Stripe receipt or failed-payment emails, configure them in Stripe.

Can I manually create an invoice in Stripe and have Booknetic SaaS extend the tenant?

No, not automatically.

Manually created Stripe invoices are not the normal subscription-renewal path in Booknetic SaaS. If you invoice a tenant manually in Stripe, update or review the tenant state manually in Booknetic SaaS as well.

Can tenants update their card without cancelling?

Not through Booknetic SaaS at the moment, because Stripe Customer Portal is not wired into the tenant panel.

Use the cancel-and-resubscribe flow, or help the tenant from the Stripe Dashboard if you manage their billing directly.

Troubleshooting checklist

First payment succeeded in Stripe, but the tenant did not activate

Check:

the tenant returned from Stripe Checkout successfully;
the Stripe webhook is configured;
the webhook secret is saved in Booknetic SaaS;
the Stripe event delivery returned 200;
the tenant selected the intended plan and billing cycle.

If the first invoice was never paid, the Stripe subscription may remain incomplete. In that case, Booknetic SaaS should not activate the paid plan yet.

Renewal is paid in Stripe, but Booknetic SaaS still shows the old expiry

This is usually a webhook issue.

Fix the webhook first, then review the affected tenant. The companion webhook guide covers the setup: Setting up Stripe webhook.

Tenant says they changed their billing email, but Stripe receipts still go to the old email

Stripe receives the tenant email when the checkout session is created. If the tenant later changes their email inside Booknetic SaaS, that does not automatically update the email already stored on the Stripe subscription/customer.

Update the billing email in Stripe if the tenant needs future Stripe receipts sent somewhere else.

Tenant cancelled, but they were charged again

Check the Stripe subscription timeline.

Common causes:

the final invoice was issued before cancellation;
the cancellation did not reach Stripe;
the customer.subscription.deleted webhook did not reach Booknetic SaaS;
the tenant was deleted before provider cancellation was verified.

Use the cancellation guide before deleting tenants: How to cancel or delete a tenant in Booknetic SaaS.

Use 3–5 Booknetic-side screenshots when preparing the published page.

Recommended captures:

Booknetic SaaS → Settings → Payment methods → Stripe section showing the Publishable key, Secret key, and Webhook secret fields, with all sensitive values blurred.
Booknetic SaaS → Plans → plan editor showing paid monthly/annual pricing or Stripe-related plan sync context if visible in the UI.
Tenant panel → Billing showing plan cards and card/Stripe payment option before checkout.
Tenant panel → Billing → current plan/subscription state showing the active plan and expiry after a successful payment.
Tenant panel → Billing → Cancel subscription button showing where cancellation starts.

Do not capture:

Stripe Dashboard subscription lists;
Stripe Dashboard invoice details;
Stripe webhook delivery screens;
Stripe Checkout pages;
any page that exposes card, customer, secret key, webhook secret, or live billing data.

For Stripe-owned UI, link to Stripe's own documentation instead: https://docs.stripe.com/billing/subscriptions/overview