← Catalogue

Cloud Billing & Usage Ledger API

OAS 3.1.0 v2.4.0 ✓ Valid 3.1
specs/cloud-billing-api.yaml • 5 operations • 4 schemas • 1 webhooks
⬇ Download .yaml

Cloud Billing & Usage Ledger API

Real-time metered billing, customer subscriptions, and invoice webhooks (OpenAPI 3.1)

Enterprise metered billing API built natively on **OpenAPI 3.1.0** and JSON Schema 2020-12. Supports usage ingestion, customer credit wallets, and asynchronous invoice webhooks.

Configured Target Servers

/api/mock/cloud-billing-api Built-in OpenAPI 3.1 Mock Server (Instant Local Execution)
https://httpbin.org/anything Public Echo Sandbox (httpbin)

Detected OpenAPI 3.1 / JSON Schema 2020-12 Features

✦ info.summary✦ SPDX license.identifier✦ jsonSchemaDialect✦ webhooks✦ schema examples array✦ type array unions (e.g. ["string", "null"])✦ JSON Schema const

Subscriptions

GET /v1/subscriptions List active subscriptions

Returns a paginated list of customer subscriptions filtered by status or plan tier.

Request Parameters

NameInType (OAS 3.1)Required
statusquerystringOptional
limitqueryintegerOptional

Responses

200 Paginated list of subscriptions
{
  "data": [
    {
      "id": "sub_01J9XYZ890",
      "customerId": "cus_acme_corp",
      "planId": "plan_enterprise_metered",
      "status": "active",
      "cancelAtPeriodEnd": false,
      "discountCode": "LAUNCH25",
      "currentPeriodEnd": "2026-11-20T00:00:00Z"
    }
  ],
  "nextCursor": "cur_98f1a2b"
}
POST /v1/subscriptions Provision a new subscription

Creates a new metered or flat-rate subscription for a customer account.

Request Body (application/json)

{
  "customerId": "cus_acme_corp",
  "planId": "plan_enterprise_metered",
  "trialDays": 14,
  "discountCode": "SCALE2026"
}

Responses

201 Subscription provisioned
{
  "id": "sub_01J9XYZ890",
  "customerId": "cus_acme_corp",
  "planId": "plan_enterprise_metered",
  "status": "active",
  "cancelAtPeriodEnd": false,
  "discountCode": "LAUNCH25",
  "currentPeriodEnd": "2026-11-20T00:00:00Z"
}
GET /v1/subscriptions/{subscriptionId} Retrieve subscription details

Request Parameters

NameInType (OAS 3.1)Required
subscriptionIdpathstringYes

Responses

200 Subscription details
{
  "id": "sub_01J9XYZ890",
  "customerId": "cus_acme_corp",
  "planId": "plan_enterprise_metered",
  "status": "active",
  "cancelAtPeriodEnd": false,
  "discountCode": "LAUNCH25",
  "currentPeriodEnd": "2026-11-20T00:00:00Z"
}
DELETE /v1/subscriptions/{subscriptionId} Cancel subscription immediately or at period end

Request Parameters

NameInType (OAS 3.1)Required
subscriptionIdpathstringYes

Responses

200 Cancellation confirmed
{
  "id": "sub_01J9XYZ890",
  "customerId": "cus_acme_corp",
  "planId": "plan_enterprise_metered",
  "status": "active",
  "cancelAtPeriodEnd": false,
  "discountCode": "LAUNCH25",
  "currentPeriodEnd": "2026-11-20T00:00:00Z"
}

Usage Events

POST /v1/usage-events Ingest metered usage event

High-throughput idempotent ingestion endpoint for customer resource consumption.

Request Body (application/json)

{
  "idempotencyKey": "evt_901283_tokens",
  "customerId": "cus_acme_corp",
  "metric": "gpu_seconds",
  "quantity": 128.5,
  "metadata": {
    "region": "eu-central-1",
    "clusterId": "cls-prod-04"
  }
}

Responses

202 Event accepted for aggregation
{
  "accepted": true,
  "idempotencyKey": "evt_idem_2026_991"
}

OpenAPI 3.1 Webhooks

WEBHOOK POST invoice.finalized Fired when a billing period closes and an invoice is finalized

Webhook Payload Sample

{
  "eventId": "wh_inv_8831",
  "invoiceId": "inv_2026_10_004",
  "amountDueCents": 49500,
  "currency": "USD",
  "pdfUrl": "https://billing.example.com/invoices/inv_2026_10_004.pdf"
}

Component Schemas (JSON Schema 2020-12)

Subscription

object
PropertyTypeRequired
idstring ✓
customerIdstring ✓
planIdstring ✓
statusstring ✓
cancelAtPeriodEndboolean —
discountCodestring | null —
currentPeriodEndstring (date-time)✓

CreateSubscriptionRequest

object
PropertyTypeRequired
customerIdstring ✓
planIdstring ✓
trialDaysinteger | null —
discountCodestring | null —

UsageEventPayload

object
PropertyTypeRequired
idempotencyKeystring ✓
customerIdstring ✓
metricstring ✓
quantitynumber ✓
metadataobject —

InvoiceWebhookEvent

object
PropertyTypeRequired
eventIdstring ✓
invoiceIdstring ✓
amountDueCentsinteger ✓
currencystring ✓
pdfUrlstring | null (uri)—

Delete OpenAPI Specification?

Are you sure you want to permanently delete Cloud Billing & Usage Ledger API (specs/cloud-billing-api.yaml)?