---
title: "PUT /v1/orgs/:slug/billing/plan — change billing plan (Admin+)."
method: PUT
path: "/v1/orgs/{slug}/billing/plan"
tags: ["billing"]
---

# PUT /v1/orgs/:slug/billing/plan — change billing plan (Admin+).

`PUT /v1/orgs/{slug}/billing/plan`

## Path parameters

- `slug` string, required

## Request body

- ChangePlanRequest — PUT /v1/orgs/:slug/billing/plan — change billing plan.
  - `plan` string, required — Catalog name of the plan to switch to (e.g. "builder").

## Response `200`

Plan changed

- BillingSummaryResponse — Billing summary response for an organization.
  - `available_credit_cents` integer, nullable — Positive USD credit Stripe will apply automatically to future invoices.
  - `billing_terms_override` BillingTermsOverrideSummary — Effective window for the org's active negotiated billing terms.
    - `effective_from` string, date-time, required
    - `effective_until` string, date-time, nullable
    - `plan` BillingPlanSummary, required — Summary of a billing plan (subset of full plan).
      - `display_name` string, required
      - `has_custom_billing_terms` boolean, required
      - `name` string, required
    - `post_expiry_plan` BillingPlanSummary — Summary of a billing plan (subset of full plan).
      - `display_name` string, required
      - `has_custom_billing_terms` boolean, required
      - `name` string, required
    - `status` 'applying' | 'pending_payment' | 'scheduled' | 'active' | 'failed' | 'expired', required — Operational state of one immutable negotiated-pricing version.
  - `checkout_url` string, nullable — Hosted-checkout URL to complete payment for a just-changed plan (Autumn). Set only on a plan change that needs payment; the client redirects to it.
  - `current_period_ends_at` string, date-time, nullable
  - `effective_pricing` BillingPricingTerms, required — Pricing fields which may be inherited from a plan or negotiated per customer.
    - `included_disk_gib_hours` integer, nullable
    - `included_memory_gib_hours` integer, nullable
    - `included_storage_gib` integer, nullable
    - `included_vcpu_hours` integer, nullable
    - `subscription_price_cents` integer, nullable
    - `usage_disk_gib_hour_usd` number, double, nullable
    - `usage_memory_gib_hour_usd` number, double, nullable
    - `usage_storage_gib_month_usd` number, double, nullable
    - `usage_vcpu_hour_usd` number, double, nullable
  - `effective_state` 'free' | 'active' | 'past_due' | 'suspended', required — Effective billing state derived from plan, period end, and suspension.
  - `is_suspended` boolean, required
  - `pending_plan` BillingPlanSummary — Summary of a billing plan (subset of full plan).
    - `display_name` string, required
    - `has_custom_billing_terms` boolean, required
    - `name` string, required
  - `plan` BillingPlanSummary, required — Summary of a billing plan (subset of full plan).
    - `display_name` string, required
    - `has_custom_billing_terms` boolean, required
    - `name` string, required

## Other responses

- `400` — Invalid plan or payment method required
- `401` — Unauthorized
- `403` — Insufficient permissions

---

[API](https://skmtc.dev/microsandbox/apis/microsandbox-api.md) · [All operations](https://skmtc.dev/microsandbox/apis/microsandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/microsandbox/microsandbox-api/revisions/23f2a45cb09b/schema)