How subscription billing works in Quarry

Billing bugs are the most expensive bugs a SaaS can have. Quarry keeps the Stripe integration small, explicit and testable.

The kit itself is a one-time purchase. The plans and checkout below are what your customers use inside the product you ship — not how you buy Quarry.

The flow

1. An organization owner picks a plan; the app creates a Stripe Checkout session with the organization ID in metadata.
2. Stripe redirects back to the app, and delivers a checkout.session.completed webhook.
3. The webhook handler verifies the signature, fetches the subscription and writes it to the subscription table — the only write-path for billing state.
4. Later plan changes and cancellations arrive as customer.subscription.updated / deleted events and go through the same path.

Why one write-path matters

Because every state change funnels through applySubscriptionState, the whole flow is unit-testable with fake events — no Stripe account needed. The database is always a faithful mirror of Stripe, and the UI only ever reads from the database.

Trying it locally

Run the Stripe CLI with stripe listen --forward-to localhost:3000/api/webhooks/stripe and use the test card 4242 4242 4242 4242. The kit works without any Stripe keys, too — billing UI simply shows as not configured.