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)

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).