How to manage subscription renewals: aligning Vevee with Stripe
A user signs up on Jan 15. Stripe charges them on the 15th of every month. Your metering layer resets on the 1st. Two clocks. One angry support ticket per cycle.
Last updated: 2026-05-30
Two clocks, one quota
The naive integration has Stripe owning billing dates and Vevee owning quota cycles, and nobody telling them about each other. Stripe charges the user on Jan 15, Feb 15, Mar 15. Vevee resets their counters on Feb 1, Mar 1, Apr 1. On the 1st the user sees a fresh quota two weeks before their next charge - over-served. On the 15th they renew and nothing changes in the dashboard - they keep ticking down toward the next reset on the 1st. The drift is invisible until a power user emails support asking why they got more than they paid for, or why they ran out a week early.
Why a "reset on renewal" function is the wrong shape
The obvious instinct is to add a resetCycle endpoint and call it from the Stripe webhook. Don't. Two problems. One: it requires you to think of cycles as discrete events, but Stripe webhooks aren't reliable enough for that - a missed delivery means a user is stuck in last month's window forever. Two: it tempts you to delete or zero-out counters, which makes analytics useless ("how many images did this user generate last cycle?" becomes unanswerable).
The right shape: a per-subscription anchor
Vevee now stores an optional cycle_anchor_at per subscription. When set, it's used as the relative-period anchor instead of started_at or the plan-level calendar default. Pass it as cycleStart on upsertSubscription. That's the whole API surface - no new endpoint, no special path, no migration. Counter rows are keyed on (user, group, period_start); when the anchor advances, the next metered event computes a new period_start and inserts a fresh counter row. Old rows stay queryable. Events are append-only and untouched.
The Stripe webhook, in full
You wire it once. customer.subscription.created and customer.subscription.updated both carry current_period_start; handling them identically makes the integration idempotent for free. Each call passes the subscription ID, the plan id derived from the price id, and cycleStart set to new Date(sub.current_period_start * 1000).toISOString(). Re-delivered webhooks re-assert the same anchor - no double-reset bug. Stripe pauses, prorations, and coupons all flow through because you're reading the canonical period_start from the source of truth.
What renewal does (and what stays put)
On a same-plan renewal with a new cycleStart, Vevee writes exactly one row to subscription_events with event_type = renewed. That gives you renewal counts, MRR-style timelines, and churn analytics straight out of the audit table - no extra plumbing. Retried webhooks that carry the same cycleStart stay no-ops, so the count reflects real billing cycles, not delivery flakiness. Lifetime plans skip the renewed event entirely. What does not change: the events log is append-only and never trimmed, so every prompt and render the user ever generated remains queryable forever; and counter rows from the previous cycle aren't deleted, they're simply no longer the active row once period_start advances.
Three call shapes, three intents
cycleStart accepts three values. An ISO string sets the anchor - call this from your Stripe webhook. Omitting the field preserves whatever anchor is currently stored - call this from signup, login middleware, or any code path that doesn't know the renewal date and shouldn't guess. Passing null explicitly clears the anchor - call this when migrating a user off external billing, e.g. converting them to a comp plan or an enterprise sponsorship where the plan's default anchor takes over again. The three shapes cover every realistic integration pattern without growing the API surface.
The 30-day footnote
One detail to flag: for relative monthly periods, Vevee uses a 30-day window from the anchor. Stripe's real months vary from 28 to 31 days. If you set the anchor once and never touch it again, the two clocks would drift by up to three days per year. The reason this doesn't matter in practice is that your renewal webhook re-asserts cycleStart every cycle - Stripe's exact current_period_start, which already accounts for real calendar months. Drift never accumulates because the anchor moves with Stripe.
Where this leaves you
You keep Stripe as the source of truth for billing. You keep Vevee as the source of truth for usage. One field on one method call connects them. Your dashboard's "remaining this cycle" number now matches your customer's expectations, your charts still answer historical questions, and you never need to write - or maintain - a counter-reset path of your own. That's the entire point of a metering layer: it should track the clocks you already pay for, not invent new ones.
More from the blog
The race condition in "if (usage < limit)" that is costing your AI app money
A user at nine of ten images opens six tabs and clicks generate in all of them. Every tab passes your limit check, every tab gets an image, and you pay for all six. The bug is one read-then-write - and your unit tests will never catch it.
engineering · 9 minHow to build a credits system for your AI app (ledger design, rollover, refunds)
A user emails: "I had 40 credits this morning and now I have 12, and I only made one image." If your balance is a column you mutated, you cannot answer that email. Here is the ledger design that can.
thinking · 7 minStripe metered billing for AI apps: what it solves and what it does not
You are sketching the pricing page for your AI app and every plan ends in "per generation" - because your costs arrive per generation. Stripe meters the charging half beautifully. The question is what happens at request time.
thinking · 8 minHelicone is in maintenance mode. An honest map of where to go
Somewhere in your codebase a base URL points at Helicone, and it has been quietly doing four jobs at once. The team got acquired - good for them - but now you have to replace each job separately, and the one everyone forgets is the one your users will exploit.
engineering · 8 minHow to stop free-tier abuse without killing signups
The usage graph spikes at 3:41am: four thousand free generations in an hour, all from disposable emails. Your first instinct is a credit-card wall. That instinct will cost you more than the abuse does.
thinking · 7 minTokens, credits, or requests: choosing the unit you meter (and price)
The pricing doc has three columns: $9, $19, $49. The prices took twenty minutes. The row above them - what a user actually gets for the money - has been blank for a week. That blank row is the real decision.
engineering · 3 minI rewrote my cancel flow with one LLM call. It argues better than I do.
The cancel flow is where SaaS revenue goes to die politely. "Are you sure? You'll lose access to Premium features" has never changed a single mind - but reminding a user of their own 312 generations this month is an argument.
engineering · 3 minThe trial-ending email everyone sends is the same email. Here's the one that converts
"Your trial ends in 3 days! Upgrade now to keep access." You've received a hundred of these. You've deleted a hundred of these. The email fails because it's about your product, not about the user's trial.
engineering · 3 minStop making users do math on your pricing page: recommend their plan from their own usage
Every pricing page asks the user to solve an estimation problem: "How many credits will I need per month?" Nobody knows. But for any user who has actually used your product, their usage history IS the answer - here is how to put it on the pricing page.
engineering · 3 minWin-back emails fail because they're written for "users." Write them for the one user instead.
Every dormant-user campaign in history: "We miss you! Here's what's new." Open rate: pity clicks. The email fails because it's about your changelog - and the user left because of something in their experience.
engineering · 3 minSpotify Wrapped is a growth loop, not a year-end gimmick. Ship one for your AI app in an afternoon.
Spotify Wrapped works because people love seeing their own behavior reflected back as a story. Every AI app with usage data can run that loop monthly - and almost none do, because turning usage rows into narrative used to be a content problem. It is now a schema problem.
engineering · 3 min"AI-personalized copy converts better" - prove it or delete it. Here is the 40-line A/B harness
Half of the "we added AI personalization and conversions went up 40%" posts have no control group. The other half measured clicks, not revenue. If LLM-generated copy is going in front of your paywall, you owe yourself a real experiment - and the harness is tiny.
thinking · 3 minAI personalization without the creepy part: opt-out as a first-class return value
Users have learned that "personalized for you" means "we mined everything you ever did" - and the backlash is rational. When I added LLM-generated personalized copy to my app, the part I sweated was not the generation. It was making declining it a real, respected choice.
engineering · 3 minI stopped walking into demo calls blind: every lead now comes with a usage brief written 10 seconds before the call
Founder-led sales has one structural weakness: you have no time to prep. If the lead has touched your product, their usage history is the best discovery call you'll never have to run - here's how I turn it into a one-page brief, automatically, before every call.
thinking · 4 minThe "founder email" converts like crazy and scales like garbage. Here is the middle path.
A personal email from the founder converts trials at a rate no automated sequence touches - and at 50 signups a week it stops scaling. The middle path: drafts generated from each user's real usage, that you read, edit, and send yourself.
engineering · 3 minChurn doesn't announce itself. My Monday Slack digest does it instead.
Every founder finds out about churn the same way: the cancellation email. By then the user has been gone for weeks - the decision happened earlier, quietly, in their usage. So I made the metering tables write me a memo.
engineering · 3 minHalf of every support ticket is asking what the user already did. Attach the answer instead.
The ticket says "it's not working" - and the next twenty minutes go to figuring out who this user is, what plan they're on, and whether "it" is a bug, a quota, or a misunderstanding. The actual fix usually takes two. All of that context lives in your usage data; here is how to attach it to every ticket automatically.
thinking · 4 minYour users are telling you your roadmap, in writing, every day. It's in your prompt logs
Founders pay for interviews and beg for survey responses to learn what people are actually trying to do. Meanwhile, your users type their intent into your product, in their own words, hundreds of times a day - and nobody performs for a prompt box.
engineering · 5 minHow to reset usage limits when a subscription renews
A weekly plan, used twice. First week: ten generations. Second week: zero, because the counter never reset. This is the cron-job mistake - and the fix is one field on one call.
engineering · 5 minStop hardcoding your pricing page - render it from your metering layer
Every B2B SaaS I have shipped repeats the same mistake: plans live in two places - the dashboard that enforces them, and a const PLANS = [...] on the marketing site. They drift within a quarter.
thinking · 4 minMeter AI by user, not by account - your margin depends on it
A few users will cost you 100x what your median user costs. If you only meter at the account level, you will not see them coming until your gross margin is gone.
engineering · 5 minreserve / commit / release: the only correct way to enforce AI quotas
Every team I have seen build per-user AI metering has shipped a version of canUse → call OpenAI → track. It looks correct in single-threaded tests. It is broken in production.
thinking · 4 minWhy Stripe Billing is not enough for AI products
Stripe is excellent at one thing: turning usage into invoices. AI products need three other things, and Stripe does not do any of them.
engineering · 6 minDynamic onboarding: a different first step for every user
A teacher and a student sign up the same minute. The teacher wants to build a quiz; the student wants to summarize a lecture. Your onboarding shows them both the same five-step checklist. One of them bounces.
thinking · 6 minPaywall copy that rewrites itself for every user
Your paywall says "Upgrade to Pro for unlimited generations." A teacher reads it and shrugs. A student on a budget reads it and closes the tab. The same words, two lost conversions - because the words were written for nobody in particular.
engineering · 5 minAdd usage limits to your AI app in 10 minutes (no backend required)
You shipped an AI feature on Friday. By Monday one user had burned $212 of OpenAI credit on your free tier. The fix is not a TODO comment that says "add rate limiting" - it is two method calls.
engineering · 5 minMeter LLM tokens, not requests - your flat per-request limit is lying
Two users, both at 100 requests. One sent tweets, the other sent novels. Your cost for them differed by 400x. Your limit treated them identically - and your margins noticed.
engineering · 7 minThe upgrade nudge that writes itself: convert free users before they hit the wall
By the time a user hits your paywall, they are blocked, annoyed, and halfway to a competitor’s signup page. The best moment to make the pitch was three days earlier - when they were winning. Here is how to catch it, automatically, for every user at once.
engineering · 5 minOne event, two limits: gate your premium model without forking your code
The premium model launch was going great until you looked at the bill: free users had figured out the good model and were living on it. You need a sub-limit. You do not need a second code path.
engineering · 5 minTest mode: break your pricing in the sandbox, not on your customers
You changed the free tier from 10 to 25 generations and somehow locked out every Pro user for an hour. Nobody tested it, because testing it meant tracking fake events into production analytics. There is a mode for this.
engineering · 5 minThe support ticket that solves itself: log the prompt behind every AI event
A user says your AI feature "broke" on Tuesday. You have a charge for the call, a timestamp, and no idea what they asked or what the model said. The evidence existed for exactly one request - the one you didn’t log.
engineering · 5 minYour funnel has one broken step. Find it without writing a single SQL query.
A hundred people saw your paywall this week. Three upgraded. Is that a copy problem, a price problem, or did ninety of them never generate anything worth paying for? You cannot fix what you cannot locate.
engineering · 5 minOne user, three ghosts: fix your funnel with identify()
Your funnel says signup conversion is 4%. It is actually 11%. The missing users didn’t bounce - they came back on another tab and got counted as someone new. Every number downstream of that split is wrong.
thinking · 5 minThe usage bar that sells the upgrade (build it with a public key in an afternoon)
An invisible limit feels like a trap. A visible one feels like a fuel gauge. Same quota, same plan, same user - and a measurably different reaction when the wall finally arrives.
engineering · 6 minHow to cancel a subscription without burning the bridge (or your data)
The user cancels. Do they drop to a free tier, or lose access when the paid month runs out? Those are different products, different SDK calls, and different mistakes when you get them wrong.