Spend controls & auto-reload

01Two independent controls

STELQ gives you two separate guardrails for spend. A per-key credit limit hard-caps how much a single key can spend (great for handing a scoped key to an agent or a teammate). Auto-reload keeps your account wallet topped up off-session so long-running workloads never hit a 402 mid-job. They are orthogonal: a per-key cap protects you from one key running away; auto-reload protects you from the whole account running dry.

02Per-key spend caps

Each key can carry a creditLimitCents and an optional resetPeriod of daily, weekly, or monthly. The gateway tracks the key's running spend and enforces a HARD cap: a request that would push the running total past the limit is rejected, and so is a request on a key that is already at or over the ceiling. There is no last-request overshoot — a key never spends a single cent beyond the limit its owner set.

The check runs in the gateway's balance middleware before the request is dispatched upstream, so a capped-out key is rejected pre-billing. When a resetPeriod is set and the period has elapsed since the key's last reset, the running total is treated as zero — the limit re-arms automatically, with nobody having to touch the key.

{
  "error": "This key has reached its credit limit ($5.00 of $5.00). Raise the limit or resume spending from the dashboard at https://stelq.com/dashboard."
}

A per-key cap is distinct from your account wallet. The wallet is the shared pool of prepaid credit every key draws from; the per-key cap is a ceiling on how much of that pool one key may consume. A request is allowed only if it clears BOTH checks — the wallet must afford it, and the key must be under its cap.

• creditLimitCents: the spend ceiling for this key (null = unlimited; the key spends straight from the wallet).
• resetPeriod: daily | weekly | monthly | null — when set, the running total auto-resets to zero once the period elapses.
• Enforced in the gateway before upstream dispatch, so a capped request never bills.
• Distinct from the account wallet balance, and NOT a permission scope.

03Auto-reload (off-session)

Auto-reload keeps your wallet funded without you in the loop. When a debit pushes your balance below a threshold you choose, a saved card is charged off-session and the wallet is credited — so a batch job or an autonomous agent that runs overnight never stalls on an empty balance. Both the threshold and the reload amount are whole dollars, and the amount must be at least your threshold so a reload always lifts you back out of the trigger zone.

Configure it at GET / PUT /api/dashboard/billing/auto-reload. Enabling unattended charges requires two things: a saved card and consent to the current off-session mandate. Without a card the enable call returns 409 (needsCard); without consent it returns 400. Once you have accepted the mandate, later edits to the threshold or amount do not re-prompt. If Stripe billing is not configured for the platform, the enable call returns 503.

curl -X PUT https://stelq.com/api/dashboard/billing/auto-reload \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 50,
    "amount": 100,
    "consent": true
  }'

Detection is fast. The moment a debit crosses your threshold, the usage path flags your account inline (no Stripe call on the hot path), and a gateway-driven sweep (~once a minute) services the flag — so reload latency is milliseconds-to-seconds, not minutes. The sweep also scans for under-threshold accounts directly, so a missed flag only ever means slightly slower, never missed.

04Safety rails & no double-charge

Off-session charging is the one place STELQ moves money without you present, so it is wrapped in hard guarantees. The headline invariant is no double-charge: there is at most ONE open reload episode per user, enforced by a database partial unique index. A second concurrent trigger cannot start a new charge — it must reuse the open episode's STABLE Stripe idempotency key, which is reused on every retry so Stripe itself returns the original PaymentIntent instead of charging a second time.

A charge whose fate is unknown is never re-charged blind. A reload stuck in pending is reconciled — the system asks Stripe whether it actually went through and settles it (crediting the wallet only if it truly succeeded) before any new charge is considered. The credit and the state advance commit in a single transaction, so the cooldown can never arm without money having actually moved.

05Related