---
title: "Create a plan"
method: POST
path: "/api/v1/plans"
tags: ["Plans"]
---

# Create a plan

`POST /api/v1/plans`

Create a new plan with components and pricing. Set `status` to `ACTIVE` to
publish immediately, or `DRAFT` to stage for review.

## Request body

- CreatePlanRequest
  - `add_ons` PlanAddOnInput[]
    - `add_on_id` string, MeteroidId, required
    - `max_instances` integer, nullable
    - `price_id` string, MeteroidId
    - `self_serviceable` boolean, nullable
  - `billing` BillingConfig
    - `billing_cycles` integer, nullable
    - `net_terms` integer
    - `period_start_day` integer, nullable
  - `components` PriceComponentInput[], required
    - `fee` union, required
      - 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
    - `name` string, required
    - `product_id` string, MeteroidId
  - `currency` string, required
  - `description` string, nullable
  - `name` string, required
  - `plan_type` 'STANDARD' | 'FREE' | 'CUSTOM', required
  - `product_family_id` string, MeteroidId, 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

## Response `201`

Plan created

- 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
- `409` — Conflict
- `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 `409`
  - 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 removed without deprecation

[Change history](https://skmtc.dev/meteroid-oss/apis/meteroid/changes/api/v1/plans/post.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)