Cortensor Portal V1 Detailed Spec 08 - Usage / Metering / Billing
Status
Draft
Purpose
This document defines how Portal V1 should think about usage, metering, quota visibility, and simple billing foundations.
It focuses on the product and system rules needed to make Portal V1 understandable, enforceable, and evolvable, without over-designing the first release.
1. Summary
Portal V1 should keep usage and billing semantics intentionally simple.
The main V1 priorities are:
clear allowance visibility
practical gateway enforcement
durable usage writeback
simple future billing compatibility
The exact billing sophistication can come later.
In practice, Portal V1 should first answer four questions well:
how much usage does the user have?
how much has been consumed?
when does it reset?
what happens when the limit is reached?
2. Goals
Portal V1 usage and billing design should aim to:
make limits easy for users to understand
make enforcement easy for the gateway to apply
create a durable record of usage
leave room for future paid plans or credits
keep the first product release narrow and supportable
avoid backing the team into a brittle billing model too early
3. Recommended V1 Usage Model
Portal V1 should start with a simple allowance model such as:
request or task cap
short reset window
weekly allowance
The exact numeric limits can be finalized later.
The important V1 principle is:
Usage should be simple enough to explain, simple enough to enforce, and simple enough to debug.
Suggested V1 user-facing usage view
The web app should show:
current plan
percent used
reset timing
warning state near limit
If useful, it may also show:
current window usage
weekly usage summary
simple text description of what counts as usage
What V1 should avoid
Avoid launching with:
too many usage dimensions
too many charts
highly detailed financial-style reporting
deeply technical metering explanations in the customer UI
4. Metering Ownership
Portal should own usage semantics.
That means Portal should decide:
what counts as usage
when usage is recorded
how usage is attributed
how usage maps to plans or billing state
This should not be left entirely to a third-party key system or gateway vendor.
Why this matters
Even if Portal uses external systems for:
API key verification
rate limiting
request-time enforcement
Portal still needs to define:
whether a request should count toward allowance
how usage maps to a user, org, or key
which model families count differently later
how usage relates to upgrades or billing
This is product logic, so it belongs to the Portal layer.
5. Durable Usage Writes
Portal should maintain durable records for:
usage events
billable events or equivalent
request logs if needed for reconciliation
Some writes may be synchronous, others asynchronous, but the ownership should remain clear.
Durable records should support
dashboard usage visibility
quota tracking
future billing logic
operational debugging
support workflows
reconciliation between request acceptance and backend completion
Design principle
Portal should own the durable usage model even if:
some request-time checks happen elsewhere
some writes are delayed
some analytics are computed later
6. Usage Events
Portal V1 should treat usage events as the basic durable metering unit.
A usage event should be attributable to:
user or organization
API key (if relevant)
model or model family
plan or allowance class
request ID
timestamp
request outcome category
Suggested V1 responsibilities of usage events
Usage events should support:
showing usage in the Portal UI
understanding whether allowance has been consumed
later feeding a billing ledger
basic support/debugging
auditing what happened for a given request
V1 simplicity note
The event model does not need to be overcomplicated in the first version. But it should be shaped so that later additions like:
credits
paid plans
model-weighted usage
account-level aggregation
can be added without rewriting the basic ownership model.
7. Billing in V1
Billing should stay simple.
Reasonable V1 options:
free plan only
free plus simple upgrade placeholder
simple monthly quota plan
prepaid credits later
The important thing is not final billing complexity. The important thing is that the usage model is stable enough to evolve.
Recommended V1 stance
Portal V1 should prioritize:
usage clarity
simple limit semantics
stable metering ownership
future billing compatibility
It does not need to become a complex billing product immediately.
Practical interpretation
The billing surface in V1 can be intentionally lightweight:
show current plan
show whether user is on free / paid / placeholder state
optionally show upgrade direction
defer more advanced billing breakdowns until later
8. Billing Ledger Foundations
Even if billing remains simple in V1, Portal should still maintain the foundations for a durable billing ledger.
Why this matters
Portal will likely need, later:
credits
plan-based allowances
monthly statements or invoices
account-level billing history
usage-to-billing reconciliation
If the usage model is designed cleanly early, this becomes much easier later.
V1 requirement
Portal V1 does not need full invoice UI or advanced accounting logic, but it should keep the data model compatible with future ledger-based billing.
9. UI Requirements
The Portal UI should at minimum show:
plan badge
current allowance status
reset timing
basic upgrade direction if relevant
The UI should not try to be a complex finance console in V1.
Usage page should make these obvious
what plan the user is on
how much has been used
how close they are to their limit
when the allowance resets
what they can do next if they are near or at the limit
UI tone
The UI should be:
calm
clear
readable
low-noise
Not:
overloaded with metrics
full of financial terminology
shaped like an internal billing dashboard
10. Request-Time Enforcement vs Durable Accounting
Portal V1 should clearly separate:
Request-time enforcement
Used for:
key validity
rate-limit checks
quota allowance checks
model entitlement checks
This belongs in the gateway hot path.
Durable accounting
Used for:
usage history
billable usage history
request tracing
future billing support
reconciliation
This belongs in the Portal durable state layer.
Why the separation matters
The gateway must remain fast. The accounting layer must remain durable and trustworthy.
Those are related, but not identical needs.
Portal V1 should avoid a design where every request requires heavy durable DB work before it can proceed.
11. Reconciliation Concerns
Portal should eventually be able to reason about differences between:
request accepted by gateway
request forwarded
inference completed
usage written durably
V1 does not need to solve every reconciliation edge case perfectly, but it should avoid designing itself into a corner.
Example reconciliation scenarios
Possible mismatches include:
request accepted by the gateway but never forwarded
request forwarded but backend timed out
backend completed but usage event failed to write immediately
duplicate retries produce ambiguous accounting unless tracked carefully
V1 requirement
Portal V1 should at least preserve enough structure so the team can answer:
was the request accepted?
was it forwarded?
did it complete?
was usage recorded?
That is enough to support debugging and later reconciliation improvements.
12. Suggested V1 Simplicity Rules
To keep V1 coherent:
use one primary allowance model
keep reset windows obvious
keep usage language simple
avoid too many quota dimensions
avoid tying billing to too many variables immediately
A good V1 usage system should be:
easy to explain
easy to enforce
easy to inspect
easy to extend later
13. Open Questions
Open questions for later refinement:
what should the primary allowance unit be?
which writes are synchronous vs asynchronous?
when should billing become more than plan visibility?
should usage be counted per request, per task, per token, or in a hybrid way?
how much metering detail should be exposed in the Portal UI?
These questions should be answered while keeping V1 intentionally simple.
14. Relationship To Other Specs
This spec connects directly to:
04-free-plan-rate-limits-and-gateway.md05-portal-backend-control-plane.md06-data-model-and-durable-state.md07-router-pools-and-model-product-layer.md01-ui-ux-web-app.md
It also depends on:
API key lifecycle behavior
free-plan and allowance semantics
durable usage event design
product-facing model access rules
15. Working Summary
Portal V1 should think about usage, metering, and billing as a deliberately simple first-layer product system.
The main V1 priorities are:
clear allowance visibility
practical gateway enforcement
durable usage ownership
clean future compatibility for billing evolution
In one sentence:
Portal V1 should make usage easy to understand, easy to enforce, and easy to record durably, while deferring more advanced billing sophistication to later versions.
Last updated