API reference, Console billing

Join the waiting list for a plan

View as Markdown

POST/v1/console/waiting-listoperation id joinWaitingList

Founding round: each plan has a limited number of seats. When a plan is sold out (available: false), join its waiting list. When a seat frees up, the next account on the list gets an email invitation and its seat is held for 72 hours. Idempotent per account and plan: joining again answers 201 with the same entry and place. An account that already holds the plan gets 409 subscription_exists.

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.

Parameters

x-dex-csrfheader · string

The csrf_token returned by createSession (or handed over in the completeGoogleSignIn redirect). Required with the session cookie on every state-changing console route; not used with a bearer app session.

32 to 64 characters

Request body

application/json, schema WaitingListRequest

planPlanIdrequired

A subscription plan (docs/pricing-v2.md). New plans may appear within v1.

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

Responses

201The account's entry on the plan's waiting list (new, or the one it already had).

Headers: x-request-id

objectstringrequired

always "waiting_list_entry"

planPlanIdrequired

A subscription plan (docs/pricing-v2.md). New plans may appear within v1.

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

statusstringrequired

waiting: in the queue. invited: a seat is held for the account until invite_expires_at; subscribe with createSubscriptionCheckout before then.

one of "waiting", "invited"

positioninteger | nullrequired

Place among the accounts waiting for this plan (1 is invited next); null once invited.

at least 1

createdstringrequired

When the account joined the waiting list.

format date-time

invite_expires_atstring | nullrequired

With invited, until when the seat is held (72 hours after the invitation); null while waiting.

format date-time

400The request could not be read. Codes: invalid_json (not JSON, not UTF-8, or a \u escape that is half of a surrogate pair, such as "\ud800" without its low half), duplicate_key (a JSON object repeats a key; param is the JSON pointer of the repeated member, such as /questions/q1/options/a), unsupported_media_type (not application/json) and invalid_header (a malformed idempotency-key or x-client-request-id; param names the header).

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

Error envelope. See Errors for every type and code.

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.

409The idempotency key was used with a different body, or the first request with this key is still running. Console billing routes also answer 409 for a state conflict: subscription_exists (createSubscriptionCheckout while a subscription is live, joinWaitingList for a plan the account holds), no_subscription (updateSubscription, cancelSubscription, createResetCheckout or createBillingPortalSession without one), plan_sold_out (createSubscriptionCheckout or updateSubscription to a plan with no founding-round seat left; with hints), key_revoked (updateKey on a revoked key).

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

Error envelope. See Errors for every type and code.

422The request is well-formed JSON but breaks a validation rule. param names the field as a dotted path. Codes: unknown_field, missing_field, invalid_type (wrong JSON type), invalid_value (right type, value out of range: an empty or over-long string, a state, instructions, criteria string or option description of only whitespace, an empty questions or options object, an empty state object or array, a pattern or allowed-value mismatch such as a label or level with outer whitespace, a state nested deeper than 32 levels, a bad date or date range), field_not_allowed (options or levels on the wrong question type), invalid_question_id, too_many_questions, too_many_options, invalid_levels (including two levels equal after Unicode NFC normalisation and lower-casing), invalid_min_confidence, duplicate_label (two option labels equal after Unicode NFC normalisation and lower-casing, such as Billing and billing), state_path_not_found, state_not_json and, on the console, top_up_limit_exceeded.

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.

Request: hot

{
  "plan": "hot"
}

Response: joined

{
  "object": "waiting_list_entry",
  "plan": "hot",
  "status": "waiting",
  "position": 12,
  "created": "2026-09-28T09:41:07Z",
  "invite_expires_at": null
}