Billing

Read-only wallet endpoints — balance, lots, ledger, usage. Available even when org is suspended.

Get billing summary

GET

/api/v1

/billing

auth_token (cookie)

Bearer

Returns the wallet snapshot for the authenticated user's organization: credit balance, billing status, threshold, and project quota. Available even on suspended orgs.

Get billing summary › Responses

Billing summary

BillingSummaryResponse

org_id

string · uuid

billing_status

string · enum

Enum values:

active

low_credit_warned

suspended

Example: active

credit_balance_cents

integer · int64

Denormalized cache of SUM(ledger). Source of truth is credit_ledger_entries.

Example: 12500

low_credit_threshold_cents

integer · int64

Below this balance the org transitions to low_credit_warned then suspended. Default 500.

Example: 500

project_quota

integer

project_count

integer

Active (non-deleted) projects in this org.

Example: 1

low_credit_warned_at

string | null · date-time

List active credit lots

GET

/api/v1

/billing/lots

auth_token (cookie)

Bearer

Returns all credit lots for the org (consumed and active). Used to show the user where their balance comes from (promo, plan-included, manual, topup) and when each lot expires. Lots are consumed in priority order (promo → plan_included → manual → topup) then by earliest expiry.

List active credit lots › Responses

List of credit lots

CreditLot[]

Bucket of credits. Lots are consumed in order of `consumption_priority` (1 = first), then by earliest `expires_at`. `plan_included` is a legacy lot type kept only for historical rows.

CreditLot

id

string · uuid

organization_id

string · uuid

lot_type

string · enum

Enum values:

promo

plan_included

manual

topup

initial_amount_cents

integer · int64

remaining_amount_cents

integer · int64

consumption_priority

integer

1=promo, 2=plan_included, 3=manual, 4=topup. Lower priority is consumed first.

expires_at

string | null · date-time

created_at

string · date-time

List ledger entries (paginated)

GET

/api/v1

/billing/ledger

auth_token (cookie)

Bearer

Append-only audit log of every credit movement (grants, usage, adjustments, expiries). Paginated.

List ledger entries (paginated) › query Parameters

limit

integer · min: 1 · max: 200

Default: 50

offset

integer · min: 0

Default: 0

List ledger entries (paginated) › Responses

Paginated ledger entries

LedgerListResponse

LedgerEntry[]

limit

integer

offset

integer

total

integer

GET/billing/ledger

curl /api/v1/billing/ledger

Example Responses

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "organization_id": "00000000-0000-0000-0000-000000000000",
      "amount_cents": 0,
      "entry_type": "plan_grant",
      "balance_after_cents": 0,
      "lot_id": "00000000-0000-0000-0000-000000000000",
      "source_type": "project",
      "source_id": "source_id",
      "project_id": "00000000-0000-0000-0000-000000000000",
      "vm_size": "vm_size",
      "price_cents_per_hour_snapshot": 0,
      "billable_seconds": 0,
      "hour_bucket": "2024-08-25T15:00:00Z",
      "idempotency_key": "idempotency_key",
      "notes": "notes",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 142
}

json

application/json

Daily usage totals (chart-ready)

GET

/api/v1

/billing/ledger/daily

auth_token (cookie)

Bearer

Returns one row per UTC day with the sum of billable usage in cents — convenient for usage charts. Default window is the last 30 days.

Daily usage totals (chart-ready) › query Parameters

from

string · date-time

RFC3339, default = now − 30 days

to

string · date-time

RFC3339, default = now. Must be strictly after from.

Daily usage totals (chart-ready) › Responses

Daily usage rollup

DailyUsageEntry[]

DailyUsageEntry

day

string · date-time

UTC start-of-day timestamp.

total_cents

integer · int64

Sum of metered usage for the day, in cents.

List metering runs over a window

GET

/api/v1

/billing/usage

auth_token (cookie)

Bearer

Hourly usage rollup from metering_runs. Default window is the last 30 days. Use this to render usage charts.

List metering runs over a window › query Parameters

from

string · date-time

RFC3339, default = now − 30 days

to

string · date-time

RFC3339, default = now. Must be strictly after from.

List metering runs over a window › Responses

List of metering runs

MeteringRun[]

Hourly usage rollup, one row per (hour_bucket, project_id).

MeteringRun

hour_bucket

string · date-time

project_id

string · uuid

organization_id

string · uuid

billable_seconds

integer

Seconds the project was running during the hour (clamped to 3600).

Example: 3600

vm_size

string

price_cents_per_hour_snapshot

integer

total_cost_cents

integer · int64

processed_at

string · date-time

Redeem a credit code

POST

/api/v1

/billing/redeem-code

auth_token (cookie)

Bearer

Redeems a single-use credit code into a "promo" credit lot for the authenticated user's organization.

Redeem a credit code › Request Body

code

string · required

Redeem a credit code › Responses

Code redeemed

status

string · required

amount_cents

integer · int64 · required

Credit amount added, in cents

Logs Volumes