# Family and Group Plans Sell one plan that a manager pays for and every member of the group benefits from, each on their own account. A family plan is a workspace plan. The family is a workspace, the person who pays is its owner, and everyone they invite is a member. What makes it a family plan rather than a team plan is what each member gets on their own account: the plan grants every member a personal item, and it follows them into every workspace they open for as long as the family pays. > **Note:** **Requires `@buildbase/sdk` 1.0.0 or later.** `useEntitlement`, `useLimit`, `` and `useGrants`, which read what a member receives, arrive with it. ```json { "memberGrants": [ { "itemSlug": "ai-assistant", "itemKind": "feature", "quantity": 1 }, { "itemSlug": "storage-gb", "itemKind": "limit", "quantity": 50, "supersedes": "cancel_at_period_end" } ], "ownerGrants": [ { "itemSlug": "priority-support", "itemKind": "feature", "quantity": 1 } ] } ``` That block sits on the family plan's version. `memberGrants` names user-scope items, the ones a personal plan sells, and publishing refuses an item of any other scope. > **Note:** The family plan lives in a workspace pricing group (`"payerType": "workspace"`, the default), and the items it grants are declared with `"scope": "user"`. See [Plans for users vs plans for workspaces](/billing/users-and-workspaces). ## What a member receives Each grant is written on the member as a sponsored grant, with the workspace as its sponsor, when the plan is assigned and whenever someone joins. It goes when they leave, and follows the sponsor's plan through every change: an upgrade, a downgrade at the end of the period, a pause, a failed payment, a cancellation. - **Features and limits are a floor.** A member who already has 100 GB on their own plan keeps 100 GB; the family's 50 never stacks on top of it, and never lowers it. - **Quotas add.** A quota granted to members is added to whatever their own plan includes. - **Two families never stack.** A person in two workspaces that both grant the same item keeps the more generous of the two. Read it with the user subject, as any personal entitlement: `useEntitlement('ai-assistant', { subject: { user: true } })`, or gate with ``. Where the grant decided the answer, its `source` reads `floor` (or `add` for a quota) rather than `plan`. To say "included with your family plan", list the person's grants with `useGrants({ user: true })`: the row carries `source: "plan_grant"` and the workspace that pays as its `sponsor`. ## A member who already pays `supersedes` on a member grant says what happens to a member's own personal plan when the family grant duplicates it: | `supersedes` | The member's own plan | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `keep` (the default) | Stays as it is; they keep paying for it | | `cancel_at_period_end` | Set to cancel at the end of the period they paid for, which they can undo until then. A member already cancelling, or on Free, is left as they are | ## Who pays and who manages The owner holds `workspace:billing:manage`, so they are the one who changes the plan and the card. Who else sees billing is up to the roles you give members: `workspace:billing:view` reads it. Add billing contacts on the workspace if invoices should go to someone else. ## Shared and personal allowances A quota marked `perMember` gives each member their own allowance every period, while the workspace still counts the total. With `fallback: 'pool'` and a `poolIncluded`, a member who spends their own draws on a shared pool next; with `fallback: 'none'` they stop at their own. ```json { "quotas": { "ai-messages": { "perMember": true, "fallback": "pool", "poolIncluded": 500, "monthly": { "included": 200 } } } } ``` `useLimit('ai-messages', { member: true })` reads the signed-in member's own allowance against the pool. Read a per-member quota for one member. On the REST API that is `GET /api/v1/public/workspaces/:workspaceId/quotas/:slug?member=1`, which adds the signed-in member's `member` standing. Without `?member=1` the line is the workspace's: its `included` is one member's allowance and its `usage` is every member's together, so its `available` is not what any one member has left, and the line says so with `perMember: true`. A per-member quota never bills overage on the workspace line. ## How many members `maxMembers` on the family plan's version caps how many people hold the member grants at once. Set it, and optionally `memberChangeCooldownDays`, on a draft version through the admin API; like `memberGrants`, both are fixed once the version is published. ```bash curl -X PATCH https://api.console.buildbase.app/api/subscriptions/plans/$PLAN_ID/versions/$VERSION_ID \ -H "Authorization: $BUILDBASE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"maxMembers": 6, "memberChangeCooldownDays": 30}' ``` At `maxMembers: 6` the owner comes first, then those already holding a place, earliest first, then members in the order they joined, until six hold one. A seventh person can still join the workspace; they hold no member grants until a place frees, and then they get them without asking. Lowering the cap ends the places of the latest to get one. The owner's own `ownerGrants` are never capped. `memberChangeCooldownDays` stops a family from rotating one place around a circle of friends. A place a member gives up stays theirs for that many days: it is not handed to the next person, and it is theirs again if they come back inside the window. A cooldown needs `maxMembers`; one without the other is refused. To refuse the seventh invitation outright instead, cap the workspace's seats with the plan's `maxSeats`: a pending invitation holds a seat until it is accepted or revoked. ## Next steps - [Plans for users vs plans for workspaces](/billing/users-and-workspaces) - The rules behind personal grants. - [Add-ons](/billing/add-ons#grants-and-how-they-compose-with-the-plan) - How a grant composes with the plan, and `useGrants`. - [Entitlement checks](/billing/entitlements) - Reading a grant's `source`. - [Invitations](/workspaces/invitations) - Adding members to the family.