Billed Usage API Reference

Manage billed usage records, consumption tracking, and billing data in the usage management system.

Base Path: /api/billed-usage

Overview

The Billed Usage API provides endpoints for managing billed usage records including creation, retrieval, and bulk operations. Tracks consumption data that has been billed to customers.

Key Operations

API Endpoints

POST /api/billed-usage

Create Billed Usage Record

Creates a new billed usage record for a subscription.

Authentication

Bearer Token or Service Token

Request Body

{
  "subscriptionId": "sub_123",
  "customerId": "cust_456",
  "usageType": "cpu_hours",
  "quantity": 100,
  "unitPrice": 0.50,
  "amount": 50.00,
  "currency": "USD",
  "billingPeriod": "2026-06-01",
  "usageDate": "2026-06-02T10:30:00Z"
}

Response

{
  "id": "usage_789",
  "subscriptionId": "sub_123",
  "usageType": "cpu_hours",
  "quantity": 100,
  "amount": 50.00,
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/billed-usage/{id}

Get Billed Usage Record by ID

Gets billed usage record details by ID.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
id string

Response

{
  "id": "usage_789",
  "subscriptionId": "sub_123",
  "customerId": "cust_456",
  "usageType": "cpu_hours",
  "quantity": 100,
  "unitPrice": 0.50,
  "amount": 50.00,
  "currency": "USD",
  "billingPeriod": "2026-06-01",
  "usageDate": "2026-06-02T10:30:00Z",
  "createdAt": "2026-06-02T10:30:00Z"
}
POST /api/billed-usage/bulk

Bulk Insert Usage Records

Creates multiple billed usage records in a single request.

Authentication

Bearer Token or Service Token

Request Body

{
  "records": [
    {
      "subscriptionId": "sub_123",
      "customerId": "cust_456",
      "usageType": "cpu_hours",
      "quantity": 100,
      "unitPrice": 0.50,
      "amount": 50.00,
      "currency": "USD",
      "billingPeriod": "2026-06-01"
    },
    {
      "subscriptionId": "sub_124",
      "customerId": "cust_456",
      "usageType": "memory_gb",
      "quantity": 512,
      "unitPrice": 0.10,
      "amount": 51.20,
      "currency": "USD",
      "billingPeriod": "2026-06-01"
    }
  ]
}

Response

{
  "inserted": 2,
  "failed": 0,
  "results": [
    {
      "id": "usage_789",
      "subscriptionId": "sub_123",
      "status": "created"
    },
    {
      "id": "usage_790",
      "subscriptionId": "sub_124",
      "status": "created"
    }
  ]
}
GET /api/billed-usage

List Billed Usage Records

Gets all billed usage records with filtering and pagination.

Authentication

Bearer Token or Service Token

Query Parameters

Parameter Type Description
$filter string OData filter expression
$orderby string Sort by columns
$skip integer Skip n records
$top integer Take n records

Response

{
  "value": [
    {
      "id": "usage_789",
      "subscriptionId": "sub_123",
      "usageType": "cpu_hours",
      "quantity": 100,
      "amount": 50.00,
      "billingPeriod": "2026-06-01"
    }
  ],
  "count": 300
}

Error Responses

Code HTTP Status Description
USAGE_RECORD_NOT_FOUND 404 Usage record does not exist
SUBSCRIPTION_NOT_FOUND 404 Associated subscription not found
INVALID_QUANTITY 400 Invalid quantity value
BULK_INSERT_FAILED 400 One or more records failed to insert

Quick Links

← Back to Overview ← Ledger API Unbilled Usage API → Try the Playground