Usage ledger
Follow every operation from reservation through settlement and overage reporting.
The operation backend uses reserve/settle accounting so an upstream failure does not consume a user's balance.
- 1Validate auth, scope and operation
- 2Reserve allowance or credits
- 3Call inVerus
- 4Settle success or reverse failure
- 5Report eligible Stripe overage
- 6Return updated balance
Ledger fields
Recent usage includes operation, channel, subject, credits charged, charge source, status and timestamp. The Console returns up to 50 rows from the authoritative Free month or Stripe subscription cycle and reports the exact successful-operation count for that period separately.
/api/clawdbase/usageCharge sources
Common sources include free, gifted, included, purchased and overage. The server decides the source atomically; clients must not choose it.
Failed operations settle with zero net charge. If Stripe metering fails after an overage operation succeeds, the ledger remains the authoritative usage record and the failure is logged for reconciliation.
How a source is selected
Clawdbase selects the first eligible source for the account. A Free allowance consumes exactly one call, while gifted, included, purchased and overage sources use the operation's credit price. The request cannot choose a cheaper source or opt into overage directly.
| Source | Unit | Typical eligibility |
|---|---|---|
free | One call | Remaining monthly free-call allowance |
gifted | Operation credits from claimed eligible gifts | Recipient has an available gifted balance |
included | Operation credits | Active plan cycle balance |
purchased | Operation credits | Confirmed prepaid pack balance |
overage | Metered operation credits | Active paid subscription and configured meter |
State transitions
pending is inserted with the reservation. success keeps the consumed amount. failed reverses the matching balance counter and writes zero settled credits. A pending row after a process failure is visible for reconciliation rather than silently disappearing.
Idempotent replay
Clawdbase recognizes an already settled logical request and returns its ledger ID without another debit or scoring call. Consumers should associate one application job with one ledger ID even if several HTTP attempts occurred.
Overage reporting
Only a successfully settled overage operation emits a Stripe meter event. The ledger ID is used as both the event identifier and Stripe idempotency identity, and the operation price is the value. The API does not confirm overage delivery until Stripe accepts the event. A retry with the same operation idempotency key safely retries that same meter event; failed operations never emit one.
Support and reconciliation
The Console returns the current balance period and recent rows. When asking for support, provide the ledger ID, operation, approximate UTC time and safe subject reference. Never send an Access Key, provider token or payment credential.
What to expect
- Pending rows have a bounded reconciliation path.
- Failed settlement always reverses the original source counter.
- A Free operation increments free usage by one, not the operation credit price.
- Purchased packs are granted once per confirmed Stripe session.
- Meter events can be correlated to a successful overage ledger ID.