# Billing reference

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

Canonical: https://entirefeed.com/docs/reference/billing

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

## Balance response

```json
{
  "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

- `reserved`: The current estimate is held while work is active. Included in reserved balance, not available balance.
- `settled`: Final usage was charged. The settled amount remains spent; unused hold can be released.
- `released`: The held amount was returned. Released funds are available again.
- `manual_review`: Final cost could not be resolved automatically. The hold remains unavailable until resolution.

## Ledger entries

Entry types: `TOP_UP`, `RESERVE`, `RELEASE`, `SETTLE`, `ADJUSTMENT`, `REFUND`, `ADMIN_CREDIT`.

```json
{
  "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

| Scenario | Amounts | Result |
| --- | --- | --- |
| Final cost below reservation | $1.20 reserved; $0.90 final | Settle $0.90 and release $0.30 to available balance. |
| Overage covered | $1.20 reserved; $1.50 final; at least $0.30 available | Settle $1.20 and debit a $0.30 adjustment. |
| Overage capped | $1.20 reserved; $1.50 final; $0.20 available | Settle $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.