---
title: "Set or clear the monthly usage budget (owner)"
method: PATCH
path: "/api/v1/organizations/{organization_id}/billing/budget"
tags: ["organizations"]
---

# Set or clear the monthly usage budget (owner)

`PATCH /api/v1/organizations/{organization_id}/billing/budget`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/organizations/{organization_id}/billing/budget`
- Auth: HTTP bearer

## Path parameters

- `organization_id` string, required

## Request body

- object

## Response `200`

Updated billing page

- BillingPage
  - `token_account` object, required
    - `balance_usd` string, required
    - `reserved_usd` string, required
    - `available_usd` string, required
    - `top_up_cents` integer[], required
  - `organization_id` string, required
  - `can_manage_contact` boolean, required
  - `can_manage_extra_spend` boolean, required
  - `can_manage_local_subscription` boolean, required
  - `can_manage_payment_method` boolean, required
  - `extra_spend_enabled` boolean, required: Organization consent to paid overages across all metered usage.
  - `deployment_usage_visible` boolean, required
  - `customer` BillingCustomer, required
    - `billing_email` string, nullable, required
    - `tax_status` 'manual' | 'automatic', required
    - `has_stripe_customer` boolean, required
    - `has_metronome_customer` boolean, required
    - `delinquent` boolean, required
    - `delinquent_since` string, nullable
  - `subscription` BillingSubscription, required
    - `id` string, required
    - `status` 'trialing' | 'active' | 'past_due' | 'unpaid' | 'canceled' | 'incomplete', required
    - `seat_quantity` integer, required
    - `complimentary` boolean, required
    - `package_key` string, required
    - `cancel_at_period_end` boolean, required
    - `has_metronome_contract` boolean, required
    - `current_period_started_at` string, nullable
    - `current_period_ended_at` string, nullable
    - `trial_ends_at` string, nullable
    - `free_coupon_ends_at` string, nullable
    - `cancel_at` string, nullable
    - `canceled_at` string, nullable
  - `package` BillingPackage, required
    - `key` string, required
    - `name` string, required
    - `visibility` 'public' | 'custom', required
    - `revision` integer, required
    - `base_price_cents` integer, required
    - `seat_price_cents` integer, required
    - `currency` string, required
    - `billing_interval` 'month' | 'year', required
    - `billing_policy` 'metered' | 'prepaid_browser', required
    - `trial_days` integer, required
    - `max_seats` integer, nullable
    - `pay_as_you_go_enabled` boolean, required
    - `roder_daily_run_limit` integer
    - `roder_run_concurrency_limit` integer
    - `rates` BillingPackageRate[], required
      - `meter_key` string, required
      - `dimension_value` string, nullable
      - `unit` string, required
      - `unit_price_nanodollars` integer, required
      - `unit_price_dollars` string, required: Decimal string
      - `included_per_organization` number, required
      - `included_per_seat` number, required
      - `hard_cap` number, nullable
    - `addons` BillingAddon[], required
      - `addon_key` string, required
      - `name` string, required
      - `monthly_price_cents` integer, required
      - `raises_meter_key` string, nullable, required
      - `raises_quantity` number, required
      - `raises_roder_concurrency` integer, required
      - `purchasable` boolean: Whether new purchases are available. Older API releases omit this field; absence preserves purchase availability.
      - `max_quantity` integer, nullable
  - `entitlements` BillingEntitlements, required
    - `state` 'none' | 'trialing' | 'active' | 'past_due' | 'suspended' | 'exempt', required
    - `seats` integer, required
    - `recurring_price_cents` integer, required
    - `roder_run_concurrency_limit` integer, required
    - `roder_daily_run_limit` integer, required
    - `seat_limit` integer, nullable
    - `seats_remaining` integer, nullable
    - `period_spend_cents` integer, required: Overage spend so far this period across every meter
    - `enforcing` boolean, required
    - `period_started_at` string, required
    - `usage_reset_at` string, date-time, nullable, required
    - `ci_raw_used` number, required: Full-period CI usage with the shared standard pool counted once.
    - `meters` BillingEntitlementMeter[], required
      - `meter_key` string, required
      - `dimension_value` string, nullable
      - `unit` string, required
      - `included` number, required
      - `used` number, required
      - `projected_overage_cents` integer, required: Forecast overage for the current allowance window.
      - `raw_used` number, required: Full billing-period usage before allowance resets.
      - `remaining` number, required
      - `spend_cents` integer, required: What this period's overage costs so far at the unit price. The standard CI runner classes split their shared pool's overage by each class's own minutes.
      - `hard_cap` number, nullable
      - `cap` number, nullable: The quantity past which new usage is refused; null means unlimited.
      - `pay_as_you_go` boolean, required
      - `unit_price_nanodollars` integer, required
  - `prepaid` BillingPrepaidAccount, required
    - `package_name` string, required
    - `monthly_price_cents` integer, required
    - `included_minutes` number, required
    - `subscription_status` string, required
    - `can_purchase` boolean, required
    - `refresh_recommended` boolean, required
    - `has_paid_period` boolean, required
    - `needs_payment_method` boolean, required
    - `can_cancel` boolean, required
    - `cancellation_pending` boolean, required
    - `cancel_at` string, date-time, nullable, required
    - `monthly_payment` BillingPrepaidPeriod, required
      - `id` string, required
      - `minutes` integer, required
      - `net_amount_cents` integer, required
      - `currency` string, required
      - `paid_total_cents` integer, nullable, required
      - `refunded_net_cents` integer, required
      - `state` 'requested' | 'submitting' | 'pending' | 'requires_action' | 'uncertain' | 'failed' | 'paid' | 'available' | 'under_review' | 'refunded' | 'partially_refunded', required
      - `last_error` string, nullable, required
      - `created_at` string, date-time, required
      - `paid_at` string, date-time, nullable, required
      - `activated_at` string, date-time, nullable, required
      - `receipt_url` string, nullable, required
      - `payment_action_url` string, nullable, required
      - `period_started_at` string, date-time, required
      - `period_ended_at` string, date-time, required
    - `next_renewal_at` string, date-time, nullable, required
    - `balance` BillingPrepaidBalance, required
      - `monthly_minutes` number, required
      - `purchased_minutes` number, required
      - `operator_minutes` number, required
      - `reserved_minutes` number, required
      - `available_minutes` number, required
      - `held_minutes` number, required
    - `top_up_options` object[], required
      - `minutes` 100 | 500 | 1000, required
      - `amount_cents` integer, required
      - `currency` string, required
    - `recent_purchases` BillingPrepaidPurchase[], required
      - `id` string, required
      - `minutes` integer, required
      - `net_amount_cents` integer, required
      - `currency` string, required
      - `paid_total_cents` integer, nullable, required
      - `refunded_net_cents` integer, required
      - `state` 'requested' | 'submitting' | 'pending' | 'requires_action' | 'uncertain' | 'failed' | 'paid' | 'available' | 'under_review' | 'refunded' | 'partially_refunded', required
      - `last_error` string, nullable, required
      - `created_at` string, date-time, required
      - `paid_at` string, date-time, nullable, required
      - `activated_at` string, date-time, nullable, required
      - `receipt_url` string, nullable, required
      - `payment_action_url` string, nullable, required
  - `storage_usage` BillingStorageUsage, required
    - `incomplete` boolean, required
    - `stored_bytes` integer, required
    - `provisioned_bytes` integer, required
    - `as_of` string, date-time, required
    - `categories` BillingStorageCategory[], required
      - `meter_key` string, required
      - `current_bytes` integer, required
      - `measurement` 'stored' | 'sampled' | 'provisioned', required
      - `sampled_at` string, date-time, nullable, required
      - `unmeasured_count` integer, required
      - `allowance` BillingEntitlementMeter, required
        - `meter_key` string, required
        - `dimension_value` string, nullable
        - `unit` string, required
        - `included` number, required
        - `used` number, required
        - `projected_overage_cents` integer, required: Forecast overage for the current allowance window.
        - `raw_used` number, required: Full billing-period usage before allowance resets.
        - `remaining` number, required
        - `spend_cents` integer, required: What this period's overage costs so far at the unit price. The standard CI runner classes split their shared pool's overage by each class's own minutes.
        - `hard_cap` number, nullable
        - `cap` number, nullable: The quantity past which new usage is refused; null means unlimited.
        - `pay_as_you_go` boolean, required
        - `unit_price_nanodollars` integer, required
  - `addons` BillingSubscriptionAddon[], required
    - `addon_key` string, required
    - `quantity` integer, required
    - `name` string, nullable
    - `monthly_price_cents` integer, nullable
  - `budget` BillingBudget, required
    - `monthly_cap_cents` integer, required
    - `notified_thresholds` integer[], required
  - `preview` object, nullable, required: Metronome draft invoice and credits, or null.
  - `breakdown` BillingUsageBreakdownSummary, required
    - `source` 'tinybird' | 'rollup', required
    - `as_of` string, required
    - `live` BillingUsageLiveBucket[], required
      - `meter_key` string, required
      - `dimension_value` string, required: Empty for meters without a dimension.
      - `unit` string, required
      - `quantity` number, required
      - `bucket_started_at` string, required: Start of the 5-minute bucket
  - `stripe` object, required
    - `configured` boolean, required
  - `feature_enabled` boolean, required: Whether the `billing` feature is on for this organization. False renders the page as not enabled, with no Subscribe action.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Unprocessable entity
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)