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

# Create a subscription plan

`POST /api/v3/subscriptions/plans`

Create a plan your subscribers can subscribe to.

## Request body

- CreatePlanRequest — A `FIXED` plan carries a `price` (every subscription bills it) and must omit `asset`. A `VARIABLE` plan carries only an `asset` — the amount is supplied per subscription at creation — and must omit `price`.
  - `name` string, required
  - `type` 'FIXED' | 'VARIABLE', required — How a plan's billed amount is determined. `FIXED` — the plan carries a fixed `price`; every subscription bills it. `VARIABLE` — the plan carries only an `asset`; the amount is set per subscription at creation.
  - `price` Price — Monetary amount. `amount` is a decimal string. `asset` is an ISO 4217 code for fiat or an uppercase stablecoin symbol — e.g. `USD`, `EUR`, `USDC`, `USDT`.
    - `amount` string, required
    - `asset` string, required
  - `asset` string — Billing asset for a `VARIABLE` plan (the amount is supplied per subscription). Required when `type` is `VARIABLE`; ignored for `FIXED` (asset is taken from `price.asset`).
  - `billingInterval` 'MONTHLY' | 'ANNUAL', required — How often the subscription is billed.
  - `termCycles` integer, nullable — Number of billing cycles before the subscription term ends. Unit follows `billingInterval`. Null or omitted means the subscription renews indefinitely.
  - `gracePeriod` string, required — ISO-8601 calendar period. Examples: `P7D` (7 days), `P1M` (1 month), `P1Y` (1 year). Sub-day precision is not supported.

## Response `201`

Plan created.

- Plan
  - `id` string, uuid, required
  - `name` string, required
  - `type` 'FIXED' | 'VARIABLE', required — How a plan's billed amount is determined. `FIXED` — the plan carries a fixed `price`; every subscription bills it. `VARIABLE` — the plan carries only an `asset`; the amount is set per subscription at creation.
  - `asset` string, required — The plan's billing asset. Always present (equals `price.asset` for `FIXED` plans).
  - `price` Price — Monetary amount. `amount` is a decimal string. `asset` is an ISO 4217 code for fiat or an uppercase stablecoin symbol — e.g. `USD`, `EUR`, `USDC`, `USDT`.
    - `amount` string, required
    - `asset` string, required
  - `billingInterval` 'MONTHLY' | 'ANNUAL', required — How often the subscription is billed.
  - `termCycles` integer, nullable — Number of billing cycles in the plan's term; null means it renews indefinitely.
  - `gracePeriod` string, required — ISO-8601 calendar period. Examples: `P7D` (7 days), `P1M` (1 month), `P1Y` (1 year). Sub-day precision is not supported.
  - `status` 'ACTIVE' | 'ARCHIVED', required — `ACTIVE` — open for new subscriptions. `ARCHIVED` — closed to new subscriptions; existing subscriptions keep billing.
  - `createdAt` integer, required — Unix epoch seconds.
  - `updatedAt` integer, required — Unix epoch seconds.

## Other responses

- `400` — Request is malformed or violates a validation rule.
- `401` — Caller is unauthenticated.
- `403` — Caller is authenticated but not authorized for this resource.
- `422` — Request parsed but violates a business rule or invariant.
- `500` — Unexpected server error.

---

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