ProdVerdictStripe Entitlements migration checklist (before you cut over)
Moving from Postgres paid flags to Stripe Entitlements? Pitfalls, dual-write traps, and how to verify billing vs DB before you flip the switch.
Stripe Entitlements can be the billing source of truth for feature access. Your app probably still has has_paid_access, is_pro, or plan in Postgres from before the migration.
The cutover week is when drift hurts most. Two systems think they own access. Neither is wrong until they disagree.
Before you migrate
| Question | Why it matters |
|---|---|
| Which rows are paid in DB but missing in Entitlements? | Orphan paid users lose access on cutover |
| Which Entitlements grants have no DB mirror yet? | New subscribers may bypass your legacy gates |
Are webhooks wired for entitlements.active_entitlement_summary.updated? | Without it, Entitlements changes do not reach your app |
WorkOS documents the sync problem: Stripe tracks billing entitlements, but your app must persist and serve them. Missed webhook handling = stale access.
Dual-write trap
Teams often run:
- Write Entitlements on checkout
- Also flip
is_proin Postgres - Plan to remove step 2 later
"Later" is where bugs live. Step 2 stops updating when someone edits a subscription in the Stripe dashboard. Step 1 fails silently when a webhook returns 200 without writing.
Run both sides until a verifier says they match. ProdVerdict ships an entitlements-migration contract for exactly that comparison.
npx prodverdict check entitlements-migrationGuide: Entitlements migration.
Cutover checklist
- Inventory — export active Stripe subs + DB paid flags + Entitlements grants
- Map features — each product feature → entitlement lookup key → DB column or role
- Wire webhooks — entitlement summary updates, not just
invoice.paid - Verify — run migration contract daily until zero high-severity findings
- Flip reads — app checks Entitlements (or synced table) as primary
- Keep reconcile — scheduled Access check for stragglers on legacy columns
After cutover
Do not delete the reconcile job. Entitlements can be correct while your cached table is stale. Scheduled drift detection catches the gap.
Related:
- Why billing drift happens
- Stripe vs Postgres evidence
- Volunteer for the public study if you want a redacted run on your stack
— mattbaconz
Try it in 60 seconds
Run the fixture demo — no Stripe key or database required.
npx prodverdict@latest check access --config examples/nextjs-stripe/prodverdict.yml --fixtures --fixtures-dir examples/nextjs-stripe/scenarios/fail-revenue-leakRelated posts
Scheduled Stripe–Postgres reconciliation beats PR-only billing tests
Why Access checks belong on a cron, not every pull request — and how to install nightly billing drift detection in GitHub Actions.
July 1, 2026
Stripe webhook idempotency in production (checklist)
Raw body verification, evt_ dedup, return 200 before slow work — the Stripe webhook patterns that stop duplicate charges and silent drift.
June 30, 2026
Stripe and Postgres drift apart. Here's the proof.
Webhooks are not enough. Stripe docs, practitioner writeups, and reconciliation patterns for when billing state and your database disagree.
June 29, 2026
Comments
Guest comments. No account required. Max 300 words.
Loading comments…