Skip to content
BuildBase

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, <WhenUserEntitled> and useGrants, which read what a member receives, arrive with it.

{
  "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.

Before you start

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.

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 <WhenUserEntitled slug="ai-assistant">. 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:

supersedesThe member's own plan
keep (the default)Stays as it is; they keep paying for it
cancel_at_period_endSet 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.

{
  "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.

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