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

# Update a Subscription Plan

> Update a plan name, description, active status, or country availability. Amount and interval cannot be changed.

`PATCH /subscription/plan/{id}` updates the mutable fields on an existing plan. You can rename it, update its description, toggle its active status to stop accepting new subscribers, or adjust the countries where it is available — all without affecting existing subscribers.

<Note>
  `amount`, `interval`, `intervalCount`, and `currency` are immutable and cannot be changed via this endpoint. To change pricing or billing cadence, create a new plan using `POST /subscription/plan` and migrate subscribers using [change-plan](/api-reference/subscriptions/change-plan).
</Note>

Only include the fields you want to change — omitted fields are left unchanged (see the parameters panel above for the full list; `availableCountries` is a full replacement, not a merge).

Returns `200 OK` with the full updated plan object.

## Errors

| Code  | Meaning                                                                                          |
| ----- | ------------------------------------------------------------------------------------------------ |
| `404` | Plan not found.                                                                                  |
| `422` | Validation error — e.g. an unrecognized country code or an attempt to mutate an immutable field. |

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X PATCH https://api.therius.io/v1/subscription/plan/42 \
    -H "Authorization: Bearer prv_production_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "merchantCode": "MERCHANT_001",
      "name": "Pro Monthly (Revised)",
      "isActive": false
    }'
  ```
</RequestExample>


## OpenAPI

````yaml PATCH /subscription/plan/{id}
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /subscription/plan/{id}:
    patch:
      tags:
        - Plans
      summary: Update a subscription plan
      operationId: updatePlan
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - merchantCode
              properties:
                merchantCode:
                  type: string
                  description: Your merchant account identifier.
                name:
                  type: string
                  description: New plan name.
                description:
                  type: string
                  description: New description.
                isActive:
                  type: boolean
                  description: >-
                    Set `false` to stop the plan accepting new subscribers.
                    `amount` and `interval` cannot be changed - create a new
                    plan and use change-plan instead.
                availableCountries:
                  type: array
                  items:
                    type: string
                  description: >-
                    Replacement list of ISO 3166-1 alpha-2 codes. Send `[]` to
                    make the plan global.
      responses:
        '200':
          description: Updated plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
components:
  schemas:
    Plan:
      type: object
      description: >-
        A reusable billing plan. `amount` is a flat integer in the currency
        minor units (with separate `currency` + `exponent`) - not an Amount
        object.
      properties:
        id:
          type: integer
          description: The plan unique integer ID.
        merchantId:
          type: integer
          description: The merchant account that owns the plan.
        name:
          type: string
        description:
          type: string
        interval:
          type: string
          enum:
            - day
            - week
            - month
            - year
          description: Billing interval unit. Immutable after creation.
        intervalCount:
          type: integer
          description: >-
            Number of `interval` units between charges - `month` + `3` bills
            quarterly.
        amount:
          type: integer
          description: >-
            Recurring charge in the currency minor units (e.g. `2999` = $29.99
            at exponent 2). Immutable after creation.
        currency:
          type: string
          description: ISO 4217 currency code. Immutable after creation.
        exponent:
          type: integer
          description: >-
            Decimal places for `amount` / `introAmount` - `2` for USD, `0` for
            JPY.
        trialPeriodDays:
          type: integer
          description: Free-trial length in days before the first charge. `0` for no trial.
        introAmount:
          type: integer
          description: >-
            Introductory charge in minor units for the first
            `introBillingCycles` cycles, if set.
        introBillingCycles:
          type: integer
          description: >-
            How many initial cycles are billed at `introAmount` before the rate
            reverts to `amount`.
        maxBillingCycles:
          type: integer
          description: >-
            Total cycles after which the subscription auto-completes. `0` =
            open-ended.
        availableCountries:
          type: array
          items:
            type: string
          description: >-
            ISO 3166-1 alpha-2 codes the plan is offered in. Empty = available
            everywhere.
        isActive:
          type: boolean
          description: >-
            Whether the plan accepts new subscribers. Existing subscriptions are
            unaffected when this is `false`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````