---
title: "Create Plan"
method: POST
path: "/plans"
---

# Create Plan

`POST /plans`

Creates a reusable pricing plan. Plans are immutable once created — a price change means creating a new plan; existing subscriptions on the old plan are unaffected.

## Request body

- object
  - `name` string, required — The plan name (MAX 255; MIN 3).
  - `description` string — The plan description. No length limit is currently enforced.
  - `merchant_reference` string — Your own identifier for the plan. No length limit is currently enforced.
  - `base_amount` object, required — The default price used for any country without an explicit entry in `country_prices`.
    - `currency` string, required — MAX 3; MIN 3; [ISO 4217](/reference/country-reference).
    - `value` number, float, required — Multiple of 0.0001.
  - `frequency` object, required — The billing frequency for the plan. Subscriptions created from this plan inherit it.
    - `type` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required
    - `value` integer, required
  - `country_prices` object[] — Optional explicit per-country prices. A country not listed falls back to `base_amount`.
    - `country` string — [ISO 3166-1](/reference/country-reference).
    - `amount` object
      - `currency` string
      - `value` number, float
  - `allowed_payment_methods` string[] — Payment method types accepted for subscriptions on this plan.
  - `metadata` object[] — Key-value pairs attached to the plan. Independent of any `metadata` set on a subscription created from it.
    - `key` string — MAX 48.
    - `value` string — MAX 512.
  - `phases` object[] — Optional leading ladder (for example, a trial) before the plan's regular price. Omit for a flat plan. The last entry must be the terminal REGULAR phase with no `duration`.
    - `order` integer, required
    - `name` string, required — Required, non-empty — each phase must have a name.
    - `type` 'TRIAL' | 'REGULAR', required
    - `duration` object — Required on every non-terminal phase, omitted on the terminal REGULAR phase.
      - `type` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR'
      - `value` integer
    - `frequency` object — Optional. If omitted, the phase bills as a single lump-sum charge covering the whole `duration`. If set, the phase bills every `frequency` interval instead, and the server computes `total_payments = duration / frequency` (both in the same unit) — e.g. a 3-month duration with a 1-month frequency produces 3 charges. Not applicable to the terminal phase.
      - `type` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR'
      - `value` integer
    - `amount` object — Flat price for the phase. 0 is allowed (a free trial). On a **non-terminal** phase, this or `country_prices` is required (one of the two). On the **terminal** REGULAR phase, omit this entirely — sending it is rejected with `400 BAD_REQUEST` ("The terminal phase price comes from the plan base_amount/country_prices - remove the phase amount"); the terminal price always comes from the plan's own `base_amount`/`country_prices`.
      - `currency` string
      - `value` number, float
    - `country_prices` object[] — Per-country prices for this phase. On a non-terminal phase, this or `amount` is required. Not applicable to the terminal phase — its pricing always comes from the plan's own `country_prices`.
      - `country` string
      - `amount` object
        - `currency` string
        - `value` number, float

## Response `200`

200

- object
  - `id` string
  - `account_id` string
  - `name` string
  - `description` string
  - `merchant_reference` string
  - `status` string
  - `base_amount` object
    - `currency` string
    - `value` number
  - `frequency` object
    - `type` string
    - `value` integer
  - `country_prices` object[]
    - `country` string
    - `amount` object
      - `currency` string
      - `value` number
  - `allowed_payment_methods` string[]
  - `metadata` object[]
  - `phases` object[]
  - `created_at` string
  - `updated_at` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/y/apis/ai-caller.md) · [All operations](https://skmtc.net/y/apis/ai-caller/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/y/ai-caller/revisions/05b629819b49/schema)