Overview
The Account API returns the subscription state of the account a Scrunch API key belongs to: the organization, its plan, and the current billing period. Use it to gate a partner experience by trial state, drive an upgrade prompt in your own UI, or confirm the account is still paying before serving premium features. The endpoint is read-only and does not change how the account is billed.When to use the Account API
Use the Account API when you need to:- Tell a trial account from a paid or churned one inside a product-led growth flow
- Read the trial end date to schedule reminders or conversion prompts
- Confirm the account behind an API key is still active before serving a paid integration
Endpoint
The endpoint requires a bearer token with the
query scope. See Authentication.
The account is derived from the API key, so there are no path or query parameters. Session (JWT) callers return 400, because a user may belong to several organizations and the credential alone does not name one.
Example
Reading the response
status
status reports the account’s subscription state. Most values mirror Stripe’s own subscription statuses:
Two values are specific to this endpoint:
subscription_not_found— Scrunch holds no Stripe subscription record for this account. This is normal for manually invoiced accounts and CS-managed trials, and is not a sign that the account lapsed. Treat it as “active unless you know otherwise” in a gating flow.unknown— Scrunch cannot vouch for the account’s current state, either because its billing record is no longer being kept up to date or because the subscription is in a state this endpoint does not publish yet. Keep your current behavior rather than treating it as a lapse.
current_period_end for trials
While status is trialing, current_period_end is the date the trial ends. Use it to schedule reminders or drive an in-product conversion prompt.
plan and plan_display_name
plan is the machine-readable plan name (for example enterprise); use it in gating logic. plan_display_name is the human-readable label (for example Enterprise); show it in UI. Both are empty strings when the account has no plan on file.