subscribe and manage

Subscribing is a redirect to the payment provider’s checkout page; managing is a redirect to the customer portal.

In the admin dashboard, settings → billing → subscribe opens checkout. Spirby:

Looks up or creates a customer record at the provider, keyed to your organization id.
Refuses to start a second checkout if you already have a live subscription. “Live” includes active, trialing, past_due, unpaid, paused, and incomplete, use the customer portal instead.
Hands you off to the provider’s checkout page with a return url back into spirby.

Two admins clicking subscribe at the same time are serialized, only one customer record is created at the provider, even on a race.

after checkout

When you finish checkout, the provider redirects you to spirby’s success page with a session id. Spirby reconciles the session against your customer record:

If the session belongs to a different org, spirby refuses to apply it. (Never trust a session id from the url to mutate org state.)
If the session does not yet have a subscription attached (you closed the tab too early), spirby returns a pending state and the webhook fills it in.
Otherwise spirby records the new payment_subscription_id and subscription_status and you are subscribed.

The provider also fires a webhook back to spirby; the webhook is the source of truth for ongoing status changes.

customer portal

settings → billing → manage subscription opens the provider’s customer portal. From there:

update card on file
view invoices
change plan (if you are on a tier system)
cancel

You return to spirby’s billing page on close. Cancellation does not delete data; it moves the org through grace as described in trial and grace states.

payment failures

If a renewal fails, the subscription goes to past_due. Spirby leaves the org alive but flags it; the customer portal is the place to update card details. If past_due does not resolve, the provider eventually moves the subscription to unpaid or canceled, at that point spirby starts the grace clock.