Reference

Billing reference

Inspect balance fields, usage states, ledger entry types, filters, and read-only billing endpoints.

On this page

All public billing amounts are decimal USD strings. Do not parse them as binary floating-point values when exact accounting matters.

Balance response

{
  "properties": {
    "available": {
      "$ref": "#/components/schemas/Money"
    },
    "currency": {
      "const": "usd",
      "default": "usd",
      "title": "Currency",
      "type": "string"
    },
    "reserved": {
      "$ref": "#/components/schemas/Money"
    },
    "total": {
      "$ref": "#/components/schemas/Money"
    }
  },
  "required": [
    "available",
    "reserved",
    "total"
  ],
  "title": "BillingSummaryResponse",
  "type": "object"
}

Usage status

reservedThe current estimate is held while work is active.Included in reserved balance, not available balance.

settledFinal usage was charged.The settled amount remains spent; unused hold can be released.

releasedThe held amount was returned.Released funds are available again.

manual_reviewFinal cost could not be resolved automatically.The hold remains unavailable until resolution.

Ledger entries

TOP_UPRESERVERELEASESETTLEADJUSTMENTREFUNDADMIN_CREDIT

{
  "properties": {
    "amount_usd": {
      "title": "Amount Usd",
      "type": "string"
    },
    "available_after_usd": {
      "title": "Available After Usd",
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "description": {
      "title": "Description",
      "type": "string"
    },
    "generation_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Generation Id"
    },
    "id": {
      "title": "Id",
      "type": "string"
    },
    "reserved_after_usd": {
      "title": "Reserved After Usd",
      "type": "string"
    },
    "type": {
      "enum": [
        "TOP_UP",
        "RESERVE",
        "RELEASE",
        "SETTLE",
        "ADJUSTMENT",
        "REFUND",
        "ADMIN_CREDIT"
      ],
      "title": "Type",
      "type": "string"
    },
    "workflow_run_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Workflow Run Id"
    }
  },
  "required": [
    "id",
    "type",
    "amount_usd",
    "available_after_usd",
    "reserved_after_usd",
    "description",
    "created_at"
  ],
  "title": "BillingLedgerEntryResponse",
  "type": "object"
}

Adjustment limit

Final cost below reservation$1.20 reserved; $0.90 finalSettle $0.90 and release $0.30 to available balance.

Overage covered$1.20 reserved; $1.50 final; at least $0.30 availableSettle $1.20 and debit a $0.30 adjustment.

Overage capped$1.20 reserved; $1.50 final; $0.20 availableSettle $1.20 and debit a $0.20 adjustment. Available balance stops at $0.00.

Maximum additional debit: available_balance. A settlement never creates a negative available balance.