A self-serve customer signs up, gets free credits, and starts running your product at 2am.
Nobody on your team has spoken to them.
The only thing between that customer and your compute bill is the balance your product checks.
Most billing systems can't give your product that answer.
They apply credits when the invoice is priced, at the end of the period, so a customer with 1,000 credits can use 5,000 before anything notices.
Engineering ends up building a balance service next to billing: a counter, a way to hold credit while a job runs, and a nightly job to reconcile the two. Finance ends up with two balances and has to decide which one is right.
Today we're launching real-time credits. Your product asks Alguna whether a customer can afford a piece of work before it runs. The answer comes from the same balance finance sees on the invoice.
Let's see how it works.
How real-time credits work in Alguna
Real-time credits sit around the work your product is about to do, such as a model call or an agent run.
- Check. Before the work starts, your product tells Alguna what it's about to do. Alguna prices it in credits and says whether the customer's balance covers it.
- Hold. Alguna sets that credit aside while the work runs, so two jobs running at once can't spend the same balance.
- Settle. When the work finishes, your product reports what actually happened. Alguna charges the real amount and returns the rest of the hold.
So what does this mean in practice exactly? Say a customer has 1,000 credits, and an AI summary costs 50. An agent run that may write up to two summaries holds 100 credits and leaves 900 available.
It writes one, so Alguna charges 50, releases the other 50, and the balance reads 950.
You decide what happens when the credits run out
For each kind of usage, you choose what happens when a customer's credits run out:
- Block usage. The work is refused before it costs you anything. Your product can show a top-up or upgrade prompt at the moment the customer needs one.
- Allow and bill overage. Usage keeps flowing, and the part credits didn't cover is billed on the invoice.
You set this per billable metric, which is the unit of usage Alguna measures, such as tokens or API calls. One product can do both: block image generation at zero, for example, and let API calls run into overage.
This is a pricing decision as much as a technical one. So it's a setting in Alguna that finance can change and engineering can read, not a rule buried in your code.
Built for self-serve
In a product-led motion, nobody approves a customer's usage. Real-time credits cover the whole path from sign-up to paid plan without anyone stepping in.
- Sign-up. The customer starts on a free plan with included credits, so every run is checked against a real balance from the first request.
- Usage. Each run is checked, held and settled as it happens. Your product shows the live balance from the same response.
- Empty balance. The next run is refused before it costs you anything. Alguna sends an
account.credits.balance_depletedwebhook, and your product sends the customer to hosted checkout to upgrade. - Paid plan. Checkout starts the subscription, and the plan's included credits are granted every period. The same check keeps running with no change to your code.
No one sets a customer's limit by hand, and nobody chases a self-serve customer for usage they ran up after their credits ran out.
For engineering: No ledger to build
Here's what an in-house credit system has to do, and who does it with real-time credits:
| What a credit ledger needs | With real-time credits |
|---|---|
| A balance every request can read before it runs | POST /credits/check returns it |
| Holds, so concurrent requests can't spend the same credit | reserve opens one; track settles it |
| Pricing usage in credits | Alguna prices the events from the rate on the metric |
| Releasing credit when a job fails or never runs | Close with no events, or let the hold expire |
| Safe retries without charging twice | Each event's unique_id, plus Idempotency-Key on holds |
| Resetting allowances every period | The plan grants a new allowance on schedule |
| Matching usage to the invoice | One ledger; the invoice reads it |
| One database write per request at high volume | The gate settles to the ledger in blocks |
What's left for you is two calls.
You don't build a counter, a reservation system, or a reconciliation job. You make two calls.
POST /credits/check with reserve prices the work and opens the hold:
curl -X POST <https://api.alguna.io/credits/check> \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: run_88f_reserve" \
-d '{
"account": "cust_abc123",
"reserve": {},
"events": [
{
"event_name": "agent_step",
"unique_id": "run_88f_step1",
"properties": { "tokens": 1200 }
}
]
}'
POST /credits/track with the reservation_id and the events that actually happened settles it.
- You never send a credit amount. You describe the work as events, and Alguna prices it from the rate set on the metric. A rate change doesn't touch your code.
- Zero isn't an error. The check returns
200withallowed: falseand anat_zero_actionofstoporoverflow. Your code branches on a field, not an exception. - Every response carries the balance. Show it in your product without a second call. Leave out
reserveand the check is a free quote: nothing is held and no credit moves. - Holds clean up after themselves. A hold lasts 15 minutes by default and up to 4 hours. Close it with no events to release it, or let it expire.
- Long and short work both fit. For a long job, hold a ceiling and report progress with
close: false. For small, fast work, skip the hold and charge directly with a singletrackcall. - Retries are safe. Each event carries a
unique_id, and a reserving check takes anIdempotency-Key. You can read a hold back to see what already landed.
For finance: Nothing to reconcile by hand
A balance service built next to billing answers the product's question and leaves you with a second set of numbers to tie out at month end.
Real-time credits use the ledger your invoices already draw from.
- One ledger. Every movement records what caused it: a grant, an invoice, a direct real-time charge, or a settled hold. You and engineering read the same entries.
- No double billing. Usage that credits paid for in real time comes off the invoice line before it's priced. Your customer is invoiced only for what credits didn't cover.
- Spend stops at the balance when you want it to. With usage blocked at zero, a self-serve customer you've never spoken to can't run up cost past their credits. With overage allowed, the uncovered part goes on the invoice and is charged to the card they saved at checkout.
- You choose which credits pay. Each grant of unit credits has a gate funding setting: off, all real-time usage, or only the metrics you pick. It's off by default, so credit a customer bought for something else never starts paying for usage by surprise.
- Closed periods stay closed. Once an invoice closes, its credit consumption is frozen. A hold that settles afterwards is carried into the open period.
This means no nightly reconciliation job, no second balance to tie out, and no month-end argument about which number is right.
Get started
- Finance: add a consumption rule. In Settings → Workflows → Billing → Credits, pick a billable metric, set how many credits one unit costs, and choose what happens when credits run out.
- Finance: put credits on your self-serve plans. Add unit credits to your free plan and to the plans your checkout sells, and turn on gate funding so they pay for real-time usage.
- Engineering: call the API.
POST /credits/checkbefore the work,POST /credits/trackafter it, and send the customer to checkout when a check comes backallowed: false.
The credit consumption guide has the full request and response reference.