Plans
A plan is the schedule + price recipe a subscription charges against: an amount, a currency, an interval (monthly, yearly, weekly, daily), a label, and (optionally) a stack of multi-tier prices. Plans are the durable definition; subscriptions reference them by ID.
All endpoints require an sk_* key.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST |
/v1/payment/plans |
Create a plan |
GET |
/v1/payment/plans |
List plans |
GET |
/v1/payment/plans/:id |
Retrieve a plan |
PATCH |
/v1/payment/plans/:id |
Update a plan |
DELETE |
/v1/payment/plans/:id |
Archive a plan |
POST |
/v1/payment/plans/:id/prices |
Add a price tier |
PATCH |
/v1/payment/plans/prices/:priceId |
Update a price tier |
Create
POST /v1/payment/plans
Idempotency-Key supported. Tier-limited — some plans cap the count of billing plans you can create.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name |
string (1–100) | yes | Internal label (Pro Monthly, Enterprise Annual). |
description |
string | no | Internal note. |
amount |
integer | yes | Smallest-unit price per interval. |
currency |
string (3) | yes | ISO 4217. |
interval |
daily | weekly | monthly | yearly |
yes | Billing cadence. |
intervalCount |
integer | no | Multiplier — interval: monthly, intervalCount: 3 = quarterly. Default 1. |
trialDays |
integer | no | Default trial offered on new subscriptions to this plan. Overridable per-subscription. |
active |
boolean | no | Defaults true. false plans can't accept new subscriptions but existing ones keep running. |
metadata |
object | no | Free-form. |
Response — 201 Created. Returns the plan object.
Retrieve / list / update / archive
Standard CRUD. DELETE is a soft-archive (sets active: false and excludes from GET /plans by default).
Multi-tier prices
For plans with multiple price points (e.g. monthly vs annual, or volume tiers), use:
POST /v1/payment/plans/:id/prices
| Field | Type | Description |
|---|---|---|
amount |
integer | Smallest-unit. |
currency |
string (3) | ISO 4217. |
interval |
string | Cadence override. |
nickname |
string | Display label (Monthly, Annual). |
active |
boolean | If false, hidden from new-subscription pickers. |
To update an existing price tier:
PATCH /v1/payment/plans/prices/:priceId
Updatable fields: nickname, active. Amount and currency are immutable — create a new price to change them and archive the old one.
The plan object
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string | no | plan_ + ULID. |
accountId |
string | no | Workspace. |
name |
string | no | Internal label. |
description |
string | yes | Internal note. |
amount |
integer | no | Default smallest-unit price. |
currency |
string | no | ISO 4217. |
interval |
enum | no | Cadence. |
intervalCount |
integer | no | Multiplier. |
trialDays |
integer | yes | Default trial. |
active |
boolean | no | Accepts new subscriptions. |
prices |
array | no | Tier records (id, amount, currency, interval, nickname, active). |
metadata |
object | no | Free-form. |
createdAt / updatedAt |
string | no | Timestamps. |
Events
| Event type | Fires on | Notes |
|---|---|---|
| (none today) | — | Plan lifecycle isn't currently mirrored to the outbox. |
plan.created,plan.updated,plan.archivedare reserved but not emitted. They appear in Plugipay's event catalogue but Storlaunch doesn't re-fire them. If you need plan-mutation push events, subscribe on the Plugipay side directly once the workspace has the module on.
Next
- Subscriptions — the running billing instance tied to a plan.
- Customers — who's subscribed.
- Invoices — per-cycle artifacts of subscription charges.