---
title: "Update plan metadata"
method: PATCH
path: "/api/v1/plans/{plan_id}"
tags: ["Plans"]
---

# Update plan metadata

`PATCH /api/v1/plans/{plan_id}`

Partially update plan-level fields (name, description, self_service_rank).
Does not modify version-level configuration or components.

## Path parameters

- `plan_id` string, MeteroidId, required

## Request body

- PatchPlanRequest
  - `description` string, nullable
  - `name` string, nullable
  - `self_service_rank` integer, nullable

## Response `200`

Plan updated

- Plan
  - `available_parameters` AvailableParameters, required
    - `billing_periods` object — Map of component_id -> available billing periods (e.g., "MONTHLY", "ANNUAL")
    - `capacity_thresholds` object — Map of component_id -> available capacity values
    - `slot_components` string[] — List of component_ids that support slot parametrization (initial slot count)
  - `billing_cycles` integer, nullable
  - `created_at` string, date-time, required
  - `currency` string, required
  - `description` string, nullable
  - `id` string, MeteroidId, required
  - `name` string, required
  - `net_terms` integer, required
  - `period_start_day` integer, nullable
  - `plan_type` 'STANDARD' | 'FREE' | 'CUSTOM', required
  - `price_components` PriceComponent[], required
    - `fee` union
      - RatePlanFee — Recurring rate fee (e.g., monthly subscription)
        - `rates` TermRate[], required
          - `price` string, required
          - `term` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
      - SlotPlanFee — Slot-based fee (e.g., per-seat pricing)
        - `minimum_count` integer, nullable
        - `quota` integer, nullable
        - `rates` TermRate[], required
          - `price` string, required
          - `term` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
        - `slot_unit_name` string, required
      - CapacityPlanFee — Capacity-based fee with included committed usage and overage
        - `cadence` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
        - `metric_id` string, MeteroidId, required
        - `thresholds` CapacityThreshold[], required
          - `included_amount` integer, required
          - `per_unit_overage` string, required
          - `price` string, required
      - UsagePlanFee — Usage-based fee
        - `cadence` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
        - `metric_id` string, MeteroidId, required
        - `pricing` union, required
          - PerUnitPlanPricing
            - `rate` string, required
          - TieredPlanPricing
            - `block_size` integer, nullable
            - `tiers` TierRow[], required
              - …
          - VolumePlanPricing
            - `block_size` integer, nullable
            - `tiers` TierRow[], required
              - …
          - PackagePlanPricing
            - `block_size` integer, required
            - `rate` string, required
          - MatrixPlanPricing
            - `rates` MatrixRow[], required
              - …
      - ExtraRecurringPlanFee — Extra recurring fee
        - `billing_type` 'ADVANCE' | 'ARREARS', required
        - `cadence` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
        - `quantity` integer, required
        - `unit_price` string, required
      - OneTimePlanFee — One-time fee
        - `quantity` integer, required
        - `unit_price` string, required
    - `id` string, MeteroidId, required
    - `name` string, required
    - `product_id` string, MeteroidId
  - `product_family` ProductFamily, required
    - `id` string, MeteroidId, required
    - `name` string, required
  - `self_service_rank` integer, nullable
  - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'ARCHIVED', required
  - `trial` TrialConfig
    - `duration_days` integer, required
    - `is_free` boolean, required
    - `trialing_plan_id` string, MeteroidId
  - `version` integer, required
  - `version_id` string, MeteroidId, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Plan not found
- `429` — Too many requests

## Changes

- **2026-03-27** (v1) `de35c02bb0d2` — 3 warning, 1 info
  - added the new `TOO_MANY_REQUESTS` enum value to the `code` response property for the response status `400`
  - added the new `TOO_MANY_REQUESTS` enum value to the `code` response property for the response status `401`
  - added the new `TOO_MANY_REQUESTS` enum value to the `code` response property for the response status `404`
  - added the non-success response with the status `429`
- **2026-03-20** (v1) `51c7018cc5ef` — 1 info
  - endpoint added
- **2025-07-09** (v1) `dece17f86f99` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/meteroid-oss/apis/meteroid/changes/api/v1/plans/:plan_id/patch.md)

---

[API](https://skmtc.dev/meteroid-oss/apis/meteroid.md) · [All operations](https://skmtc.dev/meteroid-oss/apis/meteroid/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meteroid-oss/meteroid/revisions/de35c02bb0d2/schema)