How do per-user spending caps work?
Per-user spending caps stop the assistant from generating more usage once an end-user crosses a monthly cost threshold you define. The cap uses the same suspension gate as MCP Gateway's cap_action=block, so the behaviour is consistent across products: at the cap, the widget shows a graceful 'limit reached' message instead of replying. Caps are reset on the first of each calendar month.
Setup
- Open Monetize → Caps.
- Set a default monthly cap (USD) applied to every end-user.
- Optionally set a soft threshold percentage for an in-widget warning.
- Save. Caps take effect on the next forwarded meter event.
Cap behaviour
- Under soft threshold — normal operation, no UI changes.
- Soft → hard — widget shows a warning banner; assistant still replies.
- At hard cap — assistant returns a 'limit reached' message; no model call is made.
- Reset — all caps reset at 00:00 UTC on the first of each calendar month.
Per-user overrides
Open any end-user's detail page from Monetize → Users. You can raise or lower their cap, manually unblock them mid-cycle, or exempt them entirely (sets cap to unlimited). All overrides are audit-logged.
How a visitor's cap is resolved
Each visitor's effective monthly cap is picked in this order — the first match wins:
- Per-user override — a cap you set on that visitor in Monetize → Users.
- Tier — the
tierclaim in the visitor's widget JWT (e.g."pro"), matched against the per-tier caps you configured. Free-form — use your own plan labels. - Default — the workspace-wide default cap.
tier is distinct from the lifecycle plan claim (trial | paid | free), which only steers the activation agent's guidance and never affects caps. See the JWT claim reference.
Next steps
FAQ
- What identity is the cap scoped to?
- The JWT 'sub' you pass on widget identify. Without JWT auth, caps fall back to anonymous session IDs which reset on browser change.
- Can I warn users before they hit the cap?
- Yes — set a soft threshold (e.g. 80%). The widget surfaces a warning banner once usage crosses it. Hard block fires at 100%.
- Can I override a cap for a specific user?
- Yes. Open the user in the Monetize → Users list and set a custom cap or unblock them mid-cycle.
- Can different plans get different caps?
- Yes. Put your plan label in the widget JWT's tier claim and configure a cap per tier. Resolution order is per-user override, then tier, then the workspace default.