Billing & Metering
Qarion includes built-in billing infrastructure for multi-tenant deployments. It tracks API usage per tenant, aggregates consumption into billing periods, and generates invoices automatically — all manageable from the admin panel.
Overview
The billing system is designed for platform operators running Qarion as a multi-instance deployment. Each tenant instance has its own usage tracking, billing cycle, and invoice history.
Key Concepts
Usage Metering
Every API request is counted by the BillingUsageMiddleware. The middleware records:
- Instance ID — Which tenant made the request
- Meter key — The type of usage (e.g.,
api_calls,storage_bytes) - Timestamp — When the request occurred
Raw events are rolled up hourly into usage summaries by the run_billing_aggregation background task.
Pricing Plans
Pricing plans define how usage translates into charges. Plans support two component types:
| Component Type | Description |
|---|---|
| Flat-rate | Fixed fee per billing period (e.g., $99/month for Standard tier) |
| Metered | Per-unit charges with optional tiered buckets (e.g., first 10,000 API calls included, $0.001 per additional call) |
Plans can include multiple components and support configurable allowances.
Billing Cycles
The run_billing_cycle background task runs daily and:
- Checks for billing periods that need closing
- Calculates total usage and charges
- Generates draft invoices with itemized line items
- Applies any credit balances
Invoices
Invoices follow a lifecycle:
| Status | Description |
|---|---|
| Draft | Generated automatically; editable |
| Finalized | Locked for review; line items frozen |
| Sent | Delivered to the tenant |
| Paid | Payment confirmed |
| Overdue | Past due date without payment |
| Void | Cancelled |
Invoices can be downloaded as formatted HTML documents for record-keeping.
Managing Billing (Admin Panel)
Usage Meters
Navigate to Administration → Billing → Meters to configure what gets tracked:
- Key — Unique identifier (e.g.,
api_calls) - Label — Human-readable name
- Unit — Display unit (e.g., "calls", "GB")
- Overage rate — Cost per unit beyond included allowance
- Currency — USD, EUR, or other ISO currency codes
- Cadence — Rate applies per month or per year
Pricing Plans
Under Administration → Billing → Plans, create plans with:
- Base price — Fixed monthly/annual fee
- Components — Add metered or flat-rate line items
- Usage tiers — Define tiered pricing buckets for metered components (e.g., 0–10K calls at $0, 10K–100K at $0.001)
Invoices
Review and manage invoices under Administration → Billing → Invoices:
- Filter by instance or status
- View itemized line items per invoice
- Transition invoice states (finalize, send, mark paid)
- Download invoice as HTML
Credits
Apply credit adjustments to tenant accounts for promotional offers, billing corrections, or prepaid balances. Credits are automatically applied during invoice generation.
Background Tasks
| Task | Schedule | Description |
|---|---|---|
run_billing_aggregation | Hourly | Rolls up raw usage events into daily summaries |
run_billing_cycle | Daily | Closes billing periods and generates invoices |
Related
- Multi-Instance Architecture — How tenant instances are managed
- Tier Management — Feature gating by subscription tier