--- title: "List subscriptions" method: GET path: "/v1/subscriptions" tags: ["Subscriptions"] --- # List subscriptions `GET /v1/subscriptions` ## Request - Base URL: `https://api.subscriby.net` - URL: `https://api.subscriby.net/v1/subscriptions` - Auth: HTTP bearer ```bash curl "https://api.subscriby.net/v1/subscriptions?status=active" \ -H "Authorization: Bearer $SUBSCRIBY_TOKEN" ``` The held subscriptions across every project the token reaches, newest first, paged with `page` and `per_page` (default 25; `limit` is accepted as an alias). `status` matches a single payment status and `plan_id` scopes to one plan. Rows carry no `grants`. A token minted with `scope:project:` entries lists only the subscriptions of those projects, and a subscription of any other project is `404 RESOURCE_NOT_FOUND` on every endpoint of this resource. ## Query parameters - `status` 'trialing' | 'active' | 'incomplete' | 'expired' | 'past_due' | 'canceled' | 'unpaid' | 'paused' | 'processing' | 'succeeded' | 'capturable' | 'failed' | 'pending' - `plan_id` string, uuid, nullable - `page` integer - `per_page` integer - `sort_by` string - `sort_direction` 'asc' | 'desc' - `limit` integer ## Response `200` The page of held subscriptions, newest first. - object - `data` SubscriptionResource[], required: The items on this page. - `id` string, required: The subscription's id. - `plan_id` string, required: The plan that was bought. - `subscriber_id` string, nullable, required: The member who holds it. - `method_id` string, required: The payment method it was bought through; null for an access code. - `payment_status` union, required: Where the purchase stands: `trialing`, `active`, `incomplete`, `expired`, `past_due`, `canceled`, `unpaid`, `paused`, `processing`, `succeeded`, `capturable` or `failed`. - string - 'trialing' | 'active' | 'incomplete' | 'expired' | 'past_due' | 'canceled' | 'unpaid' | 'paused' | 'processing' | 'succeeded' | 'capturable' | 'failed' | 'pending' - `payment_price` string, required: What the member pays per period, as a decimal string in the plan's currency. - `currency_id` string, required: The currency the price is in. - `trial_ends_at` string, nullable, required: When the trial ends, ISO 8601; null without a trial. - `ends_at` string, nullable, required: When the current access ends, ISO 8601, `compensation_seconds` already included: a one-time purchase simply ends later, while a recurring plan's `ends_at` runs that many seconds past the period the member last paid for. Null while open-ended. - `canceled` boolean, required: Whether a cancellation is scheduled or done; the access runs to `ends_at`. - `compensation_seconds` integer, required: The outage time Outage Compensation has banked on the purchase, 0 for almost every subscription; the renewal the gateway bills is `ends_at` minus this. - `redeemed_at` string, nullable, required: When an access code was redeemed, ISO 8601; null for a paid purchase or an unredeemed code. - `created_at` string, nullable, required: When the purchase was made, ISO 8601. - `updated_at` string, nullable, required: When the row last changed, ISO 8601. - `source` unknown[], nullable: Where the subscriber came from: the Smart Link credited with them, the door and the campaign tags, read from the member. Null for a member who arrived with no link and no tags; present on a single read and on a list. - unknown - `grants` AccessGrantResource[]: The access ledger rows, one per resource and dated window; embedded on the detail read only, never on the list. - `id` string, required: The grant's id. - `subscription_id` string, required: The purchase the grant belongs to. - `resource_id` string, required: The resource the grant admits the holder to. - `window_id` string, nullable, required: The dated pass window the grant is for; null for continuous access. - `identity_id` string, nullable, required: The connector account admitted, the same id the member's identities endpoint returns; null while none is linked or for a hand-arranged perk. - `connector` string, nullable, required: The connector that gave the access, by key; null for a manual perk. - `mode` string, required: How the access is given: `bearer_link` (a personal invite link the member comes through), `membership` (the connector added the member itself), `role` (a role was assigned) or `creator_task` (the creator has to do something by hand). - `state` string, required: `pending_identity` (the member has not linked an account on that connector yet; issued the moment they connect one), `pending` (issued, not yet used), `held` (issued ahead of a pass window and released when it opens), `granted`, `revoked` or `failed`. - `reference` string, nullable, required: The connector's handle on the grant (the invite link on a connector that grants by link); null before anything was issued. Treat it as a secret: whoever holds a bearer link can use it. - `granted_at` string, nullable, required: When the access was granted, ISO 8601; null until then. - `revoked_at` string, nullable, required: When the access was revoked, ISO 8601; null while standing. - `failure_kind` string, nullable, required: Why a `failed` grant failed: `unreachable`, `not_permitted`, `target_missing`, `rate_limited`, `configuration`, `transient` or `other`; null otherwise. - `failure_detail` string, nullable, required: The sentence the creator sees in the dashboard for a failed grant; null otherwise. - `created_at` string, nullable, required: When the ledger row was written, ISO 8601. - `links` object, required: Links to the first, last, previous and next pages. - `first` string, nullable, required: The first page's URL. - `last` string, nullable, required: The last page's URL. - `prev` string, nullable, required: The previous page's URL; null on the first page. - `next` string, nullable, required: The next page's URL; null on the last page. - `meta` object, required: The paging counters for this page. - `current_page` integer, required: The page returned, 1-indexed. - `from` integer, nullable, required: The 1-indexed position of this page's first item across every page; null when the page is empty. - `last_page` integer, required: How many pages there are. - `links` object[], required: Generated paginator links. - `url` string, nullable, required: The page's URL; null for the ellipsis and the disabled arrows. - `label` string, required: The link's label: a page number, the previous or next arrow, or an ellipsis. - `active` boolean, required: Whether this link is the current page. - `path` string, nullable, required: Base path for paginator generated URLs. - `per_page` integer, required: Number of items shown per page. - `to` integer, nullable, required: Number of the last item in the slice. - `total` integer, required: Total number of items being paginated. ## Other responses - `401`: `AUTHENTICATION_REQUIRED`: the request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an `sbt_test_` token on production). - `403`: `TOKEN_MISSING_ABILITY`: the token is valid but does not carry the ability this endpoint requires; `error.context.required_ability` names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers `FORBIDDEN`, `TEAM_TIER_REQUIRED` or `CONNECTOR_TIER_REQUIRED` with the same status, and says so in its own description. - `422`: `VALIDATION_FAILED`: the payload broke a rule, and `error.fields` maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with `error.message` saying why and no `fields`. On this endpoint: `VALIDATION_FAILED`: when `status` is not a payment status or `plan_id` is not a UUID. - `429`: `RATE_LIMITED`: the token has spent its 300 requests a minute or 10,000 an hour; `Retry-After` says when the next one is accepted. --- [API](https://skmtc.dev/memberpass/apis/subscriby-rest-api.md) · [All operations](https://skmtc.dev/memberpass/apis/subscriby-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/memberpass/apis/subscriby-rest-api/revisions/59c4df91d764?raw)