---
title: "Get a subscription"
method: GET
path: "/v1/subscriptions/{subscription}"
tags: ["Subscriptions"]
---

# Get a subscription

`GET /v1/subscriptions/{subscription}`

## Request

- Base URL: `https://api.subscriby.net`
- URL: `https://api.subscriby.net/v1/subscriptions/{subscription}`
- Auth: HTTP bearer

One subscription with its `grants` embedded.

`payment_status` is one of `trialing`, `active`, `incomplete`, `expired`, `past_due`, `canceled`, `unpaid`, `paused`, `processing`, `succeeded`, `capturable` or `failed` (the `subscriby://enums/subscription-status` MCP resource lists them).

`compensation_seconds` is the outage time [Outage Compensation](https://docs.subscriby.net/disaster-recovery/connector-outages#outage-compensation) has banked on the purchase, `0` for almost every subscription. `ends_at` already includes it: 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, so the renewal the gateway bills is `ends_at` minus `compensation_seconds`.

## Path parameters

- `subscription` string, uuid, required

## Response `200`

The subscription, its access grants embedded.

- object
  - `data` object, required: A subscription: one member's purchase of a plan, held or still an unredeemed access code, with its payment state and, on the detail read, its access grants.
    - `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[], required: 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.

## 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.
- `404`: `RESOURCE_NOT_FOUND`: an id in the path names nothing the token can see. `TENANT_MISMATCH`: the project sits outside the token's `scope:project:` allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.
- `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)