API reference, Console billing

The account's subscription and weekly meter

GET/v1/console/subscriptionoperation id getSubscription

The current plan, its status, the paid period, a scheduled downgrade or cancellation, and the weekly meter (allowance, used, when it resets). An account that never subscribed, or whose subscription ended, has plan: null and status: none; its requests are paid from the prepaid balance at the standard rate.

Authentication. Console session cookie (__Host-dex_session), or an app session token (Authorization: Bearer dex_ses_...). With the cookie, state-changing routes also need the x-dex-csrf header.

Responses

200The subscription (or its absence).

Headers: x-request-id

objectstringrequired

always "subscription"

planstring | nullrequired

The current plan; null when the account has no subscription.

one of "base", "hot", "fierce", null

statusstringrequired

none: never subscribed, or the last subscription ended and the account is back on pay as you go. incomplete: Checkout started, the first payment is not settled yet (delayed payment methods). active: paid up; the weekly allowance is available. past_due: a renewal payment failed, the allowance stays available during the grace period. frozen: the grace period passed, requests are paid from the balance until the subscription is paid or ends. canceled: ended; plan is null.

one of "none", "incomplete", "active", "past_due", "frozen", "canceled"

cancel_at_period_endbooleanrequired

The subscription ends at current_period_end (cancelSubscription).

scheduled_planstring | nullrequired

A cheaper plan that applies at current_period_end (updateSubscription to a cheaper plan); null otherwise.

one of "base", "hot", "fierce", null

current_period_startstring | nullrequired

format date-time

current_period_endstring | nullrequired

When the paid month ends and Stripe bills the next one; a cancellation or downgrade applies then.

format date-time

week_started_atstring | nullrequired

Start of the current 7-day allowance week (weeks run from the subscription start).

format date-time

week_resets_atstring | nullrequired

When the allowance refills (week_started_at plus 7 days).

format date-time

week_allowance_tokensintegerrequired

format int64
at least 0

week_used_tokensintegerrequired

format int64
at least 0

reset_price_centsinteger | nullrequired

Price excluding VAT of a reset for the current plan; null without a plan.

resets_bought_this_weekintegerrequired

at least 0

billing_portalbooleanrequired

Whether createBillingPortalSession works (the Stripe Customer Portal is configured for Dex and the account has a Stripe customer).

currencystring | nullrequired

The currency the plan is billed in (Stripe's subscription currency, else the account's billing_currency); null without a plan or before it is known. reset_price_cents stays in euro cents: the reset in this currency is Plan.prices[currency].reset_price_cents. New currencies may appear within v1.

one of "EUR", "USD", "GBP", "INR", null

401Missing, unknown, revoked or expired credentials.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

403The credentials are valid but not allowed to do this (missing scope, suspended account or failed CSRF check).

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

500An unexpected error. Any charge was refunded. Retry with the same idempotency key.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

503maintenance: the console's database, sign-in or payments are unavailable for a moment (for createGoogleSession also: Google sign-in is not configured, or Google's signing keys cannot be fetched). Retry after retry-after. Nothing was changed.

Headers: x-request-id, retry-after

Error envelope. See Errors for every type and code.

Examples

Illustrative values. Examples show the shape of requests and responses; the numbers in them are not measured results.

Response: Base plan, week 3 of the subscription, one reset bought this week

{
  "object": "subscription",
  "plan": "base",
  "status": "active",
  "cancel_at_period_end": false,
  "scheduled_plan": null,
  "current_period_start": "2026-10-03T09:15:00Z",
  "current_period_end": "2026-11-03T09:15:00Z",
  "week_started_at": "2026-10-17T09:15:00Z",
  "week_resets_at": "2026-10-24T09:15:00Z",
  "week_allowance_tokens": 4611000,
  "week_used_tokens": 1204880,
  "reset_price_cents": 250,
  "resets_bought_this_week": 1,
  "billing_portal": true,
  "currency": "EUR"
}