Account subscription

Responses

• 200 The merged subscription view
  • plan string required

    The EFFECTIVE plan: what this account can actually do right now. Entitlements and quotas all flow from this, including during a trial.

  • status string | null required

    Subscription status, mirroring Stripe. Metadata for display; capability comes from `plan`. Null when there is no subscription.

  • cancelAtPeriodEnd boolean required

    True when the subscription ends at the period boundary rather than renewing. Nothing is downgraded until then.

  • renewsAt string | null required

    When the plan next renews, as an ISO 8601 instant. Null when there is nothing to renew.

  • billingEmailsEnabled boolean | null required

    Whether Stripe billing emails are sent to this account. Null when not configured.

  • live LiveSubscription required

    The subscription read live from Stripe. Null when there is no subscription, or when the live read failed — check `liveError` to tell those apart.

    • id string required

      The Stripe subscription id.

    • status string required

      The Stripe subscription status. A trial is `trialing` over the trialled plan, not a separate plan.

    • priceId string required

      The Stripe price the subscription is on.

    • planName string required

      The plan this subscription grants.

    • amount number required

      Price per seat per interval, in the currency’s SMALLEST unit (4900 = $49.00). Multiply by `quantity` for the recurring total.

    • currency string required

      ISO 4217 currency code, lower-case.

    • interval string required

      Billing interval: `month` or `year`.

    • currentPeriodEnd string required

      When the current billing period ends, as an ISO 8601 instant.

    • cancelAtPeriodEnd boolean required

      True when the subscription is set to end at `currentPeriodEnd` instead of renewing. The plan stays fully active until then.

    • quantity integer required

      Seats currently billed by Stripe. This is seats PAID FOR, which can differ from seats occupied.

    • nextInvoiceAmount number | null required

      Preview of the next invoice total, in the currency’s smallest unit. Null when Stripe has nothing to preview, which is normal for a cancelled or ended subscription.

  • liveError boolean required

    True when the live Stripe read failed. The rest of this response is still authoritative: `plan`, `status` and `quotas` come from our own records, so a Stripe outage does not change what the account may do.

  • quotas array of BillingQuotaView required

    Every numeric allowance this plan sets, with current usage.

    • metric string required

      The quota metric key. Stable; branch on this rather than on `label`.

    • label string required

      Human-readable name of the metric, for display.

    • limit integer required

      The ceiling this plan allows. A value of -1 means unlimited.

    • used integer required

      How much of the allowance is consumed.

    • remaining integer required

      What is left. Reaching zero is refused with a 429 for a usage metric and a 402 for a capacity metric such as seats.

  • grant SubscriptionGrantView required

    A plan granted outside Stripe, when one is in force. Null otherwise.

    • plan string required

      The plan granted directly rather than through a paid subscription.

    • expiresAt string | null required

      When the grant lapses, as an ISO 8601 instant. Null means it does not expire on its own.

• 401 No or invalid credential
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.

• 403 Missing billing:read
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.