List subscriptions
/v1/subscriptions in the Subscriptions API.
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:<uuid> 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.
Requires ability
The token must hold this ability, or the call is refused with 403.
Authorization
bearerToken A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.
In: header
Query Parameters
Match a single payment status: trialing, active, incomplete, expired, past_due, canceled, unpaid, paused, processing, succeeded, capturable or failed. An unknown value is refused.
Scope to one plan.
uuidThe 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.
1 <= value1Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 25.
1 <= value <= 10025The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.
"created_at"asc or desc. Defaults to desc.
"desc"Value in
- "asc"
- "desc"
Legacy alias of per_page, kept for clients that predate it. per_page wins when both are sent.
1 <= value <= 100Responses
200OKapplication/json
The page of held subscriptions, newest first.
401UnauthorizedAUTHENTICATION_REQUIREDapplication/json
The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).
403ForbiddenTOKEN_MISSING_ABILITYapplication/json
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.
422Validation failedVALIDATION_FAILEDapplication/json
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.
429Too many requestsRATE_LIMITEDapplication/json
The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.
How is this guide?
Last updated on