# subscriptions.stripe-state Keep one row per subscription in your database, up to date from Stripe's webhooks, without trusting the order they arrive in. Verify each webhook (the event is `{ id, type, created, object }`, exactly what `payments.stripe-checkout`'s `verifyWebhook` returns, so pass that straight in; `object` is the event's `data.object`), load the stored state for its subscription (or null), fold the event in, and store what comes back: ```ts import { verifyWebhook } from "#fune/payments.stripe-checkout@^1"; import { applyStripeEvent } from "#fune/subscriptions.stripe-state@^1"; const event = verifyWebhook(await req.text(), req.headers.get("stripe-signature") ?? ""); const subId = subscriptionIdOf(event); // yours: object.id, or the invoice's subscription const next = applyStripeEvent(await db.load(subId), event); if (next) await db.save(next); // unchanged state saves the same row ``` What it reads: - `customer.subscription.created`, `.updated`, `.deleted`, `.paused`, `.resumed` and `.trial_will_end` carry the whole subscription: a snapshot. The status, the first item's price and quantity, the current period (top level on older API versions, on the item since 2025), the cancellation fields, trial end and latest invoice are taken from it. `.deleted` is always `canceled`. - `invoice.paid` and `invoice.payment_succeeded` clear `paymentFailed` and move `past_due`, `unpaid` or `incomplete` to `active`; `invoice.payment_failed` sets `paymentFailed` and moves `active` to `past_due` (a trial stays `trialing`). The subscription is `object.subscription`, or `object.parent.subscription_details.subscription` on newer API versions, as a string or an expanded object. An invoice without a subscription (a one-off) is ignored. - Every other event type returns the state unchanged (and null stays null). Ordering. Stripe neither promises order nor delivers exactly once, so: - snapshots and invoice events each keep their own clock (`subscriptionEventAt`, `invoiceEventAt`, the events' `created`): an older one than the last applied is ignored, one at the same second applies; - the same event id as `lastEventId` changes nothing; - when a snapshot is older than the last invoice event (a paid invoice arriving before `customer.subscription.created`), the invoice's effect is kept on top of the snapshot's status, so the paid subscription does not fall back to `incomplete`; - an invoice event with no state yet starts one (`active` when paid, `incomplete` when failed), with no price and `subscriptionEventAt` 0, so the first snapshot to arrive still fills it in; - `canceled` is final, as in Stripe: a later snapshot with another status does not revive it (a later cancelled one may still fill in `endedAt`). `entitled` is the access decision: true for `active`, `trialing` and `past_due`. Counting `past_due` is a deliberate grace period while Stripe retries the card (see `subscriptions.dunning-schedule`); an app that wants to cut access at the first failure checks `status == "active" || "trialing"` itself. A customer who cancels at the period end stays `active` with `cancelAtPeriodEnd` true until Stripe sends the deletion. Errors: a malformed event (not an object, no id or type, `created` not a whole number, `object` not an object, a subscription without id, customer or status, an unknown status, a non-integer time field) and an event for a different subscription than the state's (`event is for subscription sub_x, not sub_y`) throw: look the state up by the event's subscription id. Out of scope: several items per subscription (only the first item's price and quantity are kept), schedules, and checkout sessions (store the customer id from `checkout.session.completed` yourself).