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
Add Operation / Endpoint

GET /v1/subscriptions
Summary
operationId
Parameters
POST /v1/subscriptions
Summary
operationId
GET /v1/subscriptions/{subscriptionId}
Summary
operationId
Parameters
DELETE /v1/subscriptions/{subscriptionId}
Summary
operationId
Parameters
POST /v1/usage-events
Summary
operationId
openapi: 3.1.0
info:
  title: Cloud Billing & Usage Ledger API
  summary: Real-time metered billing, customer subscriptions, and invoice webhooks (OpenAPI 3.1)
  description: |
    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.
  version: 2.4.0
  license:
    name: Apache 2.0
    identifier: Apache-2.0
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
servers:
  - url: /api/mock/cloud-billing-api
    description: Built-in OpenAPI 3.1 Mock Server (Instant Local Execution)
  - url: https://httpbin.org/anything
    description: Public Echo Sandbox (httpbin)
tags:
  - name: Subscriptions
    description: Manage customer plans and billing cycles
  - name: Usage Events
    description: Ingest high-throughput metered telemetry events
  - name: Invoices
    description: Retrieve and finalize customer invoices
paths:
  /v1/subscriptions:
    get:
      operationId: listSubscriptions
      summary: List active subscriptions
      description: Returns a paginated list of customer subscriptions filtered by status or plan tier.
      tags:
        - Subscriptions
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by subscription lifecycle state
          schema:
            type: string
            enum: [active, trialing, past_due, canceled]
            default: active
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Paginated list of subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  nextCursor:
                    type: ['string', 'null']
                    examples: ['cur_98f1a2b']
    post:
      operationId: createSubscription
      summary: Provision a new subscription
      description: Creates a new metered or flat-rate subscription for a customer account.
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '201':
          description: Subscription provisioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /v1/subscriptions/{subscriptionId}:
    get:
      operationId: getSubscriptionById
      summary: Retrieve subscription details
      tags:
        - Subscriptions
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: Unique subscription identifier
          schema:
            type: string
            examples: ['sub_01J9XYZ890']
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    delete:
      operationId: cancelSubscription
      summary: Cancel subscription immediately or at period end
      tags:
        - Subscriptions
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
            examples: ['sub_01J9XYZ890']
      responses:
        '200':
          description: Cancellation confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /v1/usage-events:
    post:
      operationId: ingestUsageEvent
      summary: Ingest metered usage event
      description: High-throughput idempotent ingestion endpoint for customer resource consumption.
      tags:
        - Usage Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageEventPayload'
      responses:
        '202':
          description: Event accepted for aggregation
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
                    const: true
                  idempotencyKey:
                    type: string
                    examples: ['evt_idem_2026_991']
webhooks:
  invoice.finalized:
    post:
      operationId: onInvoiceFinalizedWebhook
      summary: Fired when a billing period closes and an invoice is finalized
      tags:
        - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceWebhookEvent'
      responses:
        '200':
          description: Return 200 OK to acknowledge receipt of the webhook
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Subscription:
      type: object
      required:
        - id
        - customerId
        - planId
        - status
        - currentPeriodEnd
      properties:
        id:
          type: string
          examples: ['sub_01J9XYZ890']
        customerId:
          type: string
          examples: ['cus_acme_corp']
        planId:
          type: string
          examples: ['plan_enterprise_metered']
        status:
          type: string
          enum: [active, trialing, past_due, canceled]
          examples: ['active']
        cancelAtPeriodEnd:
          type: boolean
          default: false
        discountCode:
          type: ['string', 'null']
          description: Optional promotional code (uses OpenAPI 3.1 union type array)
          examples: ['LAUNCH25']
        currentPeriodEnd:
          type: string
          format: date-time
          examples: ['2026-11-20T00:00:00Z']
    CreateSubscriptionRequest:
      type: object
      required:
        - customerId
        - planId
      properties:
        customerId:
          type: string
          examples: ['cus_acme_corp']
        planId:
          type: string
          examples: ['plan_enterprise_metered']
        trialDays:
          type: ['integer', 'null']
          minimum: 0
          maximum: 90
          examples: [14]
        discountCode:
          type: ['string', 'null']
          examples: ['SCALE2026']
    UsageEventPayload:
      type: object
      required:
        - idempotencyKey
        - customerId
        - metric
        - quantity
      properties:
        idempotencyKey:
          type: string
          examples: ['evt_901283_tokens']
        customerId:
          type: string
          examples: ['cus_acme_corp']
        metric:
          type: string
          examples: ['gpu_seconds']
        quantity:
          type: number
          minimum: 0
          examples: [128.5]
        metadata:
          type: object
          properties:
            region:
              type: string
              examples: ['eu-central-1']
            clusterId:
              type: ['string', 'null']
              examples: ['cls-prod-04']
    InvoiceWebhookEvent:
      type: object
      required:
        - eventId
        - invoiceId
        - amountDueCents
        - currency
      properties:
        eventId:
          type: string
          examples: ['wh_inv_8831']
        invoiceId:
          type: string
          examples: ['inv_2026_10_004']
        amountDueCents:
          type: integer
          examples: [49500]
        currency:
          type: string
          examples: ['USD']
        pdfUrl:
          type: ['string', 'null']
          format: uri
          examples: ['https://billing.example.com/invoices/inv_2026_10_004.pdf']
OpenAPI 3.1 Validator & Linter (0 findings) ✓ Specification is valid OpenAPI 3.1.0
No validation errors or warnings found.