Subscriptions API

Base: /api/organizations/{organization_id}/subscribers/{subscriber_id}/subscriptions

Create subscription

Assigns a plan to the subscriber.

POST /api/organizations/{organization_id}/subscribers/{subscriber_id}/subscriptions

{
  "plan_id": "01H…"
}

Field	Required	Rules
plan_id	yes	Must exist in org

201 — subscription with status: "active"

409 — subscriber already has an active subscription (cancel or change first)

404 — subscriber or plan not found

List subscriptions

GET /api/organizations/{organization_id}/subscribers/{subscriber_id}/subscriptions

Includes active and canceled (history grows over time).

200 { "subscriptions": [ … ] }

Get subscription

GET /api/organizations/{organization_id}/subscribers/{subscriber_id}/subscriptions/{subscription_id}

200

{
  "id": "01H…",
  "subscriber_id": "01H…",
  "plan_id": "01H…",
  "status": "active",
  "started_at": "2026-01-15T12:00:00.000Z",
  "ended_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

Cancel subscription

POST /api/organizations/{organization_id}/subscribers/{subscriber_id}/subscriptions/{subscription_id}/cancel

200 — subscription with status: "canceled", ended_at set

409 — already canceled

Change plan

Moves the subscriber to a different plan in one request (ends the current active subscription, starts a new one).

POST /api/organizations/{organization_id}/subscribers/{subscriber_id}/subscriptions/change

{
  "plan_id": "01H…"
}

200 — when an active subscription existed:

{
  "canceled": {
    "id": "01H…",
    "subscriber_id": "01H…",
    "plan_id": "01H…",
    "status": "canceled",
    "started_at": "2026-01-15T12:00:00.000Z",
    "ended_at": "2026-03-01T09:00:00.000Z",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-03-01T09:00:00.000Z"
  },
  "active": {
    "id": "01J…",
    "subscriber_id": "01H…",
    "plan_id": "01J…",
    "status": "active",
    "started_at": "2026-03-01T09:00:00.000Z",
    "ended_at": null,
    "created_at": "2026-03-01T09:00:00.000Z",
    "updated_at": "2026-03-01T09:00:00.000Z"
  }
}

404 — subscriber not found, plan not found, or subscriber has no active subscription (create a subscription first).