# 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_days: 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_days": "-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. - `funding_purpose: optional "first_charge" or "auto_recharge" or "manual_top_up" or "manual_recharge"` Funding flow that produced this entry, for a grant: "first_charge", "auto_recharge", "manual_top_up", or "manual_recharge". Null for adjustments. - `"first_charge"` - `"auto_recharge"` - `"manual_top_up"` - `"manual_recharge"` - `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: 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", "funding_purpose": "auto_recharge", "receipt_url": "https://pay.stripe.com/receipts/..." } ], "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_days: 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_days": "-69125", "estimated_next_charge_at": "2025-01-01T00:00:00Z", "runway_months": "-69125" } ``` ## Re-trigger Organization Prepaid Recharge **post** `/v1/organizations/{organization_id}/billing/recharge` Charge the card on file up to the recharge target now instead of waiting for the scheduled retry. Automatic-policy prepaid organizations only. Idempotency-Key header required. ### Path Parameters - `organization_id: string` ### Header Parameters - `"Idempotency-Key": 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_days: 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/recharge \ -X POST \ -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" ``` #### Response ```json { "daily_cost": "-69125", "effective_balance": "-69125", "monthly_cost": "-69125", "recharge_threshold_days": "-69125", "estimated_next_charge_at": "2025-01-01T00:00:00Z", "runway_months": "-69125" } ``` ## Get Organization Usage Statement **get** `/v1/organizations/{organization_id}/billing/statements` Get the itemized monthly usage statement: consumption grouped by project, resource type, and dimension, priced from recorded usage. Defaults to the current month. ### Path Parameters - `organization_id: string` ### Query Parameters - `month: optional string` Billing month, YYYY-MM (UTC). Defaults to the current month. ### Returns - `OrganizationUsageStatement object { currency, month, projects, total }` Itemized usage statement for a billing month: consumption grouped by project, resource type, and dimension. Costs are recorded at consumption time, not re-priced. - `currency: string` ISO 4217 currency code. - `month: string` Billing month the statement covers, as YYYY-MM (UTC). - `projects: array of StatementProject` One entry per project with consumption in the month, ordered by name. - `project_id: string` Project identifier. - `project_name: string` Human-readable project name. - `resource_types: array of StatementResourceType` Consumption grouped by resource type. - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` Component dimensions nested under this one (e.g. vCPU and memory under an instance type). Empty for a leaf. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_vcpu", "compute_memory_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_n1_standard_8", "storage_abs_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `resource_type: string` Resource type the line items belong to (e.g. "vm", "volume", "nks_node_pool"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `total: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Example ```http curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/statements \ -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" ``` #### Response ```json { "currency": "USD", "month": "2026-07", "projects": [ { "project_id": "018f8c1a-1b2c-7d3e-9f4a-5b6c7d8e9f01", "project_name": "production", "resource_types": [ { "items": [ { "children": [ { "cost": "-69125", "dimension": "compute_vcpu", "display_name": "vCPU (hours)", "quantity_hours": "-69125", "unit_price": "-69125" } ], "cost": "-69125", "dimension": "compute_n1_standard_8", "display_name": "VM (n1-standard-8)", "quantity_hours": "-69125", "unit_price": "-69125" } ], "resource_type": "vm", "subtotal": "-69125" } ], "subtotal": "-69125" } ], "total": "-69125" } ``` ## Domain Types ### Billing History Entry - `BillingHistoryEntry object { id, amount, created_at, 5 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. - `funding_purpose: optional "first_charge" or "auto_recharge" or "manual_top_up" or "manual_recharge"` Funding flow that produced this entry, for a grant: "first_charge", "auto_recharge", "manual_top_up", or "manual_recharge". Null for adjustments. - `"first_charge"` - `"auto_recharge"` - `"manual_top_up"` - `"manual_recharge"` - `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. ### 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. - `funding_purpose: optional "first_charge" or "auto_recharge" or "manual_top_up" or "manual_recharge"` Funding flow that produced this entry, for a grant: "first_charge", "auto_recharge", "manual_top_up", or "manual_recharge". Null for adjustments. - `"first_charge"` - `"auto_recharge"` - `"manual_top_up"` - `"manual_recharge"` - `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: 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). ### Organization Usage Statement - `OrganizationUsageStatement object { currency, month, projects, total }` Itemized usage statement for a billing month: consumption grouped by project, resource type, and dimension. Costs are recorded at consumption time, not re-priced. - `currency: string` ISO 4217 currency code. - `month: string` Billing month the statement covers, as YYYY-MM (UTC). - `projects: array of StatementProject` One entry per project with consumption in the month, ordered by name. - `project_id: string` Project identifier. - `project_name: string` Human-readable project name. - `resource_types: array of StatementResourceType` Consumption grouped by resource type. - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` Component dimensions nested under this one (e.g. vCPU and memory under an instance type). Empty for a leaf. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_vcpu", "compute_memory_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_n1_standard_8", "storage_abs_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `resource_type: string` Resource type the line items belong to (e.g. "vm", "volume", "nks_node_pool"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `total: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Line Item - `StatementLineItem object { children, cost, dimension, 3 more }` A top-level metered dimension. Heads nest components as children (cost is the subtotal, unit_price null); standalone dimensions carry a unit price and an empty children array. - `children: array of StatementLineItemLeaf` Component dimensions nested under this one (e.g. vCPU and memory under an instance type). Empty for a leaf. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_vcpu", "compute_memory_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_n1_standard_8", "storage_abs_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Line Item Leaf - `StatementLineItemLeaf object { cost, dimension, display_name, 2 more }` A priced dimension line: a component nested under a head, or one rate segment of a dimension whose price changed mid-period. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_vcpu", "compute_memory_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Project - `StatementProject object { project_id, project_name, resource_types, subtotal }` A single project's consumption within a usage statement. - `project_id: string` Project identifier. - `project_name: string` Human-readable project name. - `resource_types: array of StatementResourceType` Consumption grouped by resource type. - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` Component dimensions nested under this one (e.g. vCPU and memory under an instance type). Empty for a leaf. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_vcpu", "compute_memory_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_n1_standard_8", "storage_abs_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `resource_type: string` Resource type the line items belong to (e.g. "vm", "volume", "nks_node_pool"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Resource Type - `StatementResourceType object { items, resource_type, subtotal }` Consumption for one resource type within a project (e.g. every VM, every volume). - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` Component dimensions nested under this one (e.g. vCPU and memory under an instance type). Empty for a leaf. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_vcpu", "compute_memory_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `dimension: string` Metered dimension identifier (e.g. "compute_n1_standard_8", "storage_abs_gb"). - `display_name: string` Human-readable label for the dimension. - `quantity_hours: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `resource_type: string` Resource type the line items belong to (e.g. "vm", "volume", "nks_node_pool"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). # Recharge Policy ## Get Organization Recharge Policy **get** `/v1/organizations/{organization_id}/billing/recharge_policy` Get the organization's recharge configuration: the top-up mode, the fixed and proportional threshold components, and when the current mode took effect. ### Path Parameters - `organization_id: string` ### Returns - `OrganizationRechargePolicy object { policy, policy_args, policy_since }` An organization's current recharge policy. policy_args is null for a manual policy. - `policy: RechargePolicyMode` Policy is the top-up mode. - `"manual"` - `"automatic"` - `policy_args: AutomaticPolicyArgs` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `policy_since: string` PolicySince is when the policy currently in force took effect. Any change moves it, including an edit to the threshold parameters of an automatic policy. ### Example ```http curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/recharge_policy \ -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" ``` #### Response ```json { "policy": "automatic", "policy_args": { "fixed": "-69125", "runway_days": "-69125", "monthly_cap": "-69125" }, "policy_since": "2026-07-30T12:00:00Z" } ``` ## Update Organization Recharge Policy **patch** `/v1/organizations/{organization_id}/billing/recharge_policy` Update the organization's recharge mode: manual for self-serve top-ups, or automatic to charge the card on file at the recharge threshold (fixed and proportional required). ### Path Parameters - `organization_id: string` ### Body Parameters - `policy: RechargePolicyMode` Policy is the top-up mode. - `"manual"` - `"automatic"` - `policy_args: optional AutomaticPolicyArgs` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Returns - `OrganizationRechargePolicy object { policy, policy_args, policy_since }` An organization's current recharge policy. policy_args is null for a manual policy. - `policy: RechargePolicyMode` Policy is the top-up mode. - `"manual"` - `"automatic"` - `policy_args: AutomaticPolicyArgs` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `policy_since: string` PolicySince is when the policy currently in force took effect. Any change moves it, including an edit to the threshold parameters of an automatic policy. ### Example ```http curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/recharge_policy \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \ -d '{ "policy": "automatic" }' ``` #### Response ```json { "policy": "automatic", "policy_args": { "fixed": "-69125", "runway_days": "-69125", "monthly_cap": "-69125" }, "policy_since": "2026-07-30T12:00:00Z" } ``` ## Domain Types ### Automatic Policy Args - `AutomaticPolicyArgs object { fixed, runway_days, monthly_cap }` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Organization Recharge Policy - `OrganizationRechargePolicy object { policy, policy_args, policy_since }` An organization's current recharge policy. policy_args is null for a manual policy. - `policy: RechargePolicyMode` Policy is the top-up mode. - `"manual"` - `"automatic"` - `policy_args: AutomaticPolicyArgs` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `policy_since: string` PolicySince is when the policy currently in force took effect. Any change moves it, including an edit to the threshold parameters of an automatic policy. ### Recharge Policy Mode - `RechargePolicyMode = "manual" or "automatic"` Policy is the top-up mode. - `"manual"` - `"automatic"`