Unbilled Usage API Reference

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

Base Path: /api/unbilled-usage

Overview

The Unbilled Usage API provides endpoints for managing unbilled usage records including creation, retrieval, and listing. Tracks consumption data that has not yet been billed to customers.

Key Operations

API Endpoints

POST /api/unbilled-usage

Create Unbilled Usage Record

Creates a new unbilled usage record for a subscription.

Authentication

Bearer Token or Service Token

Request Body

{
  "subscriptionId": "sub_123",
  "customerId": "cust_456",
  "usageType": "cpu_hours",
  "quantity": 50,
  "unitPrice": 0.50,
  "estimatedAmount": 25.00,
  "currency": "USD",
  "usageDate": "2026-06-02T10:30:00Z",
  "billableStartDate": "2026-07-01"
}

Response

{
  "id": "usage_791",
  "subscriptionId": "sub_123",
  "usageType": "cpu_hours",
  "quantity": 50,
  "estimatedAmount": 25.00,
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/unbilled-usage/{id}

Get Unbilled Usage Record by ID

Gets unbilled usage record details by ID.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
id string

Response

{
  "id": "usage_791",
  "subscriptionId": "sub_123",
  "customerId": "cust_456",
  "usageType": "cpu_hours",
  "quantity": 50,
  "unitPrice": 0.50,
  "estimatedAmount": 25.00,
  "currency": "USD",
  "usageDate": "2026-06-02T10:30:00Z",
  "billableStartDate": "2026-07-01",
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/unbilled-usage

List Unbilled Usage Records

Gets all unbilled 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_791",
      "subscriptionId": "sub_123",
      "usageType": "cpu_hours",
      "quantity": 50,
      "estimatedAmount": 25.00,
      "billableStartDate": "2026-07-01"
    }
  ],
  "count": 150
}

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
INVALID_BILLABLE_DATE 400 Billable date must be in the future

Quick Links

← Back to Overview ← Billed Usage API CMS Pages API → Try the Playground