DEV Community: Ritusmoi Kaushik

Metering a Paid API Without Overselling: the Credit Ledger Behind a Solo SaaS

Ritusmoi Kaushik — Tue, 16 Jun 2026 07:10:36 +0000

I charge per invoice extracted. One upload of a five-invoice PDF should cost five credits, a failed extraction should cost nothing, and a user with one credit left must never get two. That last rule is where it got interesting.

This is the billing design behind GSTExtract — a tool that reads Indian GST invoice PDFs into Excel — and the concurrency bug a second-pass audit found in it. Writing it up because "meter a paid API correctly" is one of those problems that looks trivial until you hold it up to the light.

The shape of the problem

Each extraction calls a vision model, which costs me real money. So the user spends a credit per invoice. The catch: I don't know how many invoices are in a PDF until after the model reads it. A single page can hold three invoices; a "10-page" file might be one. I can't charge up front because I don't know the count, and I can't charge after without a window where a user with a zero balance has already burned my API budget.

The answer most billing systems land on is reserve → settle → refund:

Reserve one credit before doing the expensive work. This is the gate — if it fails, the user is out of credits and nothing runs.
Settle after success: charge the actual count minus the one already reserved.
Refund the reserve if the extraction failed, so failures are never billed.

Money and credits are integers. Every change is also written to an append-only ledger with an idempotency key, so a retry can never double-charge. Balance is derived: the sum of remaining credits across non-expired "lots" (a lot is one grant — a signup bonus, a purchase). Consumption is FIFO by soonest expiry, so credits get used before they lapse.

That part worked. The bug was in the word "atomic."

The bug: two uploads, one credit

The original charge function did the obvious thing:

# read the balance
bal = current_balance(db, user_id)
if bal < n:
    return False, 0
# ... then walk the lots and decrement in Python
for lot in lots:
    take = min(lot.remaining, remaining)
    lot.remaining -= take          # <-- writes an ABSOLUTE value

Read the balance, decide, write the new value. Single-threaded, this is fine. Now picture a user with exactly one credit firing two uploads at the same moment (a double-click, or two tabs):

Request A reads remaining = 1. Decides it's allowed.
Request B reads remaining = 1. Also decides it's allowed.
A writes remaining = 0, inserts a -1 ledger row.
B writes remaining = 0, inserts a -1 ledger row.

Both succeed. The user spent one credit and got two extractions. The idempotency key didn't save me — the two requests had different keys, because they're two genuinely different uploads. The read-then-write-absolute is the classic lost-update race.

The fix: let the database do the deciding

The cure is to stop computing the new value in Python and let the write itself be the gate — a conditional UPDATE that only fires if there's still enough left, checked under the row lock:

res = db.execute(
    update(CreditLot)
    .where(CreditLot.id == lot_id, CreditLot.remaining >= take)
    .values(remaining=CreditLot.remaining - take)
)
if res.rowcount == 1:
    taken += take      # we actually got it
# rowcount 0 → someone else took it first; move on or roll back

remaining = remaining - take instead of remaining = <number I computed>. The WHERE remaining >= take re-checks the balance at write time, and SQLite serializes writers, so the second request blocks, re-evaluates against the now-committed remaining = 0, gets rowcount = 0, and is correctly told it can't reserve. Exactly one upload wins. Balance can never go negative.

I proved it with a test that fires N concurrent reservers at a one-credit account on a real file-backed SQLite DB (WAL mode, busy timeout — same as production, because an in-memory shared-connection DB won't reproduce writer contention). Exactly one succeeds, every time.

The second bug: a retry that costs me money

There was a sneakier one, found in the same audit. The workspace retries an upload once on a dropped connection, reusing the same request_id so it doesn't double-charge. And it didn't double-charge — the ledger keys saw to that. But the idempotency cache was written after the model call, not before. So a retry that arrived while the first call was still in flight sailed past the cache check and fired a second vision-model call. No double charge, but I paid for two API calls and logged a duplicate usage event.

Fix: mark the request in-flight before the expensive call, while everything above it is still synchronous (so two requests can't both pass the check), and have a retry return 409 instead of re-running:

cached = _REQUESTS.get(rid)
if cached:
    if cached.get("in_flight"):
        return JSONResponse({"code": "in_progress"}, status_code=409)
    return JSONResponse(cached["response"])
# ... reserve the credit ...
_REQUESTS[rid] = {"in_flight": True}   # before the model call

The lesson that keeps repeating: idempotency has to cover the side effect, not just the database row. The charge was idempotent. The expensive API call wasn't.

Why an append-only ledger earns its keep

The thing that made all of this debuggable: nothing is ever updated or deleted in the transaction log. Every grant, charge, and refund is an immutable row with a signed delta. That gives you a reconciliation invariant you can assert on a schedule:

the sum of all ledger deltas for a user == the sum of remaining across all their lots

If those two numbers ever disagree, a write went wrong, and an alert fires. (I also learned to not fold a cache-freshness check into that alert — a balance cache that goes stale when a credit quietly expires is not corruption, and it had me chasing phantom "drift" emails for a day.)

Takeaways

Don't read-modify-write a balance. Make the write conditional (WHERE remaining >= n) and trust rowcount.
Reserve → settle → refund cleanly separates "can they pay" from "what did it actually cost."
Idempotency must guard the expensive side effect, not only the ledger insert.
An append-only ledger gives you a cheap, always-true invariant to reconcile against.
Write the concurrency test against a real on-disk DB, or it won't reproduce the race you're trying to kill.

The hosted tool has a free daily tier and twenty free credits on signup, with prepaid packs for heavier use — so this ledger runs on every extraction, and I'd rather it be boringly correct. If you want to see it in action, it's at gstextract.com; the extraction engine is open source, though the billing layer above is part of the hosted product.

If you've metered a paid API differently — especially how you handle the count-unknown-until-after problem — I'd genuinely like to hear it.

I Open-Sourced the Core of My GST Tool. Here's What I Kept Private.

Ritusmoi Kaushik — Tue, 21 Apr 2026 07:12:18 +0000

A few days ago I published the core extraction engine of GSTExtract on GitHub, MIT licensed. The repository is here. It's not the full product. It's a seven-week-old snapshot, and that gap is the whole strategy.

This post is about the decisions I made picking what to open-source and what to keep private. The deciding took longer than writing the code did, which surprised me. Writing it up in case anyone else is staring at the same question on their own project.

Context, Briefly

GSTExtract reads Indian GST invoice PDFs and pulls out the fields (GSTIN, invoice number, amounts, taxes) into Excel. Small businesses and accountants use it at month-end to avoid hand-typing supplier bills into Tally. The stack is Python — pdfplumber for digital PDFs, Tesseract OCR as fallback, regex + keyword-anchored extraction, openpyxl for Excel output. FastAPI wraps it for the hosted version. The hosted tool is free during early access, with a paid tier planned for high-volume users later.

So the question was: how do I open-source without giving away the commercial edge?

What Went Public

The deterministic regex plus keyword extraction pipeline. GSTIN parsing with the Luhn mod-36 checksum. Zone segmentation that splits an invoice into header and footer and routes fields by zone. Tax-line detection with keyword anchoring. Excel export. The test suite. Basically, the commoditised parsing work that anyone doing invoice extraction would eventually re-implement themselves if they cared enough.

If someone wants to understand how you pull GSTINs and invoice totals out of a messy PDF, the code is all there. Forkable, patchable, usable in their own pipelines.

What Stayed Private

The seven weeks of engine refinements since the cut point:

Multi-vendor accuracy tuning for Amazon, Flipkart, Swiggy, Zomato, BookMyShow, RedBus, and Myntra invoices (each one has a slightly different layout that breaks generic extraction)
Table-based tax extraction for borderless PDFs
Multi-invoice detection for combined bundles
Per-field confidence scoring refinements
Proprietorship invoice edge cases (handwritten-style templates that use bare "FROM" labels instead of "BILL FROM", single-digit invoice serials, and so on)

Plus the entire webapp: FastAPI layer, rate limiting, CSRF, file validation, the invoice validation gate that rejects credit notes and proforma bills, the batch upload flow, the learning-data logging. All of that stays closed.

Why the Time-Lag

This is the part I thought about most. Just publishing the latest engine would let anyone stand up a competing extraction site with the same accuracy I have. Publishing a snapshot from seven weeks ago means competitors get a working baseline, but not the current edge. The engineering work I do this month becomes public (maybe) in a few months, not immediately.

Redis, MongoDB, and Elastic have all done versions of this. The open-core pattern: community gets a real, working version of the core. Commercial version stays ahead by some time delta. Nobody feels cheated, but the pricing power stays intact.

For me, the specific cut was commit 0aa5f07 from 2 March 2026, labeled "Phase 12 production hardening" in the private repo. Engine is solid from there. Everything after is refinement.

What I Expect to Get From This

Honestly, the single biggest thing is the backlink. GitHub has domain authority 96. Having a public repo that links to gstextract.com from the README gives my young domain an authority signal it couldn't easily get any other way. On a site that's only a couple of months old and trying to rank for competitive GST queries, that one dofollow link is legitimately meaningful.

After that, in descending likelihood:

Credibility signal to technical readers who want to see how the extraction works. Some fraction of people evaluating a hosted tool will check if the code is worth trusting.
Issues and pull requests from people hitting edge cases I haven't seen. GST invoice formats are wilder than you'd think. Someone will inevitably send me a PDF from a vendor I've never heard of that breaks something.
Forks from people who need self-hosted extraction for their own use cases. Rare, but they become potential collaborators.

What I'm not expecting: hundreds of stars, viral adoption, a community forming around the repo. For a narrow Indian-GST tool, the realistic audience is small. A handful of serious users finding it and either using it or contributing is the bar, not hockey-stick open-source growth.

Honest Tradeoffs

What this might cost me:

Competitors can clone and study the extraction logic. They would eventually anyway, but I've shortened the path.
Time maintaining the public version even if nobody uses it. If I ignore it for months, it rots and becomes a bad signal.
Some fraction of potential paying customers might think "well, the core is free, I'll just self-host" and walk away. I don't think this is many people, but it's nonzero.

What I'm betting:

The moat is distribution plus the continuous-improvement time-lag, not the code itself.
Most competitors don't actually want to self-host and maintain a parser, deal with Tesseract and Poppler, manage their own uptime. Running the hosted tool is a service, not just code.
People who'll pay for the hosted version are paying for the current-version edge, the no-setup convenience, and whatever the product becomes post-launch. The snapshot on GitHub is closer to educational than competitive.

We'll see if that's right. If self-hosting forks start cutting into hosted usage in a measurable way, I'll revisit the cut-point. For now, the calculus feels fine.