Skip to content
nsin nsin nsin Docs

Get one subscription

GET
/subscriptions/{id}
 
curl --request GET \
  --url https://api.nsin.cloud/subscriptions/1 \
  --header 'Authorization: Bearer <token>'

{id} is the numeric subscription id from GET /subscriptions, never a domain: subscriptions are per domain, and every purchase, switch and renewal leaves its own row, so expired, cancelled and superseded ones stay readable here indefinitely. The lookup is bound to your own user_id, so a subscription on a domain that was merely shared with you is a 404 — read that one through GET /domains/{domain}/subscription, which admits shared members. The payload is an envelope rather than a bare subscription: subscription (carrying effective_features, plus the quota window while it is active or in grace), period_statement, and invoices for this subscription, newest id first. period_statement is the newest frozen statement of this subscription; if it never closed one and is still active or in grace, the field falls back to a live estimate built for the domain’s current subscription, so compare the statement’s subscription_id with {id} before attributing it. In every other case it is null.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
integer

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Subscription.

Media type application/json

A plan attached to one domain. Entitlements are not read from the plan directly — use GET /domains/{domain}/features, which resolves any per-subscription overrides.

object
id
integer
user_id
integer
domain_id
integer
domain_name
string
plan_id
integer
plan

The plan this subscription is on.

object
key
additional properties
any
plan_term_id
integer
plan_term

The billing term purchased.

object
key
additional properties
any
status

For example active, expired, grace or cancelled.

string
started_at
string format: date-time
expires_at
string format: date-time
grace_until
string format: date-time
auto_renew
boolean
quota_reset_days

Traffic-allowance reset cadence, frozen at purchase time so later plan changes cannot shift an existing subscriber’s quota window.

integer
is_trial

The free trial granted at signup. Downgrades to the free plan on expiry rather than entering grace.

boolean
Example generated
{
  "id": 1,
  "user_id": 1,
  "domain_id": 1,
  "domain_name": "example",
  "plan_id": 1,
  "plan": {},
  "plan_term_id": 1,
  "plan_term": {},
  "status": "example",
  "started_at": "2026-04-15T12:00:00Z",
  "expires_at": "2026-04-15T12:00:00Z",
  "grace_until": "2026-04-15T12:00:00Z",
  "auto_renew": true,
  "quota_reset_days": 1,
  "is_trial": true
}

401

Section titled “401 ”

Missing, malformed, revoked or expired API key, or a key whose owning user row is gone. A key whose owning account has merely been deactivated is not this: that is 403 with code: account_suspended, because the credential itself is intact and re-issuing it changes nothing.

Media type application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object
error
required

Human-readable description of what went wrong.

string
code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

  • account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
  • domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
  • managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
  • invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

string
Examples
Example invalidKey 
{
  "error": "invalid API key"
}

404

Section titled “404 ”

No such subscription on this account.

Media type application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object
error
required

Human-readable description of what went wrong.

string
code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

  • account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
  • domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
  • managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
  • invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

string
Example 
{
  "error": "read-only API key"
}

429

Section titled “429 ”

The key exceeded its request budget (300 requests per minute by default).

Media type application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object
error
required

Human-readable description of what went wrong.

string
code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

  • account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
  • domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
  • managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
  • invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

string
Examples
Example limited 
{
  "error": "rate limit exceeded"
}