Stigg freemium with paid usage: credits vs metered overages and the seam gotchas
Guide Stigg freemium with paid usage: credits vs metered overages and the seam gotchas: Stigg has two competing primitives for this: credits (recurring grant + paid top-ups) and metered feature with overages (included quota + per-unit rate). Use this when you hit exactly this in Stigg freemium with paid usage. Not for different errors or different tools.
TL;DR: Stigg has two competing primitives for this: credits (recurring grant + paid top-ups) and metered feature with overages (included quota + per-unit rate). Context: Official docs (Stigg skills repo, stigg-recipes/references/freemium-with-paid-usage.md): the full recipe for the OpenAI-API-style 'free quota, then pay per unit' model.
Context: Official docs (Stigg skills repo, stigg-recipes/references/freemium-with-paid-usage.md): the full recipe for the OpenAI-API-style 'free quota, then pay per unit' model. Stigg has two competing primitives for this: credits (recurring grant + paid top-ups) and metered feature with overages (included quota + per-unit rate). The doc walks both paths and lists five gotchas at the seams that catch integrators.
Pick the primitive deliberately, because migration between paths is non-trivial (re-model the catalog, re-provision). Pick credits when customers buy usage in advance (prepaid packs), cost per unit varies by workload (per-model AI, per-region, custom formula), you want auto-recharge on low balance, or customers should see a real-time balance widget. Pick metered + overages when customers pay in arrears at end of period, cost is uniform per unit, and auto-charge above quota is fine with no prepaid-balance UX. The five seam gotchas: 1. The Free plan is still a real subscription. Provision every customer onto plan-free at signup; without an active subscription, gating returns fallback values. 2. requestedUsage on getMeteredEntitlement does not enforce. It only reports hasAccess for a hypothetical. Real enforcement happens at usage-report time (or for credits, never: overdraft auto-creates). 3. Credits + overages combined is unusual. Pick one; if you modeled both you are doubling up. 4. Auto-recharge only fires on credit-balance crossings. On the overages path it does not apply; Stripe invoicing handles paid usage. 5. On the credits path do not pre-block on overdraft: Stigg auto-creates an overdraft grant at zero, so let the call through, surface a warning in UI, and let top-up or auto-recharge settle the deficit. Wire webhooks for credit.balance.low / credit.balance.depleted / automaticrecharge.* (credits) or entitlement.usageexceeded (overages).
When to use
You hit exactly this: Stigg freemium with paid usage: credits vs metered overages and the seam gotchas in Stigg freemium with paid usage.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
Stigg freemium with paid usage.