Plans API¶

Base: /api/organizations/{organization_id}/plans

Create plan¶

POST /api/organizations/{organization_id}/plans

{
  "key": "pro",
  "name": "Pro",
  "kind": "catalog",
  "grants": [
    { "feature": "sso", "kind": "flag" },
    { "feature": "csv_export", "kind": "flag" },
    { "feature": "seats", "kind": "limit", "limit": 10 },
    { "feature": "storage_gb", "kind": "limit", "limit": null }
  ]
}

Field	Required	Rules
`name`	yes	1–255
`kind`	yes	`catalog` \| `custom`
`key`	no	unique per org if set; typical for catalog; lowercase letters, numbers, underscores, dashes
`grants`	no	array of grants; default `[]`

Grant object¶

Feature kind	Body
`flag`	`{ "feature": "<key>", "kind": "flag" }`
`limit`	`{ "feature": "<key>", "kind": "limit", "limit": <int≥0 \\| null> }`

limit: null = unlimited. Grant kind must match the catalog feature’s kind. Duplicate feature keys in one request → 422.

201 — plan object

422 — unknown feature key, kind mismatch, or invalid grant

List plans¶

GET /api/organizations/{organization_id}/plans

Query (optional):

Param	Description
`kind`	`catalog` or `custom`

200 { "plans": [ … ] }

Get plan¶

GET /api/organizations/{organization_id}/plans/{plan_id}

200 — plan

{
  "id": "01H…",
  "key": "pro",
  "name": "Pro",
  "kind": "catalog",
  "grants": [
    { "feature": "csv_export", "kind": "flag" },
    { "feature": "seats", "kind": "limit", "limit": 10 },
    { "feature": "sso", "kind": "flag" }
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

Update plan¶

PATCH /api/organizations/{organization_id}/plans/{plan_id}

{
  "name": "Pro (2026)",
  "grants": [
    { "feature": "sso", "kind": "flag" },
    { "feature": "seats", "kind": "limit", "limit": 25 }
  ]
}

Field	Notes
`name`	optional
`grants`	optional; replaces full grant list when present
`key` / `kind`	immutable after create

200 — plan

Warning

Changing grants immediately affects entitlement resolution for all active subscribers on this plan.

Delete plan¶

DELETE /api/organizations/{organization_id}/plans/{plan_id}

204 — deleted

409 — active subscriptions reference this plan