Plans, Quotas, and Feature Gates

Use this guide to understand plan tiers, daily write quotas, and which features require a paid plan.

When to use

• You received a 403 feature_locked error and want to know which plan unlocks the feature.
• You received a 429 rate_limited error and want to understand your daily write quota.
• You want to compare what each plan tier includes before upgrading.

Plan tiers

All new accounts start on the FREE plan.

Write quotas

Every POST, PUT, PATCH, and DELETE request to /v2/** counts toward your daily write quota. The quota resets at midnight in your account timezone.

Reads (GET requests) do not count toward the quota.

What does not count

• Billing endpoints (/v2/billing/*)
• Public runtime endpoints (/v2/public/*)
• Visitor authentication endpoints

When you hit the limit

The API returns:

{
  "error": "rate_limited",
  "message": "Daily write quota exceeded for FREE.",
  "plan": "FREE",
  "limits": { "writesPerDay": 2 },
  "usage": { "writesToday": 2, "writesDay": "20260225" }
}

Wait until the next day (midnight in your timezone) or upgrade your plan.

Feature gates

When you try to use a feature that requires a higher plan, the API returns:

{
  "error": "feature_locked",
  "feature": "growth_tools",
  "requiredPlan": "PRO",
  "message": "Growth tools require a PRO plan."
}

Gated features

UI path

1. Open https://app.{PUBLIC_DOMAIN}.
2. Navigate to account settings.
3. Open the Billing section.
4. View your current plan and usage.
5. Select a new plan to upgrade.

Required auth

• Owner-level JWT to manage billing and change plans.
• OPERATOR or OWNER JWT to view billing summary.

API fallback

View billing summary

GET /v2/billing/summary

Returns your current plan, quota limits, usage counters, locked features, and Stripe subscription status.

Upgrade plan

POST /v2/billing/checkout-session

{
  "handle": "acme",
  "targetPlan": "PRO"
}

Returns a Stripe checkout URL. Redirect to that URL to complete the upgrade.

Manage subscription

POST /v2/billing/portal-session

Returns a Stripe billing portal URL where you can update payment methods or cancel.

Common errors

Related:

• API Auth and Error Model
• API Tokens and Automations
• Troubleshooting and Support