Billing (Stripe)
@delightstack/stripe is Stripe billing for SvelteKit apps on Cloudflare Workers — define your
plans and meters in code, sync them to Stripe, handle webhooks, and gate features by subscription.
Features
Section titled “Features”- Config-driven plans & meters — declare them once with
defineBillingConfig; sync to Stripe. - Subscriptions — checkout, subscription state, and a webhook-driven sync into your database.
- Metered usage — report usage events for usage-based pricing.
- Webhooks — verified webhook handling with
handleWebhook. - Subscription guards — gate SvelteKit routes by plan/entitlement.
Install
Section titled “Install”pnpm add @delightstack/stripe stripe| Import | Use |
|---|---|
@delightstack/stripe/server | defineBillingConfig, createBillingHandle, syncSubscription, syncAll, reportMeterEvent, handleWebhook, getStripe |
@delightstack/stripe/sveltekit | createBillingGuards |
@delightstack/stripe/client | reactive Svelte 5 billing client |
1. Define your billing config
Section titled “1. Define your billing config”import { defineBillingConfig } from '@delightstack/stripe/server';
export const billing = defineBillingConfig({ secret_key: env.STRIPE_SECRET_KEY, plans: [ { id: 'pro', name: 'Pro', price: 2000, interval: 'month', entitlements: ['premium'] }, ], meters: [ { id: 'ai-tokens', name: 'AI tokens', event_name: 'ai_tokens' }, ],});2. Sync products & handle webhooks
Section titled “2. Sync products & handle webhooks”import { createBillingHandle } from '@delightstack/stripe/server';
export const billingHandle = createBillingHandle({ config: billing, getDb: (event) => event.platform.env.DB,});syncAll() pushes your plans/meters to Stripe; handleWebhook() verifies incoming events and
syncSubscription() reconciles them into your database.
3. Gate routes
Section titled “3. Gate routes”import { createBillingGuards } from '@delightstack/stripe/sveltekit';
const { requirePlan } = createBillingGuards(billing);
export const load = (event) => { requirePlan(event, 'pro'); // redirect / 402 if not subscribed};4. Report metered usage
Section titled “4. Report metered usage”import { reportMeterEvent } from '@delightstack/stripe/server';
await reportMeterEvent(billing, { meter: 'ai-tokens', value: 1200, customer });How plan bits are written
Section titled “How plan bits are written”A subscription sync writes the org’s plan integer through the auth RPC. The package owns only
the bits of entitlements that some plan in plans grants, at their index in entitlements. It
reads the org (getOrg), sets or clears those bits, and leaves every other bit alone, so flags
your app keeps in plan survive every webhook. Nothing is written when the value would not
change. Pass an auth RPC that has getOrg (the @delightstack/auth server does); without it the
sync replaces the whole integer.
onSubscriptionChange
Section titled “onSubscriptionChange”The hook runs after every re-sync of a customer: the customer.subscription.* and
subscription-mode checkout.session.completed webhooks, and the POST /subscription,
DELETE /subscription and POST /sync routes. It describes the most relevant subscription
(active, then trialing, past_due, canceled). A customer whose only subscription is incomplete,
unpaid or paused is reported with that status, plan_id: null and no entitlements. A
customer with no subscription at all is not reported. Webhook calls carry event_id; key any
non-idempotent side effect by it.
Testing against a fake Stripe
Section titled “Testing against a fake Stripe”export const billing = defineBillingConfig({ secret_key: env.STRIPE_SECRET_KEY, publishable_key: env.STRIPE_PUBLISHABLE_KEY, stripe_api_url: dev ? env.STRIPE_API_URL : undefined, // e.g. 'http://localhost:12111'});stripe_api_url points every Stripe API call at another server. Its protocol, host and port go
to the Stripe SDK; the path is ignored. The client always uses the SDK’s fetch HTTP client, so
it works on Cloudflare Workers.