Metered Billing

Metered billing lets you track usage in real-time and charge customers based on consumption. Perfect for VPS hosting, compute resources, API calls, video streaming, or any time-based service.

How it works:

• Create a session for a customer with pricing (e.g., $0.0025/second)
• Report usage ticks as the customer consumes resources
• Track balance and automatically deduct costs
• Settle sessions to generate invoices when usage ends

Core Concepts

Usage Session

A metered session tracks consumption for a specific customer and resource. Each session has:

• Pricing: Currency and unit price (e.g., $0.0025 per second)
• Cap: Optional maximum amount to charge
• Status: active, stopped, settled
• Usage: Total seconds consumed and amount charged

Balance

A customer's prepaid balance for a specific currency. Balances are automatically debited as usage ticks are reported. You can top up balances via API or external payment.

Usage Ticks

Periodic reports of consumption (e.g., every 10 seconds). Each tick records:

• Seconds: Duration since last tick
• Tick ID: Unique identifier for idempotency

Settlement

When a session stops, you can settle it to:

• Generate an invoice for the final usage amount
• Create a ledger entry for accounting
• Mark the session as settled

Quick Start

Typical Workflow

With Payment Checkout (Recommended)

1. Top Up with Payment    2. Customer Pays         3. Balance Topped Up
   ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
   │             │          │             │          │             │
   │ POST /v1/   │          │ Redirect to │          │ Auto top-up │
   │ metered-    │    ──▶   │ checkout    │    ──▶   │ on payment  │
   │ billing/    │          │             │          │ success     │
   │ balances/   │          │ pay.orvion. │          │             │
   │ top-up-with-│          │ sh/checkout │          │ Balance:    │
   │ payment     │          │             │          │ $100.00     │
   │             │          │             │          │             │
   └─────────────┘          └─────────────┘          └─────────────┘

4. Create Session         5. Report Usage           6. Settle Session
   ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
   │             │          │             │          │             │
   │ POST /v1/   │          │ POST /v1/   │          │ POST /v1/   │
   │ metered-    │          │ metered-    │          │ metered-    │
   │ billing/    │          │ billing/    │          │ billing/    │
   │ sessions    │          │ sessions/   │          │ sessions/   │
   │             │          │ {id}/tick   │          │ {id}/settle │
   │             │          │             │          │             │
   └─────────────┘          └─────────────┘          └─────────────┘
         │                         │                         │
         │                         │                         │
         ▼                         ▼                         ▼
   Session: active          Tick: 10s = $0.025      Invoice created
                           Balance: $99.975         Balance: $97.50

Manual Top-Up (Alternative)

1. Top Up Balance         2. Create Session         3. Report Usage
   ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
   │             │          │             │          │             │
   │ POST /v1/   │          │ POST /v1/   │          │ POST /v1/   │
   │ metered-    │          │ metered-    │          │ metered-    │
   │ billing/    │          │ billing/    │          │ billing/    │
   │ balances/   │          │ sessions    │          │ sessions/   │
   │ top-up      │          │             │          │ {id}/tick   │
   │             │          │             │          │             │
   └─────────────┘          └─────────────┘          └─────────────┘
         │                         │                         │
         │                         │                         │
         ▼                         ▼                         ▼
   Balance: $10.00          Session: active          Tick: 10s = $0.025
                                                      Balance: $9.975

4. Stop Session           5. Settle Session
   ┌─────────────┐          ┌─────────────┐
   │             │          │             │
   │ POST /v1/   │          │ POST /v1/   │
   │ metered-    │          │ metered-    │
   │ billing/    │          │ billing/    │
   │ sessions/   │          │ sessions/   │
   │ {id}/stop   │          │ {id}/settle │
   │             │          │             │
   └─────────────┘          └─────────────┘
         │                         │
         │                         │
         ▼                         ▼
   Status: stopped          Invoice created
   Total: $2.50            Balance: $7.50

Use Cases

VPS Hosting

Track server uptime and charge per second:

# Create session when VPS starts
session = await orvion.usage.create_session(
    customer_id="user_123",
    pricing=UsagePricing(currency="USD", unit="second", unit_price="0.0025"),
    cap=UsageCap(amount="50.00"),  # Max $50/month
    resource_ref="vps:server_456"
)

# Report usage every 10 seconds
while vps_running:
    await session.tick(seconds=10)
    await asyncio.sleep(10)

API Rate Limiting

Charge per API call with metered billing:

// Create session for API access
const session = await orvion.usage.createSession({
  customerId: "api_user_789",
  pricing: { currency: "USD", unit: "second", unitPrice: "0.0001" },
  resourceRef: "api:endpoint_xyz"
});

// Report usage on each API call
await session.tick({ seconds: 1, tickId: `api_call_${Date.now()}` });

Video Streaming

Track streaming time and charge accordingly:

# Start session when video begins
session = await orvion.usage.create_session(
    customer_id="viewer_456",
    pricing=UsagePricing(currency="USD", unit="second", unit_price="0.001"),
    resource_ref="video:premium_content_123"
)

# Report every 30 seconds
while video_playing:
    await session.tick(seconds=30)
    await asyncio.sleep(30)

Key Features

• Real-time tracking: Report usage as it happens
• Automatic billing: Balance deducted automatically on each tick
• Usage caps: Set maximum charges per session
• Idempotent ticks: Safe to retry with tick IDs
• Invoice generation: Automatic invoice creation on settlement
• Balance management: Top up balances via API or external payments
• Multi-currency: Support for different currencies per customer

API Endpoints

All metered billing endpoints are under /v1/metered-billing:

• POST /sessions - Create a new usage session
• GET /sessions/{id} - Get session details
• GET /sessions - List sessions
• POST /sessions/{id}/tick - Report usage tick
• POST /sessions/{id}/stop - Stop a session
• POST /sessions/{id}/settle - Settle a session
• POST /balances/top-up - Add funds to balance
• GET /balances - List balances
• GET /balances/{id}/ledger - View balance ledger

See the API Reference for complete details.

SDK Support

Both Python and Node.js SDKs provide high-level abstractions:

• Python: orvion.usage.create_session(), session.tick(), session.stop()
• Node.js: orvion.usage.createSession(), session.tick(), session.stop()

See SDK Examples for complete code samples.

Next Steps

• Create Your First Session
• Report Usage Ticks
• Manage Customer Balances
• Settle Sessions & Generate Invoices