> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Change the billing plan



## OpenAPI

````yaml /api-reference/openapi.personal.json put /v1/orgs/{slug}/billing/plan
openapi: 3.1.0
info:
  title: Personal token API
  description: User-scoped API for account and organization management.
  version: 0.1.0
servers:
  - url: https://api.microsandbox.dev
security:
  - bearer: []
paths:
  /v1/orgs/{slug}/billing/plan:
    put:
      tags:
        - Billing
      summary: Change the billing plan
      operationId: change_plan
      parameters:
        - name: slug
          in: path
          description: Organization slug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePlanRequest'
        required: true
      responses:
        '200':
          description: Plan changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummaryResponse'
        '400':
          description: Invalid plan or payment method required
        '401':
          description: Unauthorized
        '403':
          description: Insufficient permissions
      security:
        - bearer: []
components:
  schemas:
    ChangePlanRequest:
      type: object
      description: PUT /v1/orgs/:slug/billing/plan - change billing plan.
      required:
        - plan
      properties:
        plan:
          type: string
          description: Catalog name of the plan to switch to (e.g. "builder").
    BillingSummaryResponse:
      type: object
      description: Billing summary response for an organization.
      required:
        - plan
        - effective_pricing
        - effective_state
        - is_suspended
      properties:
        available_credit_cents:
          type:
            - integer
            - 'null'
          format: int64
          description: >-
            Positive USD credit Stripe will apply automatically to future
            invoices.
          minimum: 0
        billing_terms_override:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BillingTermsOverrideSummary'
              description: >-
                Current agreement metadata, including setup and payment-pending
                states.
        checkout_url:
          type:
            - string
            - 'null'
          description: >-
            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:
          type:
            - string
            - 'null'
          format: date-time
        effective_pricing:
          $ref: '#/components/schemas/BillingPricingTerms'
          description: >-
            Effective commercial terms after applying any org-specific
            agreement.
        effective_state:
          $ref: '#/components/schemas/BillingEffectiveState'
        is_suspended:
          type: boolean
        pending_plan:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BillingPlanSummary'
              description: >-
                Plan the org will switch to at `current_period_ends_at`, if a
                downgrade is scheduled.
        plan:
          $ref: '#/components/schemas/BillingPlanSummary'
    BillingTermsOverrideSummary:
      type: object
      description: Effective window for the org's active negotiated billing terms.
      required:
        - status
        - plan
        - effective_from
      properties:
        effective_from:
          type: string
          format: date-time
        effective_until:
          type:
            - string
            - 'null'
          format: date-time
        plan:
          $ref: '#/components/schemas/BillingPlanSummary'
        post_expiry_plan:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BillingPlanSummary'
              description: >-
                Explicit plan assigned at expiry; absent means target-plan
                retail pricing.
        status:
          $ref: '#/components/schemas/OrgBillingTermsOverrideStatus'
    BillingPricingTerms:
      type: object
      description: >-
        Pricing fields which may be inherited from a plan or negotiated per
        customer.
      properties:
        included_disk_gib_hours:
          type:
            - integer
            - 'null'
          format: int32
        included_memory_gib_hours:
          type:
            - integer
            - 'null'
          format: int32
        included_storage_gib:
          type:
            - integer
            - 'null'
          format: int32
        included_vcpu_hours:
          type:
            - integer
            - 'null'
          format: int32
        subscription_price_cents:
          type:
            - integer
            - 'null'
          format: int64
        usage_disk_gib_hour_usd:
          type:
            - number
            - 'null'
          format: double
        usage_memory_gib_hour_usd:
          type:
            - number
            - 'null'
          format: double
        usage_snapshot_storage_gib_month_usd:
          type:
            - number
            - 'null'
          format: double
        usage_storage_gib_month_usd:
          type:
            - number
            - 'null'
          format: double
        usage_vcpu_hour_usd:
          type:
            - number
            - 'null'
          format: double
    BillingEffectiveState:
      type: string
      description: Effective billing state derived from plan, period end, and suspension.
      enum:
        - free
        - active
        - past_due
        - suspended
    BillingPlanSummary:
      type: object
      description: Summary of a billing plan (subset of full plan).
      required:
        - name
        - display_name
        - has_custom_billing_terms
      properties:
        display_name:
          type: string
        has_custom_billing_terms:
          type: boolean
        name:
          type: string
    OrgBillingTermsOverrideStatus:
      type: string
      description: Operational state of one immutable negotiated-pricing version.
      enum:
        - applying
        - pending_payment
        - scheduled
        - active
        - failed
        - expired
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        Personal access token (msb_pat_…) or session JWT - the credential an
        agent acts with on a user's behalf.

````