What each action actually does
// plan "free": cap $0.50/month, action "block"
try {
const result = await wk.chat(openai, { model: 'gpt-5.4-mini', messages, userId, feature, plan: 'free' });
} catch (err) {
if (err instanceof WeckrCapError) {
return { error: 'Free limit reached. Upgrade to keep going.' }; // your upsell moment
}
throw err;
}
// plan "pro": cap $10/month, action "downgrade"
// over budget: the call succeeds, silently served by the cheaper same-provider
// model (for example gpt-5.4 -> gpt-5.4-mini). onDowngrade fires so you know.The check runs before the call and is cached per user for 60 seconds, so it adds no meaningful latency. Downgrade paths never cross providers, a customer on Claude stays on Claude, just cheaper.
The decision, plan by plan
- Free tier: block. The cap is your acquisition budget, per the free tier design rules, and hitting it is the conversion moment. A wall plus upgrade prompt is honest and effective, and it is the only action that fully stops the bots and quota farmers a free AI tier attracts. Downgrading a bot just makes the abuse cheaper.
- Paid tiers: downgrade. Your heaviest paying users are usually your most engaged, per the one user costing more than they pay. Blocking them mid workflow converts your best fans into churn risk; downgrading bounds the cost while the feature keeps working. Current budget models are good enough that most users never notice.
- Quality contractual tiers: block, with a big budget. If enterprise customers pay specifically for the premium model, silently serving less is worse than a clear limit conversation. Set the cap high, action block, and treat a hit as an account management signal.
- Unsure: downgrade. It is the reversible choice: nothing breaks, the onDowngrade callback tells you exactly who hits it and how often, and that data tells you whether the budget is too low, the plan is mispriced, or block would be safe.
Setting the budget number
The cap should sit above your p95 user’s normal monthly cost and below the point where the plan loses money, both numbers you read off the Users page once real traffic flows, or estimate beforehand with the feature cost method and the break even calculator. A cap that fires on normal usage is a product bug; a cap that only fires on runaways is insurance, and the runaway case is handled in depth in what happens when Weckr catches a runaway agent.
FAQ
What is the difference between block and downgrade in Weckr caps?
Both trigger when a user exceeds their plan’s monthly spending budget, checked before each call. Block stops the call entirely: the SDK throws WeckrCapError before any spend, and you show an upgrade prompt. Downgrade lets the call proceed but silently swaps to a cheaper model in the same provider, so the feature keeps working at a fraction of the cost.
When should a plan use block?
Free tiers and abuse exposure. A free user at their cap has consumed their acquisition budget; a hard stop with an upgrade prompt is the honest mechanic, and it is the only defense that fully stops bots and quota farmers, who are unimpressed by quality downgrades. Block is also right when the output quality is contractual and silently serving a weaker model would be worse than serving nothing.
When should a plan use downgrade?
Paying customers. A paying user hitting a wall mid workflow is a churn event; the same user quietly moved from a premium model to a budget one is usually a non event, since current budget models handle most product features respectably. Downgrade converts an unbounded cost into a bounded one without a single support ticket, which is why it is the default recommendation for paid tiers.
Does the user know they were downgraded?
Not unless you tell them. The swap is silent at the API level, the call succeeds on the cheaper model, and the SDK fires an onDowngrade callback with the user, the original model, and the substitute, so you can decide the product behavior: say nothing, show a subtle notice, or use it as an upsell moment. The downgrade path always stays within the same provider, never a silent vendor switch.
What happens to caps if Weckr itself is unreachable?
The check fails open: the call proceeds as if no cap existed. A monitoring outage must never take your product down, so the tradeoff is a brief enforcement gap during a Weckr outage rather than your users being blocked by someone else’s incident. Auth failures are the deliberate exception and fail closed, so a revoked key cannot silently disable enforcement.
Keep reading
Configure it in two clicks
Caps live in the dashboard settings: pick a plan, set the monthly budget, choose block or downgrade, done, enforced on the next call. See the caps screens on the live demo (no signup), or wire your project via the ten minute integration, free for 50,000 requests a month.