## List Organization Billing History

`$ nirvana organizations:billing history`

**get** `/v1/organizations/{organization_id}/billing/history`

List the organization's billing history: prepaid credits, top-ups, and manual adjustments, newest first. Paginated with an opaque cursor.

### Parameters

- `--organization-id: string`

  Organization ID

- `--created-at-max: optional string`

  Only entries at or before this RFC 3339 instant

- `--created-at-min: optional string`

  Only entries at or after this RFC 3339 instant

- `--currency: optional string`

  Filter by currency, as an ISO 4217 code. Case-insensitive.

- `--cursor: optional string`

  Pagination cursor returned by a previous request. Only valid for the same filters and sort order.

- `--limit: optional number`

  Maximum number of items to return

- `--purpose: optional string`

  Filter by the funding flow a credit came from

- `--sort: optional string`

  Comma-separated sort terms in precedence order, each field:asc or field:desc. Fields: created_at, amount

- `--type: optional string`

  Filter by entry type

### Returns

- `billing_history_entry_list: object { items, pagination }`

  - `items: array of BillingHistoryEntry`

    - `id: string`

      Unique identifier for the entry.

    - `amount: string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

    - `created_at: string`

      When the entry was recorded.

    - `currency: string`

      ISO 4217 currency code.

    - `type: "grant" or "adjustment"`

      Kind of entry.

      - `"grant"`

      - `"adjustment"`

    - `description: optional string`

      Human-readable note describing the entry, when available.

    - `purpose: optional "first_charge" or "auto_recharge" or "manual_top_up" or 6 more`

      Why this entry exists: for a grant, the funding flow ("first_charge",
      "auto_recharge", "manual_top_up", "manual_recharge") or "bonus_grant" for
      credit issued with no payment behind it; for an adjustment, the reason the
      balance was reduced ("refund", "dispute", "bonus_void" for issued credit
      withdrawn, "bonus_expiry" for credit that lapsed unspent). Null for
      adjustments with no recorded reason.

      - `"first_charge"`

      - `"auto_recharge"`

      - `"manual_top_up"`

      - `"manual_recharge"`

      - `"bonus_grant"`

      - `"bonus_void"`

      - `"bonus_expiry"`

      - `"refund"`

      - `"dispute"`

    - `receipt_url: optional string`

      Link to the hosted receipt for the payment behind this entry, when one is
      available. Present for prepaid credits funded by a card charge; absent for
      manual adjustments and while a payment's receipt is still being finalized.

  - `pagination: object { next_cursor, previous_cursor, total_count }`

    Pagination response details.

    - `next_cursor: string`

    - `previous_cursor: string`

    - `total_count: number`

### Example

```cli
nirvana organizations:billing history \
  --api-key 'My API Key' \
  --organization-id organization_id
```

#### Response

```json
{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "-69125",
      "created_at": "2025-01-01T00:00:00Z",
      "currency": "USD",
      "type": "grant",
      "description": "Refund adjustment",
      "purpose": "auto_recharge",
      "receipt_url": "https://pay.stripe.com/receipts/..."
    }
  ],
  "pagination": {
    "next_cursor": "RhwniMT4B74siYZcPF8TnCdGI1l9rpPvg",
    "previous_cursor": "ARhwnmi1hA7wEbHbMjdYQlOB_ZusP4fYvw",
    "total_count": 125
  }
}
```