Account credit balance

Responses

• 200 The account credit balance and usage
  • balance integer required

    Total spendable credits right now: `period.remaining` plus `topup.balance`. This is the number a 402 is checked against.

  • plan string required

    The plan whose allotment funds `period`.

  • unlimited boolean required

    True when the plan carries no credit ceiling, in which case the period counters are informational and spend is never refused for balance.

  • period object required

    The current period’s plan allotment. This bucket EXPIRES: whatever is left when the period rolls over does not carry forward.

    • granted integer required

      Credits the plan granted for the current period.

    • spent integer required

      Credits spent against that grant so far this period.

    • remaining integer required

      What is left of this period’s grant. Never negative: spend beyond the grant draws on `topup.balance` instead.

  • topup object required

    Purchased credits. This bucket never expires and is drawn on only after the period grant is exhausted.

    • balance integer required

      Credits remaining in the purchased bucket.

  • refreshesAt string required

    When the current period ends and a fresh grant lands, as an ISO 8601 instant.

  • autoTopup AutoTopUpView required

    Automatic recharge settings for this account.

    • enabled boolean required

      Whether automatic recharge is armed.

    • thresholdCredits integer | null required

      Recharge fires when the spendable balance falls below this number of credits. Null when not configured.

    • credits integer | null required

      How many credits are bought each time recharge fires. Null when not configured.

    • lastError string | null required

      The last off-session charge failure, in plain words. A non-null value also means recharge was DISABLED by that failure rather than retried, so a declined card stops the loop instead of storming it. Reconfiguring clears this.

  • members array of MemberCreditView

    Per-member and per-key spend breakdown. Present only for callers entitled to manage members; absent otherwise, which is a permission fact and not an empty account.

    • actorKind string required

      Whether this row is a `member` (a person) or a `key` (an API key acting on its own).

    • actorId string required

      The member id or key id this row is about.

    • label string required

      A human label for the actor, for display.

    • monthSpent integer required

      Credits this actor has spent in the current period. Resets when the period rolls over.

    • cap integer | null required

      The per-period ceiling on this actor’s spend. Null means uncapped. Once a capped actor reaches its cap its calls are refused with a 429 until the period rolls over; it does not consume anyone else’s allowance.

• 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.