Skip to content
Nirvana LabsNirvana Labs API
Docs
    API Reference
    Organizations
    Billing

    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.

    ParametersExpand Collapse
    --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

    ReturnsExpand Collapse
    billing_history_entry_list: object { items, pagination }
    items: array of BillingHistoryEntry { id, amount, created_at, 5 more }
    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.

    List Organization Billing History

    nirvana organizations:billing history \
  --api-key 'My API Key' \
  --organization-id organization_id
    {
  "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
  }
}
    Returns Examples
    {
  "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
  }
}