Managing org entitlements

How owners grant and revoke tool access for members, how the preview/confirmation modal works, and the price-ID-keyed reconciliation rule.

Who can do this

Only owners of a team organization can change member entitlements. Members and viewers see the same billing tab but the tier toggle buttons are disabled and the Save Changes button never becomes actionable. If you need tier changes and aren’t an owner, ask an owner directly — the docs won’t help you bypass the permission check.

The member tree

The Organization Settings Billing tab shows each member of the org as a collapsible row. Expand a member and you get a per-tool grid: for every tool the org owns (or could own) a subscription for, there is a pair of toggles for the Basic and Pro tiers. The toggles reflect the member’s current entitlement from this org’s subscription. Entitlements granted by the member’s own personal subscription (or by another org they belong to) are not shown on this page — those appear in the member’s own Account Settings.

A Your subscription summary card at the top of the billing tab shows the tier (Basic or Pro) and current price for each tool the org is subscribed to. The amount shown is the price on the org’s live Stripe subscription — which may differ from today’s published price for grandfathered subscribers.

Making changes

Click any tier toggle to stage a change — staged changes don’t apply until you click Save Changes at the bottom of the tab. You can stage as many changes across as many members as you like in one go.

When you click Save Changes, the app decides what to show you next:

If the org has no active subscription — either because this is the first subscription ever or because a previous one was cancelled and the period has ended — the app opens Stripe Checkout with a Session containing exactly the changes you staged. This is the same flow described in Subscriptions and trials.

If the org already has an active or trialing subscription, the app does not send you to Checkout. Instead it opens a confirmation modal that previews the change: what you are adding, what you are removing, the proration Stripe will apply to the current invoice, and the next invoice total. You confirm or cancel. Confirming calls the modify endpoint directly — no second card entry, no second Checkout.

The preview endpoint is a pure read from Stripe’s upcoming-invoice simulator — it doesn’t mutate anything. Closing the modal without confirming leaves the subscription exactly as it was.

Path 3: Silent save (pure reassignment, no billing impact)

If your staged changes cancel out at the billing level — for example, you revoke the Web tier from Alice and grant it to Bob, leaving the total count of Web seats unchanged — the app skips both Checkout and the confirmation modal and saves directly. Nothing is charged, nothing is refunded, and the entitlement records swap instantaneously. This lets owners reshuffle access without friction as team members come and go.

The “include all tiers of changed tools” rule

One subtlety matters if you ever debug a preview that looks wrong: when building the modify payload, the client collects every tool that has a staged change, then for each changed tool it submits the complete desired state for all tiers of that tool — not just the tiers you touched.

Why: subscription items are keyed in Stripe by price ID, not by tool slug. If you only tell the backend about the Web-tier change, the API-tier item for the same tool might drift into an undefined state. By always sending the full picture for any tool you touched (and leaving tools you didn’t touch completely alone), the reconciliation is always well-defined.

In practice you will never see this rule directly — the UI stages only the buttons you click. But if the confirmation modal ever shows a line item you didn’t expect to be “changed”, it’s because you touched another tier of the same tool and the backend is about to resubmit the full per-tool state.

Proration, mid-cycle changes, and timing

Stripe handles proration automatically using its create_prorations behavior: if you add a tier mid-cycle you are billed for the remaining days at the new rate minus a credit for the unused days at the old rate. Removing a tier mid-cycle similarly credits the unused portion to your next invoice. The confirmation modal shows the net proration before you confirm.

Changes apply immediately on confirmation — entitlements are reprovisioned by the customer.subscription.updated webhook within a few seconds. If a member you just granted access to still can’t open the tool, have them refresh the page; their JWT is re-issued on next API call and picks up the new entitlement.

When the modal appears, it has three zones:

Added — tool/tier/member combinations that will start being billed. Each row shows the price per period.
Removed — combinations that will stop being billed. Each row shows the credit that will be applied.
Summary — the proration amount that will hit your current invoice immediately, and the projected next invoice total.

If the modal shows zero added and zero removed rows and only a zero summary, you staged a pure reassignment and should use Save without charging — the app will do this automatically if you confirm.

Common mistakes

Toggling a tier off and back on counts as no change, not a revoke-and-regrant. If you wanted to actually cancel and reinstate, you need to save twice.
Revoking a member’s last tier for a tool is the same as removing a paid seat. Confirm carefully — the proration credit is smaller than people expect because Stripe only credits the unused portion of the current day.
Granting the Pro tier without the Basic tier is allowed and is the right choice for automation-only seats, but such seats will see a disabled state for the tool in the browser app. If a human reports “the tool is disabled”, check whether they only have a Pro (API) entitlement.