Create Metered Session

Create a new metered usage session to start tracking consumption for a customer. Sessions track usage in real-time and automatically deduct costs from the customer's balance.

Endpoint

Authorization: Bearer <ORVION_API_KEY> or X-API-Key: <ORVION_API_KEY>

Content-Type: application/json

Request Body

Response

Example: cURL

curl -X POST "https://api.orvion.sh/v1/metered-billing/sessions" \
-H "Authorization: Bearer $ORVION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "customer_ref": "user_123",
  "pricing": {
    "currency": "USD",
    "unit": "second",
    "unit_price": "0.0025"
  },
  "cap": {
    "amount": "50.00"
  },
  "resource_ref": "vps:server_456",
  "metadata": {
    "vps_id": "server_456",
    "region": "us-east-1"
  }
}'

Example: Python SDK

from orvion import OrvionClient
from orvion.usage import UsagePricing, UsageCap

# Initialize client
orvion = OrvionClient(api_key="your_api_key")

# Create session
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"),
  resource_ref="vps:server_456",
  metadata={
      "vps_id": "server_456",
      "region": "us-east-1"
  }
)

print(f"Session created: {session.id}")
print(f"Status: {session.status}")
print(f"Pricing: ${session.pricing.unit_price}/second")

Example: Node.js SDK

import { OrvionClient } from '@orvion/sdk';

// Initialize client
const orvion = new OrvionClient({ apiKey: 'your_api_key' });

// Create session
const session = await orvion.usage.createSession({
customerId: 'user_123',
pricing: {
  currency: 'USD',
  unit: 'second',
  unitPrice: '0.0025'
},
cap: {
  amount: '50.00'
},
resourceRef: 'vps:server_456',
metadata: {
  vps_id: 'server_456',
  region: 'us-east-1'
}
});

console.log(`Session created: ${session.id}`);
console.log(`Status: ${session.status}`);
console.log(`Pricing: $${session.pricing.unitPrice}/second`);

Response Example

{
  "id": "sess_abc123",
  "status": "active",
  "customer_ref": "user_123",
  "resource_ref": "vps:server_456",
  "pricing": {
    "currency": "USD",
    "unit": "second",
    "unit_price": "0.0025"
  },
  "cap": {
    "amount": "50.00"
  },
  "usage": {
    "total_seconds": 0,
    "total_amount": "0.00"
  },
  "last_tick_at": null,
  "settled_amount": null,
  "invoice_id": null,
  "metadata": {
    "vps_id": "server_456",
    "region": "us-east-1"
  },
  "started_at": "2025-01-15T10:00:00Z",
  "stopped_at": null,
  "settled_at": null,
  "created_at": "2025-01-15T10:00:00Z"
}

Important Notes

Balance Requirement

Before creating a session, ensure the customer has sufficient balance. You can:

• Top up the balance via POST /v1/metered-billing/balances/top-up
• Check balance via GET /v1/metered-billing/balances

If a session is created without sufficient balance, usage ticks will fail with insufficient_balance: true.

Idempotency

Use idempotency_key to prevent duplicate sessions if your request is retried. The same key will return the same session.

Pricing

• Currency: Must be a valid ISO currency code (e.g., USD, EUR)
• Unit: Currently only "second" is supported
• Unit Price: Must be a decimal string (e.g., "0.0025" for $0.0025/second)

Usage Caps

Set a cap.amount to limit the maximum charge for a session. Once the cap is reached:

• The session status changes to stopped
• No further ticks will be accepted
• You can still settle the session

Error Responses

400 Bad Request

{
  "detail": "Invalid pricing configuration"
}

401 Unauthorized

{
  "detail": "Invalid API key"
}

402 Payment Required

{
  "detail": "Insufficient balance"
}

Next Steps

• Report Usage Ticks - Start tracking consumption
• Manage Balances - Top up customer balances
• Settle Sessions - Generate invoices from usage