Get billing status

GEThttps://app.speybooks.com/api/v1/billing/status

Returns the organisation's current billing state: plan, grace and trial state, days remaining, founder seat, and live Stripe subscription detail when a subscription pointer exists. The call is read-only and writes nothing. Subscription detail is fetched live from Stripe; the mirror columns are the fallback when the Stripe read returns no period end.

The response carries a precomputed variant: exactly one billing-page state per render, with the dates and amounts that state needs. Clients render from the variant rather than re-deriving state from the raw fields, which remain for display detail and compatibility. Two payload-bearing kinds have behaviour worth stating. pending_cancel carries an optional paymentFailure block when a payment failure coexists with the scheduled cancellation, so one render shows both facts together. cancelled carries retentionUntil, the end of the 12-month read-only-plus-export retention window.

Two response values are derived rather than read straight from Stripe: currentPeriodEnd is read from the subscription item's billing period, and cancelAtPeriodEnd is true whenever a cancellation is scheduled, regardless of which Stripe field carries it.

Response

200Returns current subscription status, trial info, and Stripe subscription details.
Show response fields
hasStripeCustomerboolean
Whether a Stripe customer record exists for this organisation.
hasSubscriptionboolean
Whether a Stripe subscription pointer exists for this organisation. A cancelled subscription pointer persists through the retention window, so true does not imply an active subscription.
isTrialActiveboolean
Whether the grace window is active: registered, not yet subscribed, grace not expired. Grace state, not Stripe trial state; the field name is retained for client compatibility.
planstring
Current plan identifier.
trialsole_traderlimited_company
planNamestring
Human-readable plan name.
seatNumberintegernullable
Founder seat number (1 to 50) by order of first subscription. Null otherwise.
subscriptionobjectnullable
Stripe subscription details. Null if no subscription exists.
Show child attributes
amountPenceintegernullable
Recurring amount in pence from the subscription price.
cancelAtPeriodEndboolean
Whether the subscription will cancel at the end of the current period.
cardobjectnullable
Default payment method card details.
Show child attributes
brandstring
expMonthinteger
expYearinteger
last4string
currentPeriodEndstringnullabledate-time
End of the current billing period.
nextPaymentAttemptstringnullabledate-time
Next dunning retry when past_due.
statusstring
Stripe subscription status (active, trialing, past_due, canceled, unpaid).
trialEndstringnullabledate-time
Stripe trial end when trialing.
subscriptionStatusstringnullable
The organisation's mirrored subscription status, Stripe vocabulary verbatim. Statuses outside this set are refused at the webhook and never reach the mirror. Null if never subscribed.
trialingactivepast_dueunpaidcanceled
trialDaysRemaininginteger
Whole days remaining in the grace window. Zero once grace has lapsed or the organisation has subscribed.
trialEndsAtstringnullabledate-time
ISO 8601 trial expiry timestamp.
variantobject
The billing page banner variant, precomputed by the API (DESIGN-BILLING-LIFECYCLE section 6). Exactly one per render; the frontend derives nothing. kind is the discriminant; each kind carries only its own payload fields, and fields belonging to other kinds are absent from the response.
Show child attributes
cancelsOnstringnullabledate-time
pending_cancel: the date the plan cancels; access continues until then.
daysLeftintegernullable
grace, trial, trial_ending: whole days remaining.
endedOnstringnullabledate-time
cancelled: when the subscription ended.
firstChargeAmountPenceintegernullable
trial, trial_ending: the first charge amount in pence.
firstChargeDatestringnullabledate-time
trial, trial_ending: when the first charge happens.
kindstring
The section 6 variant name.
gracegrace_expiredtrialtrial_endingactivepending_cancelpast_duesuspendedcancelled
nextChargeAmountPenceintegernullable
active: the next charge amount in pence.
nextChargeDatestringnullabledate-time
active: when the next charge happens.
nextRetryAtstringnullabledate-time
past_due: when the next automatic retry happens.
paymentFailureobjectnullable
pending_cancel only, when the underlying status is past_due: the coexisting payment-failure facts (section 6 declared exception).
Show child attributes
nextRetryAtstringnullable
When the next automatic retry happens.
retryWindowEndsstringnullable
When the retry window closes.
payUrlstringnullable
suspended: the hosted payment page for the outstanding invoice. Settling restores access instantly.
retentionUntilstringnullabledate-time
cancelled: read-only access and export available until this date (12-month retention window).
retryWindowEndsstringnullabledate-time
past_due: when the retry window closes. The copy must state this date (section 6 rule).
trialEndedAtstringnullabledate-time
grace_expired: when the grace window ended.
trialEndsAtstringnullabledate-time
grace, trial, trial_ending: when the trial or grace window ends.

Error codes

404Organisation not found.