Entitlements
The per-tenant budget caps you set with create and plan. A JSONB object of known knobs — invalid keys and values are dropped silently, never rejected.
Entitlements are the per-tenant limits you set with create and patch with plan. They are stored as a JSONB object and act as budget caps — they bound what a tenant may consume but never fund it. The bill always meters to your platform account (see Data model).
Sanitization
The object is sanitized before it is stored, and the rules are forgiving by design so that one bad value never fails an otherwise-valid call:
- Unknown keys are dropped silently. Only the knobs below are recognized.
- For numeric keys,
nullpasses and means unlimited. - Finite values
≥ 0pass. Anything else — negatives,NaN, infinity, non-numbers — is dropped silently.
A dropped value is simply absent from the stored object; it is never an error. Because of this, plan requires the object to be non-empty after sanitization.
For the count-style limits (max_projects, max_published_projects, max_custom_domains), 0 or null means unlimited — they are budget ceilings, not gates. To disable a feature entirely, use the dedicated boolean knob (e.g. custom_domains_enabled: false) rather than a count of 0.
Knobs
Prop
Type
Caps replace within the keys you send
plan overwrites entitlements within the keys present in your
request. Send the full object you want each time rather than a single field, or
you may leave a stale cap in place.
Re-send plan_name on every plan call
plan_name lives in the same entitlements object as the caps. The named-plan
path in plan replaces the entitlements wholesale, so if you omit
plan_name on a change-plan call the customer-facing plan label is wiped.
Always include it in the entitlements you send.
Plans are host-defined
plan_name is just a label. There is no Swarmz catalog of plans — you define your plans (their names, prices, and the caps each one maps to) in your own billing system. The Platform API only stores the resulting per-tenant caps plus the display label.
If you maintain named plans server-side, you can also register them with Swarmz and address them by a stable code: list them with platform-plans and assign one with the plan_code param on create and plan. See Credits for how the credit knobs behave across plan changes.
Account billing summary
The owner-facing billing snapshot for your own platform account — period usage, the upcoming invoice, the card on file, and recent invoices. Supabase user-JWT authed; not a host API call.
The credit model
How a tenant's credits work — free daily credits, the monthly grant, top-ups, and rollover — and exactly when each one is billed to your platform account.