# Billing

## Get Organization Billing Summary

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

Get the organization's billing summary: effective balance, monthly and daily run-rate cost, runway, and the projected next-recharge date. Costs are run-rate projections.

### Path Parameters

- `organization_id: string`

### Returns

- `OrganizationBillingSummary object { daily_cost, effective_balance, monthly_cost, 3 more }`

  Forward-looking billing summary for an organization. All costs are run-rate projections from the organization's current active usage ("≈ $X/mo at current usage").

  - `daily_cost: string`

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

  - `effective_balance: string`

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

  - `monthly_cost: string`

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

  - `recharge_threshold_fraction: string`

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

  - `estimated_next_charge_at: optional string`

    Projected date the balance reaches the recharge threshold at the current run-rate. Null when there is no active usage (never charges).

  - `runway_months: optional string`

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

### Example

```http
curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/summary \
    -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"
```

#### Response

```json
{
  "daily_cost": "-69125",
  "effective_balance": "-69125",
  "monthly_cost": "-69125",
  "recharge_threshold_fraction": "-69125",
  "estimated_next_charge_at": "2025-01-01T00:00:00Z",
  "runway_months": "-69125"
}
```

## Get Organization Daily Cost

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

Get the organization's total usage cost per UTC day over a date range (max 90 days), summing open and closed resources. One entry per day, oldest first. Defaults to the last 30 days.

### Path Parameters

- `organization_id: string`

### Query Parameters

- `from: optional string`

  Inclusive start day, YYYY-MM-DD (UTC). Defaults to 30 days before to.

- `to: optional string`

  Inclusive end day, YYYY-MM-DD (UTC). Defaults to today.

### Returns

- `OrganizationDailyCost object { currency, days, from, to }`

  Daily usage cost over a date range: one entry per UTC day (zero on idle days), summing open and closed resources. Suitable for a daily cost bar chart.

  - `currency: string`

    ISO 4217 currency code.

  - `days: array of DailyCostPoint`

    One entry per UTC day in the range, oldest first.

    - `cost: string`

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

    - `date: string`

      UTC calendar day (YYYY-MM-DD).

  - `from: string`

    Inclusive start of the range, as a UTC calendar day (YYYY-MM-DD).

  - `to: string`

    Inclusive end of the range, as a UTC calendar day (YYYY-MM-DD).

### Example

```http
curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/cost \
    -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"
```

#### Response

```json
{
  "currency": "USD",
  "days": [
    {
      "cost": "-69125",
      "date": "2026-07-07"
    }
  ],
  "from": "2026-06-08",
  "to": "2026-07-08"
}
```

## List Organization 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.

### Path Parameters

- `organization_id: string`

### Query Parameters

- `cursor: optional string`

  Pagination cursor returned by a previous request

- `limit: optional number`

  Maximum number of items to return

### Returns

- `BillingHistoryEntryList 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: BillingHistoryEntryType`

      Kind of entry.

      - `"grant"`

      - `"adjustment"`

    - `description: optional string`

      Human-readable note describing the entry, when available.

  - `pagination: Pagination`

    Pagination response details.

    - `next_cursor: string`

    - `previous_cursor: string`

    - `total_count: number`

### Example

```http
curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/history \
    -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"
```

#### 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"
    }
  ],
  "pagination": {
    "next_cursor": "RhwniMT4B74siYZcPF8TnCdGI1l9rpPvg",
    "previous_cursor": "ARhwnmi1hA7wEbHbMjdYQlOB_ZusP4fYvw",
    "total_count": 125
  }
}
```

## Top Up Organization Prepaid Balance

**post** `/v1/organizations/{organization_id}/billing/topup`

Charge the card on file and credit the prepaid balance. A unique Idempotency-Key header is required; reuse it across retries so a timed-out top-up is not charged twice.

### Path Parameters

- `organization_id: string`

### Header Parameters

- `"Idempotency-Key": string`

### Body Parameters

- `amount: string`

  Amount to charge and credit, in USD. Must be greater than 0, at most two decimal places, and at most 10000.

### Returns

- `OrganizationBillingSummary object { daily_cost, effective_balance, monthly_cost, 3 more }`

  Forward-looking billing summary for an organization. All costs are run-rate projections from the organization's current active usage ("≈ $X/mo at current usage").

  - `daily_cost: string`

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

  - `effective_balance: string`

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

  - `monthly_cost: string`

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

  - `recharge_threshold_fraction: string`

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

  - `estimated_next_charge_at: optional string`

    Projected date the balance reaches the recharge threshold at the current run-rate. Null when there is no active usage (never charges).

  - `runway_months: optional string`

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

### Example

```http
curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/topup \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \
    -d '{
          "amount": "50.00"
        }'
```

#### Response

```json
{
  "daily_cost": "-69125",
  "effective_balance": "-69125",
  "monthly_cost": "-69125",
  "recharge_threshold_fraction": "-69125",
  "estimated_next_charge_at": "2025-01-01T00:00:00Z",
  "runway_months": "-69125"
}
```

## Domain Types

### Billing History Entry

- `BillingHistoryEntry object { id, amount, created_at, 3 more }`

  A single billing history line item: a prepaid credit or a manual adjustment.

  - `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: BillingHistoryEntryType`

    Kind of entry.

    - `"grant"`

    - `"adjustment"`

  - `description: optional string`

    Human-readable note describing the entry, when available.

### Billing History Entry List

- `BillingHistoryEntryList 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: BillingHistoryEntryType`

      Kind of entry.

      - `"grant"`

      - `"adjustment"`

    - `description: optional string`

      Human-readable note describing the entry, when available.

  - `pagination: Pagination`

    Pagination response details.

    - `next_cursor: string`

    - `previous_cursor: string`

    - `total_count: number`

### Billing History Entry Type

- `BillingHistoryEntryType = "grant" or "adjustment"`

  Kind of entry.

  - `"grant"`

  - `"adjustment"`

### Daily Cost Point

- `DailyCostPoint object { cost, date }`

  Total usage cost for a single UTC day.

  - `cost: string`

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

  - `date: string`

    UTC calendar day (YYYY-MM-DD).

### Organization Daily Cost

- `OrganizationDailyCost object { currency, days, from, to }`

  Daily usage cost over a date range: one entry per UTC day (zero on idle days), summing open and closed resources. Suitable for a daily cost bar chart.

  - `currency: string`

    ISO 4217 currency code.

  - `days: array of DailyCostPoint`

    One entry per UTC day in the range, oldest first.

    - `cost: string`

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

    - `date: string`

      UTC calendar day (YYYY-MM-DD).

  - `from: string`

    Inclusive start of the range, as a UTC calendar day (YYYY-MM-DD).

  - `to: string`

    Inclusive end of the range, as a UTC calendar day (YYYY-MM-DD).