DEV Community: Meterbase

Soft cap or hard cap? Deciding what happens when a customer hits their limit

Meterbase — Sun, 04 Oct 2026 07:22:04 +0000

Sooner or later, a paying customer hits the edge of their plan in the middle of something they care about. What your product does in that moment is a pricing decision, a product decision and an engineering decision at once. Most teams make it by accident, in whichever code path ran out of credits first.

Here are the options, and what each one needs underneath.

Option 1: Hard cap

The customer gets exactly what the plan includes. When it's gone, the next request is refused until the period renews or they buy more.

Good for: prepaid credits, free tiers, and products where each unit is expensive.

Watch out for: refusing work halfway through a multi-step job. If an agent run needs ten steps and the balance covers seven, a hard cap mid-run leaves the customer with a broken result. Gate the whole job up front, with a hold sized to the estimate, rather than step by step.

Option 2: Soft cap with overage

The plan includes an amount. Usage past it keeps working and is billed as overage when the period ends.

Good for: business customers who'd rather pay more than be interrupted, and products where a usage spike means things are going well.

Watch out for: surprise invoices. A soft cap without alerts is how you get an angry email from someone's finance team. You also need an exact, closed number for included usage and overage per customer per period.

Option 3: No cap

Nothing is included or limited. Everything is metered and billed afterwards.

Good for: pay-as-you-go API products sold to developers.

Watch out for: runaway scripts. With no cap, rate limits are the only thing between a bug in a customer's loop and a very large bill. Keep per-customer rate limits even when you don't cap totals.

Option 4: Mix them per meter

Real plans usually combine them: unlimited chat messages, 5,000 image generations a month with overage, and a hard cap on the most expensive thing you sell. A plan is a set of decisions, one per thing you measure.

Whatever you pick, add these two

Thresholds. Tell customers at 80%, 90% and 100%, once each per period. That turns a hard stop into a top-up, and an overage invoice into something they saw coming.

Top-ups. For hard caps, give customers a way to buy more right now. A top-up should have its own expiry, separate from the monthly allowance, so it doesn't vanish at renewal.

How this maps onto Meterbase

In Meterbase, each plan allowance is one of these, set per meter, so one plan can mix them:

a finite amount (hard cap)
a finite amount with allow_overage: true (soft cap)
no_cap (no cap)

Your code doesn't change between them. You still check before the work and track after. Under a soft cap, check keeps allowing past the included amount and tells you so:

{ "allowed": true, "no_cap": false, "available": 0, "allow_overage": true, "rate_limits": [] }

Threshold crossings become webhooks, rate limits apply per customer either way, and when a period closes you read its exact usage and overage to bill from.

If you're making this decision for your own product right now, we're happy to talk it through: meterbase.tech.

Two requests, one last credit: the race condition in usage-based billing

Meterbase — Sun, 04 Oct 2026 07:21:47 +0000

Here's the most common way to gate paid work:

const credits = await getCredits(customerId)   // 10 left
if (credits < cost) throw new Error("Out of credits")

const result = await runJob(input)              // takes 20 seconds

await deductCredits(customerId, result.cost)

It reads fine and works in testing. In production, a customer opens two tabs, or an agent fires five tool calls in parallel, and every request reads the same balance before any of them writes. They all pass. The customer ends the day with a negative balance, and you paid for the compute.

Why a transaction doesn't fix it

Wrapping the read and the deduct in a transaction doesn't help when the job runs in between, because you can't hold a database transaction open for 20 seconds while a GPU works. And if you deduct up front, you still have to handle jobs that cost less than you estimated, jobs that fail, and workers that crash before refunding.

Step 1: make check-and-deduct atomic

The first fix is to let the database do the comparison:

UPDATE balances
SET credits = credits - $2
WHERE customer_id = $1
  AND credits >= $2
RETURNING credits;

If no row comes back, the customer couldn't afford it. Two concurrent requests can't both take the last credits, because the second update sees the first one's write.

That works when you know the cost up front. For AI work you usually don't: a reply's token count, a render's length or a scrape's page count is only known after the job finishes.

Step 2: hold an estimate, settle the actual

The pattern that handles unknown costs is a hold, like a card hold at a hotel:

Before the work, atomically set aside an estimate. The customer's available balance drops by that amount, so a parallel request can't use it.
Run the work.
Commit the real cost. Whatever's left of the hold goes back.
If the work fails, release the hold and record nothing.
If the process dies and nobody commits or releases, the hold expires on its own and the capacity comes back.

That last step is the one teams forget. Without expiry, every crashed worker permanently eats part of a customer's balance.

A minimal holds table looks something like this:

CREATE TABLE holds (
  id          uuid PRIMARY KEY,
  customer_id text NOT NULL,
  quantity    bigint NOT NULL,
  expires_at  timestamptz NOT NULL,
  closed_at   timestamptz
);

"Available" then becomes the allowance, minus usage, plus unspent top-ups, minus open holds that haven't expired. Every reserve has to compute that and insert the hold atomically for that customer, which in practice means a row lock or serializable isolation per customer.

Step 3: decide which work needs a hold

Holds cost a write and make concurrent requests for the same customer wait their turn. Not everything needs one. A useful rule:

Cheap work you can afford to overshoot slightly, like a chat reply against a million-token allowance: check, run, record. Two replies racing past the check overshoot by a few thousand tokens.
Expensive work you can't afford to do twice, like image batches, video renders or long agent runs: hold, run, then commit or release.

What this looks like in Meterbase

We built Meterbase so this is a couple of calls. For expensive work:

const hold = await meterbase.reserve({
  customer_id: "acct_1",
  meter_id: "image_generations",
  quantity: 4,
  expires_in_seconds: 120, // longer than the work takes
})
if (!hold.allowed) throw new Error(`Refused: ${hold.reason}`)

const images = await generateImages(prompt, 4).catch(async (error) => {
  await hold.release() // the work failed: record nothing
  throw error
})

await hold.commit(images.length) // the rest of the hold comes back

Two concurrent reserves can't be granted the same capacity, and a hold nobody closes expires after expires_in_seconds (1 to 900, default 60). For cheap work you'd use check and track instead, which hold nothing.

If you're building this yourself, the SQL above is a solid start. If you'd rather not own it, take a look at meterbase.tech. We're happy to help you set it up.

The parts of a credit system nobody puts in the estimate

Meterbase — Sun, 04 Oct 2026 07:21:17 +0000

If your product sells credits, tokens, minutes or API calls, someone on your team has probably said "we'll just add a credits column to the users table." It's a reasonable first move. It's also where most teams start building a billing system they never planned to own.

Here's what that column turns into once real customers arrive.

1. The balance isn't one number

A customer on a monthly plan has an allowance that resets. Then they buy a top-up pack, which shouldn't reset. Then you give them a signup bonus that expires in 30 days. Now "how many credits do they have?" is a sum over several buckets, each with its own rules, and you have to decide which bucket to spend first. Usually it's the one that expires soonest.

2. "Monthly" means each customer's month

Allowances renew on the customer's billing date, not on the 1st. A customer who signed up on the 17th renews on the 17th. A customer who upgraded on the 9th might renew on the 9th from now on, or keep the 17th, depending on how you prorate. Your renewal job now needs to know every customer's anchor date.

3. Plan changes mid-period

Upgrade today, and what happens to the allowance? Do they get the full new amount now, a prorated share, or the new amount at the next renewal? Downgrades are worse: what if they've already used more than the smaller plan includes? Whatever you choose, you need a history of which plan applied when, or you can't explain an invoice later.

4. Two requests, one last credit

Your app checks the balance, runs the job, then deducts. With parallel requests, two jobs can both see "10 credits left", both run, and both deduct. The customer ends up at −10. For cheap work that's fine. For a video render or a batch of image generations, it's real money. Fixing it means holding capacity before the work starts and settling after.

5. Failed jobs

If you hold or deduct credits before a job and the job fails, the customer should get them back. If your worker crashes mid-job, nobody calls the refund. So holds need an expiry, and something has to clean them up.

6. Bursts

A monthly allowance doesn't stop one customer's runaway script from spending the whole month in ten minutes. You need rate limits per customer as well as totals, often in more than one window, such as per minute and per hour.

7. Telling customers before they run out

Customers would rather top up at 80% than find out they're at 100% when a job fails. That means tracking thresholds per customer per period and notifying once, not on every request after the line is crossed.

8. Usage for billing

At the end of a period, finance wants an exact number: how much this customer used, how much was included, and how much was overage. That number has to stay put once the period closes.

What it adds up to

None of these are hard on their own. Together they're a small, stateful, concurrency-sensitive system that sits in front of your most expensive operations, and it changes every time your pricing changes. That's the part that rarely makes it into the original estimate.

The short version

This is the problem we're building Meterbase for. You set up meters, plans and allowances once, and your code makes one call before the work and one after:

import { Meterbase } from "mbase-sdk"

const meterbase = new Meterbase({ apiKey: process.env.METERBASE_API_KEY! })

const check = await meterbase.check({
  customer_id: "acct_1",
  meter_id: "ai_tokens",
  quantity: 2_000, // an estimate
})
if (!check.allowed) throw new Error(`Refused: ${check.reason}`)

const reply = await generateReply(prompt)

await meterbase.track({
  customer_id: "acct_1",
  meter_id: "ai_tokens",
  quantity: reply.usage.total_tokens,
})

Allowances, top-ups, plan changes, holds, rate limits and threshold webhooks sit behind those two calls. Meterbase isn't a billing system: Stripe or Paddle still take the money, and you read each customer's usage for a period to bill from.

If you're building this right now, or you already built it and are tired of maintaining it, we'd love to hear how you handled it: meterbase.tech.