---
title: "Read your subscription credits"
method: GET
path: "/router/subscription/balance"
tags: ["Router"]
---

# Read your subscription credits

`GET /router/subscription/balance`

## Request

- Base URL: `https://api.sandbox.nevermined.app/api/v1`
- URL: `https://api.sandbox.nevermined.app/api/v1/router/subscription/balance`
- Auth: HTTP bearer

Your Nevermined Subscription credits left, when they reset, and your plan. Charges nothing. Called in an organization you are an active member of (`X-Current-Org-Id`, or that organization's API key), it reads that organization's subscription instead, never your personal one; organizations can no longer subscribe, so that is `subscribed: false` unless the organization still holds one bought earlier. `subscribed: false` carries no other field; every other field is present exactly when `subscribed` is true.

Personal API keys only: the Nevermined Subscription belongs to a personal account, so call with a key that carries no organization tag and without `X-Current-Org-Id`. An OAuth-minted credential is refused (`BCK.OAUTH.0030`). Where the subscription is not available — on this deployment or to this account — it answers 404 `BCK.SUBSCRIPTION_ACCESS.0001`.

## Response `200`

The caller's credits, reset date and plan.

- SubscriptionBalanceDto
  - `subscribed` boolean, required: Whether the caller has a current Nevermined Subscription.
  - `creditsLeft` string: Credits left: the unexpired remainder, as a whole-number digit string. What the Router debits.
  - `spendable` boolean: Whether these credits can pay a call right now: the subscription is active or trialing and not suspended by a card dispute.
  - `resetsAt` string, nullable: When this period's credits expire and — unless `cancelAtPeriodEnd` — the next period's are granted, on payment of its invoice (ISO 8601). `null` until the billing period is recorded.
  - `cancelAtPeriodEnd` boolean: The subscription ends at `resetsAt` instead of renewing.
  - `status` 'incomplete' | 'trialing' | 'active' | 'past_due' | 'unpaid' | 'paused': The subscription status. A `past_due` subscription keeps its credits but cannot spend them until its invoice is paid. An ended subscription answers `subscribed: false`.
  - `suspended` boolean: True while a card dispute is open, or after one was decided in the cardholder's favour: the credits cannot be spent. A dispute decided in Nevermined's favour lifts it, once no other dispute is open or was decided in the cardholder's favour.
  - `plan` SubscriptionBalancePlanDto
    - `catalogId` string, uuid, required: The subscription price subscribed to.
    - `planKey` string, required: The plan bought.
    - `creditsPerCycle` string, required: Credits each paid monthly invoice grants, as a whole-number digit string.

## Other responses

- `401`: Missing/invalid Nevermined API key.
- `403`: An OAuth-minted credential (BCK.OAUTH.0030).
- `404`: Not available to the caller (BCK.SUBSCRIPTION_ACCESS.0001).
- `503`: The balance could not be read (BCK.SUBSCRIPTION_MCP.0001) — never answered as zero. Retry.

---

[API](https://skmtc.dev/nevermined/apis/nevermined-api.md) · [All operations](https://skmtc.dev/nevermined/apis/nevermined-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nevermined/apis/nevermined-api/revisions/cabbe618c80b?raw)