# Billing ## Get Organization Billing Summary `client.Organizations.Billing.Summary(ctx, organizationID) (*OrganizationBillingSummary, error)` **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. ### Parameters - `organizationID string` ### Returns - `type OrganizationBillingSummary struct{…}` 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"). - `DailyCost string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `EffectiveBalance string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `MonthlyCost string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `RechargeThresholdFraction string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `EstimatedNextChargeAt Time` Projected date the balance reaches the recharge threshold at the current run-rate. Null when there is no active usage (never charges). - `RunwayMonths string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Example ```go package main import ( "context" "fmt" "github.com/nirvana-labs/nirvana-go" "github.com/nirvana-labs/nirvana-go/option" ) func main() { client := nirvana.NewClient( option.WithAPIKey("My API Key"), ) organizationBillingSummary, err := client.Organizations.Billing.Summary(context.TODO(), "organization_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", organizationBillingSummary.DailyCost) } ``` #### 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 `client.Organizations.Billing.Cost(ctx, organizationID, query) (*OrganizationDailyCost, error)` **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. ### Parameters - `organizationID string` - `query BillingCostParams` - `From param.Field[Time]` Inclusive start day, YYYY-MM-DD (UTC). Defaults to 30 days before to. - `To param.Field[Time]` Inclusive end day, YYYY-MM-DD (UTC). Defaults to today. ### Returns - `type OrganizationDailyCost struct{…}` 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 []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 ```go package main import ( "context" "fmt" "github.com/nirvana-labs/nirvana-go" "github.com/nirvana-labs/nirvana-go/option" "github.com/nirvana-labs/nirvana-go/organizations" ) func main() { client := nirvana.NewClient( option.WithAPIKey("My API Key"), ) organizationDailyCost, err := client.Organizations.Billing.Cost( context.TODO(), "organization_id", organizations.BillingCostParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", organizationDailyCost.Currency) } ``` #### Response ```json { "currency": "USD", "days": [ { "cost": "-69125", "date": "2026-07-07" } ], "from": "2026-06-08", "to": "2026-07-08" } ``` ## List Organization Billing History `client.Organizations.Billing.History(ctx, organizationID, query) (*BillingHistoryEntryList, error)` **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 - `organizationID string` - `query BillingHistoryParams` - `Cursor param.Field[string]` Pagination cursor returned by a previous request - `Limit param.Field[int64]` Maximum number of items to return ### Returns - `type BillingHistoryEntryList struct{…}` - `Items []BillingHistoryEntry` - `ID string` Unique identifier for the entry. - `Amount string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `CreatedAt Time` When the entry was recorded. - `Currency string` ISO 4217 currency code. - `Type BillingHistoryEntryType` Kind of entry. - `const BillingHistoryEntryTypeGrant BillingHistoryEntryType = "grant"` - `const BillingHistoryEntryTypeAdjustment BillingHistoryEntryType = "adjustment"` - `Description string` Human-readable note describing the entry, when available. - `Pagination Pagination` Pagination response details. - `NextCursor string` - `PreviousCursor string` - `TotalCount int64` ### Example ```go package main import ( "context" "fmt" "github.com/nirvana-labs/nirvana-go" "github.com/nirvana-labs/nirvana-go/option" "github.com/nirvana-labs/nirvana-go/organizations" ) func main() { client := nirvana.NewClient( option.WithAPIKey("My API Key"), ) billingHistoryEntryList, err := client.Organizations.Billing.History( context.TODO(), "organization_id", organizations.BillingHistoryParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", billingHistoryEntryList.Items) } ``` #### 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 `client.Organizations.Billing.TopUp(ctx, organizationID, params) (*OrganizationBillingSummary, error)` **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. ### Parameters - `organizationID string` - `params BillingTopUpParams` - `Amount param.Field[string]` Body param: Amount to charge and credit, in USD. Must be greater than 0, at most two decimal places, and at most 10000. - `IdempotencyKey param.Field[string]` Header param: Unique idempotency key scoping the charge; reuse the same value across retries so a timed-out top-up is not charged twice ### Returns - `type OrganizationBillingSummary struct{…}` 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"). - `DailyCost string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `EffectiveBalance string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `MonthlyCost string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `RechargeThresholdFraction string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `EstimatedNextChargeAt Time` Projected date the balance reaches the recharge threshold at the current run-rate. Null when there is no active usage (never charges). - `RunwayMonths string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Example ```go package main import ( "context" "fmt" "github.com/nirvana-labs/nirvana-go" "github.com/nirvana-labs/nirvana-go/option" "github.com/nirvana-labs/nirvana-go/organizations" ) func main() { client := nirvana.NewClient( option.WithAPIKey("My API Key"), ) organizationBillingSummary, err := client.Organizations.Billing.TopUp( context.TODO(), "organization_id", organizations.BillingTopUpParams{ Amount: "50.00", IdempotencyKey: "Idempotency-Key", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", organizationBillingSummary.DailyCost) } ``` #### 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 - `type BillingHistoryEntry struct{…}` 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"). - `CreatedAt Time` When the entry was recorded. - `Currency string` ISO 4217 currency code. - `Type BillingHistoryEntryType` Kind of entry. - `const BillingHistoryEntryTypeGrant BillingHistoryEntryType = "grant"` - `const BillingHistoryEntryTypeAdjustment BillingHistoryEntryType = "adjustment"` - `Description string` Human-readable note describing the entry, when available. ### Billing History Entry List - `type BillingHistoryEntryList struct{…}` - `Items []BillingHistoryEntry` - `ID string` Unique identifier for the entry. - `Amount string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `CreatedAt Time` When the entry was recorded. - `Currency string` ISO 4217 currency code. - `Type BillingHistoryEntryType` Kind of entry. - `const BillingHistoryEntryTypeGrant BillingHistoryEntryType = "grant"` - `const BillingHistoryEntryTypeAdjustment BillingHistoryEntryType = "adjustment"` - `Description string` Human-readable note describing the entry, when available. - `Pagination Pagination` Pagination response details. - `NextCursor string` - `PreviousCursor string` - `TotalCount int64` ### Billing History Entry Type - `type BillingHistoryEntryType string` Kind of entry. - `const BillingHistoryEntryTypeGrant BillingHistoryEntryType = "grant"` - `const BillingHistoryEntryTypeAdjustment BillingHistoryEntryType = "adjustment"` ### Daily Cost Point - `type DailyCostPoint struct{…}` 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 - `type OrganizationDailyCost struct{…}` 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 []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).