| name | skill-saas-core-limits |
| description | Implement SaaS plan limits, quotas, entitlements, feature flags, trials, grace periods, blocked accounts, usage counters, and access checks after AbacatePay, Stripe, webhook, or manual admin subscription changes. |
| category | saas |
| risk | medium |
| source | local-saas-entitlement-patterns |
skill-saas-core-limits
Workflow
- Identify the billable actor: user, tenant, workspace, account, organization, or project.
- Inventory gated features and usage counters. Classify each as hard limit, soft limit, feature flag, trial-only feature, admin override, or informational banner.
- Model entitlements independently from payment provider objects. Store provider IDs as evidence, not as the product access model.
- Enforce important limits server-side, in RPC, or through RLS. Use frontend checks only for early feedback.
- Make usage updates atomic when races are possible.
- Add audit logs for payment sync, admin overrides, blocked states, automatic deactivation, and limit resets.
- Verify transitions with focused tests, SQL checks, or manual scenarios.
Data Model
plans: code, display name, active flag, currency, price, interval, feature limits JSON.entitlements: actor ID, plan ID, status, starts_at, ends_at, grace_until, provider, provider IDs, override fields.usage_counters: actor ID, feature key, period start/end, used count, hard limit, reset policy.audit_logs: actor, action, before/after, reason, source, correlation ID.
Status Contract
- Subscription/access states:
trialing, active, grace, past_due, cancelled, expired, blocked.
- Usage states:
ok, caution, warning, limit_reached, expired.
- Suggested thresholds:
caution at 70%, warning at 90%, limit_reached at 100%.
Guardrails
- Do not grant or revoke access from a checkout success redirect alone.
- Do not trust frontend counters for enforcement.
- Do not scatter plan logic across UI components. Centralize in backend services, RPC, or shared domain helpers.
- Do not block paid users silently. Return actionable errors and show upgrade/recovery paths.
- Keep grace-period and cancellation policy explicit; do not infer it from provider defaults.
Local Reference
For a concrete local pattern, inspect {{USER_HOME}}/Documents\Code\Nina\src\lib\planLimitChecker.ts only when implementing similar Supabase/RPC usage checks.
Related Skills
skill-saas-factoryskill-abacatepay-integrationskill-stripe-integrationskill-supabase-rls
