Subscriptions API

Base: /org/subscribers/{subscriber_id}/subscriptions

subscriber_id is the id you chose for the subscriber. plan_id is the plan’s key.

Create subscription

Assigns a plan to the subscriber.

POST /org/subscribers/{subscriber_id}/subscriptions

{
  "plan_id": "pro"
}

Field	Required	Rules
plan_id	yes	Plan key in this org

201 — subscription with status: "active"

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

409 PLAN_ARCHIVED — plan is archived. Message: Plan {key} is archived; unarchive it or pick another plan.

404 — subscriber or plan not found

List subscriptions

GET /org/subscribers/{subscriber_id}/subscriptions

Includes active and canceled. Cursor + limit. See Lists. Oldest id first.

200

{
  "subscriptions": [ … ],
  "has_more": false
}

When has_more is true, pass the last subscription’s id as starting_after.

Get subscription

GET /org/subscribers/{subscriber_id}/subscriptions/{subscription_id}

200

{
  "id": "01H…",
  "subscriber_id": "cust_123",
  "plan_id": "pro",
  "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 /org/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 /org/subscribers/{subscriber_id}/subscriptions/change

{
  "plan_id": "enterprise"
}

200 — when an active subscription existed:

{
  "canceled": {
    "id": "01H…",
    "subscriber_id": "cust_123",
    "plan_id": "pro",
    "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": "cust_123",
    "plan_id": "enterprise",
    "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).

409 PLAN_ARCHIVED — target plan is archived. Message: Plan {key} is archived; unarchive it or pick another plan. The current subscription is left as it is.

Changing to the plan the subscriber is already on is not an error, unless that plan is archived: it still ends the current subscription and starts a new one.