DEV Community: Velobase

I stored AI SaaS credits as a single integer. Then the refunds started.

Velobase — Thu, 25 Jun 2026 02:53:09 +0000

Once in a while someone on the team writes up a mistake worth keeping. This one is about billing, from the engineer who lived it.

The scary part of launching an AI SaaS is not the empty launch day. It's the first week when real people start paying, burning credits, retrying requests, asking for refunds, running cron jobs, and finding every shortcut you left in the billing code.

Usage-based billing sounds simple when it's a pricing page. It gets messy when every AI action costs money, every retry can double-charge someone, and every support ticket starts with a number your database cannot explain.

My first credit system was one column on the users table: credits. Buy a pack, it goes up. Run a generation, it goes down. I built it in an afternoon and felt clever about how little code it took.

It held up right until real money showed up. One Tuesday I opened the billing dashboard to a refund, a chargeback from a name I didn't recognize, and a buyer who'd been charged twice because his request timed out and retried. Then an email landed that I still remember word for word:

"Why do I have 37 credits? I bought 500 and I've barely touched this."

I opened a psql shell and ran the only query I had:

select credits from users where id = '...'; -- 37

Thirty-seven. That was the whole story my database could tell me.

Not where the other 463 went. Not when. Not why. Every credits = credits - 1 had overwritten the last number and dropped the reason on the floor. I started a reply with "let me look into this" and realized there was nothing to look into.

That email is why I tore the whole thing out and rebuilt it as a ledger. Here's the model, and the exact moment that taught me each part of it.

A counter only remembers the last thing that happened

With a counter, a customer's entire financial history with your product is one mutable integer that any code path can stomp on. The grant, the spend, the refund, the bug, the fix for the bug. They all collapse into a single number, and the moment they do, you've thrown away every question worth asking:

"Why is this balance what it is?" You'd need every change that produced it.
"Refund this purchase." You'd need to know what that purchase actually granted.
"Did a retry double-credit this user?" You'd need to spot the duplicate write.
"Do our credits reconcile with Stripe?" You'd need a paper trail on both sides.

A single number answers none of them. Once refunds exist, you don't want the balance. You want the list of things that produced it.

Stop updating the balance. Start appending rows.

The fix is boring, which turns out to be the point. You never update a balance again. You write one signed row per change, and you add them up when you need the number.

create table credit_entries (
  id              bigint generated always as identity primary key,
  user_id         uuid not null references users(id),
  amount          integer not null, -- +grant, -spend, never zero
  reason          text not null,    -- 'purchase' | 'generation' | 'refund' | 'signup_bonus' | 'clawback'
  ref_type        text,             -- 'stripe_payment' | 'job' | 'credit_entry'
  ref_id          text,             -- the thing that caused this row
  idempotency_key text,             -- dedupe retries
  created_at      timestamptz not null default now()
);

create unique index on credit_entries (idempotency_key)
  where idempotency_key is not null;

No updated_at. Rows are written once and never touched again. The balance is a sum:

select coalesce(sum(amount), 0) as balance
from credit_entries
where user_id = $1;

Remember the 37-credit guy? On the ledger, his mystery is just his history, in order:

+500   purchase                    2026-05-02 09:14
 -463  generation (x463 entries)   2026-05-02 -> 05-09
-----
   37  balance

Four hundred and sixty-three generations in a week from someone who'd "barely touched it." I pasted the history into my reply. He wrote back: "oh no. that's my cron job."

Closed in one message, because the data could finally speak for itself.

The retry that gives away free credits

This is the one that actually cost me money. Stripe's webhook delivery is at-least-once, not exactly-once. Duplicate deliveries are the contract, not a bug.

One afternoon Stripe fired checkout.session.completed, my handler granted 500 credits, my server was slow to send back its 200, so Stripe assumed the delivery failed and fired the same evt_ id again. Then a third time.

The buyer pinged me an hour later:

"lol why do I suddenly have 1,500 credits"

Same event, same signature, processed three times, and I had paid for it.

The tempting fix is to check before you write. Don't. That's a race, and two deliveries can both pass the check:

// DON'T: two concurrent deliveries both read "not seen" and both grant
const seen = await db.query.creditEntries.findFirst({
  where: eq(idempotencyKey, eventId),
});

if (!seen) await grant(userId, 500);

Let the database be the referee. Derive a key from the source event and let a unique index throw the duplicate away:

await db.insert(creditEntries)
  .values({
    userId,
    amount: 500,
    reason: "purchase",
    refType: "stripe_payment",
    refId: paymentId,
    idempotencyKey: stripeEventId,
  })
  .onConflictDoNothing({
    target: creditEntries.idempotencyKey,
  });

The second and third deliveries hit the index and do nothing. The grant happens once. You didn't have to make your webhook perfectly exactly-once. The data model swallowed the retry for you.

The double-spend that takes ten milliseconds

Picture a user on hotel wifi mashing "Generate" twice, or someone with two tabs open. They have one credit left.

Request A reads the balance: 1. Ten milliseconds later, before A has written anything, Request B reads the balance: 1. Both decide they're fine. Both generate. The balance lands at -1, and they got two images for the price of less than one.

The bug is reading the balance in app code and then writing based on a number that's already stale. Do the check and the write in one transaction, so the read only sees committed rows:

await db.transaction(async (tx) => {
  const { balance } = await tx
    .select({ balance: sql`coalesce(sum(amount), 0)` })
    .from(creditEntries)
    .where(eq(creditEntries.userId, userId));

  if (balance < cost) throw new InsufficientCredits();

  await tx.insert(creditEntries).values({
    userId,
    amount: -cost,
    reason: "generation",
    refType: "job",
    refId: jobId,
    idempotencyKey: jobId,
  });
});

Run it at serializable, or take a per-user advisory lock, so two transactions can't both clear the check against the same starting balance. Using jobId as the key also means a retried job won't get billed twice.

A refund is just one more row

Forty days after a sale, a chargeback rolls in. The credits it paid for were spent two weeks ago. With a counter you're stuck choosing between editing a history you no longer have and pretending it didn't happen.

On a ledger you append:

insert into credit_entries (user_id, amount, reason, ref_type, ref_id)
values ($user, -500, 'refund', 'credit_entry', $original_entry_id);

The balance drops honestly, goes negative if it has to, and the new row points straight at the purchase it cancels.

Same move when you catch a farmed signup: append a negative clawback instead of reaching into a column and hoping you did the arithmetic right. Refund, chargeback, fraud, a manual fix from support. All the same operation. Write one more row.

Boring on purpose, and boring is exactly what you want anywhere near money.

"Won't the SUM get slow?"

At launch, that balance query was 2ms and I never thought about it. Somewhere around four million rows it was 200ms, and the p95 on every endpoint that checked a balance started to crawl.

The fix isn't to abandon the ledger. You periodically write a checkpoint row that snapshots the balance up to a point in time, then sum only what came after it.

The ledger stays the source of truth, and the checkpoint is a cache you can rebuild any time you stop trusting it. Don't build it before a profiler asks you to. An index on (user_id, created_at) carries you further than you'd guess.

One more habit worth starting early: the day you pay affiliates or hand out referral bonuses, make the movement double-entry. Every credit out of one account is a credit into another, so the books always sum to zero. The first time mine didn't, it was off by a single cent, and double-entry meant I caught it that afternoon instead of six weeks later in a reconciliation nobody had scheduled.

What I'd tell past me

Store integer units, never a float. Float math is how you wake up to balances ending in 0.000001 that drift over time.
Never delete a ledger row. Wrong entry? Append a reversal. A DELETE breaks the audit trail for good.
Give every entry a reason and a reference to whatever caused it. That one column is the difference between answering a dispute in ten seconds and guessing.
Keep a cached balance if you want the speed, but treat the ledger as the only truth and re-derive the moment the two disagree.

The honest tradeoff: this is more code than credits -= 1. It's also the difference between reading a customer his own history back and typing "let me look into this" with nothing to look into.

We kept rebuilding this same stack for AI products: Stripe checkout, usage-based billing, usage metering, customer credits, refunds, idempotent webhooks, and a ledger that support can actually explain. So we open-sourced it as Harness, MIT-licensed: github.com/velobase/velobase-harness.

If you're building an AI SaaS and don't want your first real users to become your billing test suite, it may save you a few painful weeks.

If you've run this in production: how do you handle the SUM-vs-snapshot tradeoff? Running totals, checkpoint rows, a cached balance you reconcile on a cron? I'd genuinely like to hear what held up.

AI can write the code. It can't tell you when the product is done.

Velobase — Thu, 18 Jun 2026 13:00:00 +0000

I built an AI slide-deck generator on top of Velobase Harness — type a topic, get a presentation. The AI had a demo running almost immediately: it wrote an outline, generated the slides, exported a file. On screen, it looked finished.

Here's it running:

It wasn't. All it had proven was that one user could make one deck one time.

A real product is a different animal. It has to handle a hundred people generating at once, bill each of them correctly, recover when a step dies halfway, review its own output and redraw the bad parts, and export a PPTX that actually opens in PowerPoint. None of that showed up in the demo — and the AI didn't think to add it, because I hadn't told it to.

That turned out to be the whole lesson of the project: when you build with AI, the hard part isn't describing the feature. It's defining what "done" means.

Harness gave me the boring foundation — auth, payments, credits, admin, database, queues, object storage, deployment. That stuff shouldn't be rebuilt for every new idea, so I didn't. It let me point the AI at the only part that was actually mine: the PPT generation itself.

And that's where "looks done" and "is done" kept pulling apart. Four places made it obvious.

Concurrency. AI treats "it worked once on my machine" as "the feature is complete." But 100 users generating decks of 10–20 slides each is not one big task you run serially in a single worker. The instruction that actually works: split the pipeline into plan → slide → finalize queues, generate each slide as its own job, let workers scale out, and don't let third-party image polling hog a worker slot. Then write a test that proves concurrent generation works — not that one deck succeeds.

Billing. Tell the AI "deduct credits when generating," and it'll deduct once, up front, and call it done. A real product needs a state machine: reserve credits first, settle against what was actually spent (model tokens, image generation, redraws, export), refund on failure, pause when the balance runs out, resume after top-up. That's not a button handler.

Self-review. If retries happen silently in the backend, the user just stares at a spinner. To make self-review a feature, the AI has to persist intermediate results and surface the states — generating, checking, redrawing — along with scores and attempts. Now the wait reads as "the system is improving the slide," not "it's stuck."

Export. A slide that looks perfect in the browser can come out broken as PPTX — layers, fonts, aspect ratio, cropping all drift. So the requirement can't be "generate a PPTX file." It has to be "the exported PPTX must visually match the web preview."

Once I saw the pattern, the brief I gave the AI stopped being a feature list and started being acceptance criteria:

Do not build only a working demo.
Build this as a production-ready SaaS product.

This product is based on Velobase Harness.
Harness already provides auth, payments, credits, queues, object storage, and deployment.
Implement PPT generation as an independent business module.

Requirements:
1. Support at least 100 users generating presentations concurrently.
2. Split generation into plan, slide, and finalize queues.
3. Generate each slide independently with concurrency, retries, and failure recovery.
4. Connect all model calls, image generation, editing, and export to credit billing.
5. Pause generation when credits are insufficient and resume after top-up.
6. Run AI review and deterministic layout checks after each slide.
7. Persist intermediate states and show generation, self-check, and redraw progress in real time.
8. Upload generated images to object storage instead of relying on temporary provider URLs.
9. Prioritize visual consistency for PPTX export.
10. Tests must cover concurrency, billing, failure recovery, and export fidelity — not just one successful run.

Here's what the project made unambiguous: AI is already good at writing code. It just doesn't know what makes something shippable. It will treat one successful run as completion, a local demo as a system, a page that renders as a correct export. The part only a human can supply isn't the feature description — it's the acceptance criteria, the engineering boundaries, the failure cases, the business rules.

That's the real split. Harness covers the common SaaS foundation so it's already there. AI fills in the business logic fast — once the boundaries are clear. Faster shipping doesn't come from thinking less. It comes from turning your thinking into sharper input.

If you've shipped something AI-built past the demo stage: what was the gap between "it ran" and "I'd let customers near it" that bit you hardest?

The boring 80% nobody warns you about when an AI demo becomes a real product

Velobase — Wed, 17 Jun 2026 04:55:33 +0000

This month the front page filled up with AI agents going off the rails — one reportedly ran its operator's bill into the ground, another tore through a Linux box unsupervised. Funny, until it's your credits and your customers. We learned that lesson the slower, more expensive way.

Our team shipped an AI demo in a weekend. Turning it into something people could actually pay for took the next four months, and almost none of that time went into the AI part.

That gap surprised us more than it should have. The model call was maybe 30 lines. Everything around it — getting paid, knowing who to thank for a signup, stopping one script from burning $400 of credits overnight — was the real product. Below is what we got wrong on the way there, in roughly the order it hurt.

Pitfall 1: "We'll just add Stripe later"

Later is a lie. The moment you charge for AI usage, billing stops being a checkout button and becomes a metering problem.

A flat $20/month subscription is easy. The trouble starts when usage is the cost. A heavy user can run you negative on a plan a light user is wildly overpaying for. So you end up needing both: a subscription and a usage meter that counts tokens (or images, or minutes) and reconciles them against credits the customer actually has left.

What we underestimated was the bookkeeping. Every generation has to decrement a balance, that decrement has to survive a crash mid-request, and the customer needs a dashboard that agrees with what Stripe charged them — to the cent — or you get support tickets you can't answer. We rebuilt this twice. The second time we finally separated "what the model did" (an event) from "what we charged" (a ledger entry), and the bugs stopped.

If you take one thing from this post: model the usage event and the billing entry as two different things from day one. Collapsing them feels simpler and costs you a weekend later.

Pitfall 2: Free credits are a free lunch — for abusers

We gave new signups some free credits so people could try the thing without a card. Reasonable. Within a week someone had scripted a few hundred throwaway accounts and was draining the free tier in a loop.

There's no single fix. What actually worked was a stack of cheap, boring checks layered together:

Rate limits per account and per IP (Redis, sliding window).
A CAPTCHA on signup — we used Turnstile, but anything that adds friction for bots helps.
Blocking disposable email domains at signup.
Small signup signals (is this account an hour old with 200 generations?) feeding a guest quota.
And the unglamorous one: credit clawbacks, so when you do catch fraud after the fact, you can actually take the credits back instead of eating the loss.

None of these is clever. The lesson was that abuse control isn't a feature you build once — it's a posture. You assume the free tier will be attacked and you make abuse slightly more annoying than it's worth.

Pitfall 3: You will not know which channel actually works

We spent money on a few channels and had no idea which one produced paying customers. Client-side analytics told us about pageviews. It told us nothing trustworthy about purchases, because ad blockers and the gap between "clicked an ad on Monday" and "paid on Thursday" quietly destroy attribution.

The thing that fixed it was moving attribution server-side: stamp the acquisition source when the account is created, carry it through, and fire the conversion from the backend when money actually changes hands — including the offline-conversion uploads back to Google Ads and the pixel events platforms expect. Suddenly "this campaign cost $X and produced Y paying users" was a sentence we could finish.

If you're running any paid acquisition for an AI product, do the server-side version early. The client-side numbers feel fine right up until you try to make a budget decision with them.

Pitfall 4: An affiliate program is an accounting system wearing a marketing hat

This one humbled us. "Let people refer others for a cut" sounds like a referral link and a counter. It is not.

The instant real money is owed to real people, you're running double-entry accounting whether you meant to or not. A referred customer asks for a refund — now you have to claw back the commission you already credited the affiliate. Someone wants to cash out (in our case people asked for USDT). Promo codes stack in ways you didn't intend. Get any of this slightly wrong and you're not shipping a bug, you owe someone the wrong amount of money.

We ended up treating the whole thing as a proper ledger — every credit and clawback is a balanced entry — because that's the only way the numbers stay defensible when an affiliate disputes their payout.

Pitfall 5: The "rest of the backend" is a second full-time job

Auth. Background workers for anything slower than a request (we used BullMQ on Redis). Lifecycle email so trials don't silently lapse. An admin panel so you can actually look at a customer when they email you. Then Docker, then Kubernetes, then CI/CD so a deploy isn't a held breath.

Each of these is a known, solved problem. The cost isn't difficulty — it's count. There are a dozen of them, none is the thing you set out to build, and together they're where the months go.

So what did we do about it

We kept ripping these pieces out of one product and into something reusable, and eventually it became its own open-source project: Velobase Harness — MIT licensed, Next.js 15 / React 19 / tRPC / Prisma / Postgres, with the usage billing, server-side attribution, affiliate ledger, anti-abuse stack, workers, and deploy config already wired together. It's the scaffolding we wish we'd had before pitfall 1.

We're not going to pretend it's the only way to do this — plenty of people would (and do) assemble these from separate services, and that's a legitimate choice. We just got tired of rebuilding the same plumbing for every AI idea.

What we're actually curious about, and the reason we wrote this down: for those of you who've taken an AI product past the demo — which of these bit you hardest? And did you build the billing/abuse/attribution layer yourself, reach for something off-the-shelf, or just... not, and hope? We're collecting war stories and genuinely want to hear how other people drew the line.