---
title: "Change the current subscription plan"
method: PATCH
path: "/subscription/change_plan"
tags: ["billingSubscriptions"]
---

# Change the current subscription plan

`PATCH /subscription/change_plan`

Changes a self-serve subscription to another active plan with proration. Optional product quantities are absolute quantities on the destination plan.

## Headers

- `Authorization` string, required

## Request body

- BillingChangePlanRequest
  - `plan_slug` string, required
  - `product_quantities` object — Optional map of product slugs to desired quantities on the new plan.

## Response `200`

Subscription on the new plan.

- BillingSubscriptionResponse
  - `subscription` BillingSubscription, required
    - `id` integer
    - `plan` BillingPlan
      - `id` integer
      - `name` string
      - `slug` string — Stable plan identifier used when creating or changing a subscription.
      - `plan_type` 'self_serve' | 'custom' | 'default'
      - `base_fee_cents` integer
      - `base_fee_dollars` number, double
      - `total_base_cost_cents` integer
      - `total_base_cost_dollars` number, double
      - `included_dollar_balance_cents` integer
      - `included_dollar_balance_dollars` number, double
      - `billing_interval` 'monthly' | 'quarterly' | 'annual'
      - `plan_family` BillingPlanFamily
        - `key` string
        - `name` string
        - `description` string, nullable
        - `position` integer, nullable
      - `active` boolean
      - `products` BillingPlanProduct[]
        - `id` integer
        - `name` string
        - `slug` string — Stable product identifier used in product_quantities and changes requests.
        - `description` string, nullable
        - `unit_type` string
        - `category` 'metered' | 'subscription' | 'base_fee' | 'included_credits'
        - `rate_per_unit_cents` integer
        - `rate_per_unit_dollars` number, double
        - `has_tiers` boolean
        - `tiers` BillingProductRateTier[]
          - `tier_order` integer
          - `min_quantity` number, double
          - `max_quantity` number, double, nullable
          - `rate_per_unit_cents` integer
          - `rate_per_unit_dollars` number, double
        - `included_quantity` number, double, nullable
        - `allow_additional_usage` boolean — Whether the plan permits the product quantity to be changed.
        - `min_usage_per_period` number, double, nullable — Minimum allowed quantity for this product on the plan.
        - `max_usage_per_period` number, double, nullable — Maximum allowed quantity for this product on the plan. Null means no plan-specific maximum.
        - `ui_visible` boolean — Whether the product is displayed in Resemble billing interfaces.
        - `product_family` BillingProductFamily
          - `key` string
          - `name` string
          - `description` string, nullable
          - `position` integer, nullable
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `status` 'pending_payment' | 'active_pending_payment' | 'active' | 'trialing' | 'cancelled' | 'expired' | 'past_due' | 'delinquent'
    - `current_period_start` string, date-time
    - `current_period_end` string, date-time
    - `cancel_at_period_end` boolean
    - `cancel_at` string, date-time, nullable
    - `activated_at` string, date-time, nullable
    - `invoice_due_date` string, date, nullable
    - `delinquent_at` string, date-time, nullable
    - `subscription_items` BillingSubscriptionItem[]
      - `id` integer
      - `quantity` number, double — Current absolute quantity on the subscription.
      - `consumed_quantity` number, double — Quantity currently in use. A product cannot be reduced below this value.
      - `product` BillingSubscriptionProduct
        - `id` integer
        - `name` string
        - `slug` string — Product identifier to send as product_slug when updating quantities.
        - `unit_type` string
        - `category` 'metered' | 'subscription' | 'base_fee' | 'included_credits'
        - `description` string, nullable
        - `active` boolean
        - `min_purchase_quantity` number, double, nullable
        - `max_purchase_quantity` number, double, nullable
      - `plan_product` BillingSubscriptionPlanProduct — Quantity rules inherited from the subscription's current plan.
        - `included_quantity` number, double, nullable
        - `allow_additional_usage` boolean
        - `min_usage_per_period` number, double, nullable
        - `max_usage_per_period` number, double, nullable
      - `rate_per_unit_cents` number, double — Locked-in unit rate for this subscription item.
      - `current_rate_per_unit_cents` number, double — Current catalog unit rate for comparison.
      - `is_grandfathered` boolean
      - `rate_locked_at` string, date-time, nullable
      - `ui_visible` boolean
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400` — The request could not be parsed or contains invalid parameters.
- `401` — A valid API key was not provided.
- `402` — Additional customer authentication is required before the billing change can complete.
- `403` — The API key owner cannot manage billing, or the Billing API is unavailable for the customer's billing arrangement.
- `404` — The requested billing resource does not exist for the current team.
- `422` — The request was understood but violates a billing rule.
- `500` — An unexpected billing error occurred.

---

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