VibeWeek
Home/Grow/Sub-Account & Parent-Child Organization Hierarchy: Chat Prompts

Sub-Account & Parent-Child Organization Hierarchy: Chat Prompts

⬅️ Back to 6. Grow

When you start selling to enterprise customers, "an account is a workspace" stops working. A real enterprise customer might be: parent company with 12 subsidiaries; each subsidiary has 3 departments; each department has multiple teams. Traditionally you sold to one team at $50K/yr; now the parent wants a master agreement covering all subsidiaries with consolidated billing, shared SSO, cross-org visibility for executives, but separated operational data per subsidiary. Without sub-account hierarchy, you're stuck: each subsidiary signs separately (creates 12 mini-deals); cross-org reporting is impossible (have to manually combine data); SSO doesn't span (each org configured separately); billing is fragmented.

This is multi-level multi-tenancy. Distinct from multi-tenancy (basic tenant isolation) and workspace-tenant switching (UI for switching). It's the data model + permission model + billing model that supports enterprise customers with hierarchical org structures.

When This Belongs

Use sub-account hierarchy when:

  • You sell to enterprise customers (>$50K ACV)
  • Customers have legal subsidiaries / business units / multi-level structures
  • Master Service Agreements (MSAs) span multiple operating entities
  • Consolidated billing / cross-org reporting is a sales requirement
  • SSO / IdP integration spans the parent

Don't bother when:

  • SMB / self-serve only
  • Single-team usage pattern
  • No demand for multi-org consolidation

Building this prematurely is a common architecture mistake. Wait until enterprise demand is real.

Architecture: Hierarchy Models

Three common shapes:

Shape 1: Flat — All Workspaces are Peers

Workspace A
Workspace B
Workspace C

This is most B2B SaaS default. No hierarchy. Each workspace independent.

Shape 2: Two-Level — Org → Workspaces

Acme Corp
├── Acme Sales Workspace
├── Acme Marketing Workspace
└── Acme Support Workspace

The most common enterprise pattern. Add an "Organization" layer above workspaces. Most enterprise needs solved by 2-level.

Shape 3: Multi-Level — Org Tree

Acme Holdings
├── Acme USA
│   ├── Acme USA Sales
│   ├── Acme USA Marketing
│   └── Acme USA Support
├── Acme EU
│   ├── Acme UK Sales
│   └── Acme DE Sales
└── Acme APAC
    └── Acme JP Operations

Multi-level (3+) tree. Useful for very large enterprises. More complex; more tradeoffs.

For most B2B SaaS that need hierarchy, Shape 2 (Org → Workspaces) is right. Don't over-engineer Shape 3 until 5+ enterprise customers need it.

Data Model

I'm building parent-child organization hierarchy for my B2B SaaS at $5M+ ARR.

Schema (Drizzle):
```sql
organizations:
  id, parent_org_id (nullable; for tree structure),
  name, slug, type (enum: 'org' | 'workspace' | 'team'),
  created_at, deleted_at,
  billing_entity_id (FK if this org is the billing entity OR points to a parent that bills),
  metadata (JSON)

org_relationships:
  parent_id, child_id, relationship_type (enum: 'child' | 'managed' | 'shared'),
  created_at
  -- Allows alternative graph structures beyond strict tree

workspace_data:
  -- Existing workspace tables; add org_id FK so each workspace points up
  
org_billing:
  org_id, plan, seats, billing_cycle, invoice_settings, payment_method_id,
  cascade_billing (boolean: bills children to this entity)

org_admins:
  user_id, org_id, role (enum: 'super_admin' | 'org_admin' | 'workspace_admin' | 'member')

Implement:

  • The schema
  • Helper functions: getDescendants(orgId), getAncestors(orgId), canUserAccess(user, org)
  • Recursive queries (Postgres CTE for tree traversal)
  • Constraints: prevent circular references; max-depth limit (5-10)

Stack: Next.js + Drizzle + Postgres.


## Permission Model

The hardest part. Multi-level permissions get complex fast.

Implement role-based access control across the hierarchy:

Roles per org level:

  • Super Admin: full access to org + all descendants
  • Org Admin: full access to this org + designated descendants
  • Workspace Admin: full access to this workspace only
  • Member: per-workspace access based on workspace roles

Permission resolution:

  • User's permissions = max of (their direct grant + inherited grants from ancestor orgs)
  • Resolve at request time; cache for performance
  • Always check the most specific role first

Cross-workspace visibility:

  • Users with Org Admin role on parent see all child workspaces (read-only or full?)
  • Users with Workspace Admin on Workspace A don't automatically see Workspace B
  • Cross-workspace dashboards: aggregate views available to org-level admins

Edge cases:

  • User has Org Admin on Acme USA AND Workspace Admin on Acme APAC: combined permissions
  • User removed from parent org: do they lose access to child workspaces? (Usually yes)
  • User in workspace whose parent org is deleted: handle gracefully

Implement permission check middleware that respects hierarchy.

Stack: Next.js + Drizzle + custom RBAC.


## Billing Across Hierarchy

Implement billing options for hierarchical orgs:

Option A: Bill each leaf workspace separately

  • Each workspace has its own subscription
  • Independent billing cycles + payment methods
  • Simple but no consolidation
  • Pros: simple; existing customers easy to migrate
  • Cons: enterprises hate fragmented invoicing

Option B: Bill at org level, distribute to children

  • Parent org has the subscription + payment method
  • Children share parent's subscription (counted in seats)
  • Single invoice consolidating all usage
  • Pros: enterprise-friendly
  • Cons: per-workspace cost visibility lost

Option C: Hybrid — flexible billing entity per branch

  • Each org node can be a billing entity OR inherit from parent
  • Flexible: parent bills for some children, others billed separately
  • Most enterprise-realistic but most complex

Implementation:

  • billing_entity_id on each org points to where it bills (self or ancestor)
  • Aggregation: sum usage from billing-entity org down through descendants
  • Invoice line items by branch / department for transparency
  • Cross-currency: bill at parent's currency; child usage converted

Use cases:

  • "We have a master agreement; all sub-orgs share it" → Option B
  • "Each subsidiary has its own budget" → Option A
  • "Most subs share; one is independent" → Option C

Pick Option B as default for enterprise; offer Option C for sophisticated needs.

Stack: Next.js + Stripe + Drizzle.


## SSO + Identity Federation

Implement SSO that spans the hierarchy:

Pattern A: Org-level SSO

  • Parent org configures one SAML / OIDC provider
  • All users from any descendant workspace authenticate via parent's IdP
  • IdP groups → role mappings within orgs

Pattern B: Per-workspace SSO with parent fallback

  • Each workspace can configure its own SSO
  • Parent's SSO is fallback if workspace doesn't have own

Pattern C: SCIM provisioning at org level

  • Parent's IdP provisions users
  • Users auto-assigned to workspaces based on IdP groups
  • Removes user when removed from IdP

Most enterprise customers want Pattern A or C.

Implementation:

  • WorkOS or Auth0 for SAML / OIDC handling
  • WorkOS Directory Sync (SCIM) for IdP-driven provisioning
  • SSO config stored at org level; inherited by descendants unless overridden
  • Cross-org user assignment via IdP group → role mapping table

Stack: Next.js + WorkOS or Auth0 + Drizzle.


## Cross-Org Reporting + Visibility

Build cross-workspace dashboards for org admins:

Use cases:

  • "Show me total spend across all workspaces under Acme Corp"
  • "Compare adoption metrics across departments"
  • "Aggregate user activity for this division"

Implementation:

  • Dashboard component that takes an org ID
  • Queries aggregate data from all descendant workspaces
  • Role check: only org-level admins can see cross-workspace data
  • Performance: pre-aggregate via materialized views or scheduled jobs

UX:

  • Org switcher at top (shown only to multi-org users)
  • Filter by org branch
  • Per-workspace drill-down

Privacy:

  • Some descendants may be regulated / segregated; respect data residency
  • Some customers don't want cross-org visibility (compliance / org-design choice)
  • Make cross-org visibility opt-in per org

Stack: Next.js + Drizzle + Postgres.


## Migration Path: Adding Hierarchy to Existing Data

If you didn't build hierarchy from day 1, migrating existing customers is painful.

Plan migration from flat workspace model to hierarchical:

Phase 1: Add organizations table (above workspaces)

  • Each existing workspace gets an implicit "auto-org"
  • Auto-org has same name as workspace
  • Backwards compatible: workspace.org_id always exists

Phase 2: Allow customers to opt into multi-workspace orgs

  • Self-serve UI: "Add another workspace to this org"
  • Enterprise customers: support-led migration

Phase 3: Cross-workspace features available for hierarchical customers

  • Reporting; SSO; billing — only shown for orgs with >1 workspace

Migration mechanics:

  • Existing customer with 3 separate workspaces wants to merge under one parent
  • Operations: create parent org; reassign workspaces; merge billing; preserve data
  • Communication: customer-facing migration UX explaining changes

Edge cases:

  • Customer's billing was via Customer A (workspace 1); now merged to org C; payment methods + invoices need migration
  • User permissions: simple in flat model; complex in hierarchy. Default to most permissive

Stack: Next.js + Drizzle + careful migration scripts.


## Common Pitfalls

**Building hierarchy too early.** Adding it before enterprise demand creates complexity. Stay flat until real enterprise customers need it.

**Building hierarchy too deep.** Supporting 10-level trees when 2 levels would suffice. Cap at 3-5 levels.

**Permission inheritance unclear.** "Does parent admin see child data?" — different customers have different expectations. Make explicit + configurable.

**Billing not aligned with org structure.** Customer wants single invoice; you bill per workspace. Sales loses deals over this. Build flexible billing.

**Cross-workspace queries slow.** Recursive Postgres queries on hierarchy without indexing = slow at scale. Index path or use materialized views.

**Circular references possible.** Org A is parent of Org B which is parent of Org A. Database constraints + validation.

**SSO config fragmented.** Each workspace has its own SSO; user has 5 logins. Org-level SSO is the right pattern.

**Migration without communication.** Customers' data structure changes overnight; they panic. Communicate; make optional / phased.

**Sub-account creation by anyone.** Random employee creates 50 sub-accounts. Cap creation to admins.

**Billing confusion across hierarchy.** Customer doesn't know who pays for what. Clear UX showing billing structure.

**Cross-org admin power abuse.** Org super-admin has access to all data; insider risk. Audit log + tiered admin roles.

**Reporting that exposes other branches.** Marketing manager at Acme USA sees Acme Japan data they shouldn't. Strict permission filtering.

**Currency mismatch in cross-org reporting.** Parent in USD, children in EUR/GBP/JPY; aggregations confused. Convert + display clearly.

**No way to leave the hierarchy.** Subsidiary spins out; can't separate from parent org. Build org-detachment flow.

**Performance issues with deep trees.** Querying "all descendants of root" for a 5-level tree with 1000 nodes = slow. Pre-compute or use closure tables.

**Audit logs not propagated.** Action in child workspace; parent admin can't see in their audit log. Aggregate audit at org level.

**Slug / URL conflicts.** Two workspaces in different orgs both want slug "marketing". Namespace by org or use UUIDs.

**Onboarding confusion.** New user signs up; doesn't know which workspace under which org they're in. Clear onboarding showing structure.

**No guard against hostile child orgs.** Bad-actor child org disrupts parent operations. Per-child rate limits + isolation.

**Forgetting cross-tenant data leak risks.** Reporting query joins across orgs and accidentally exposes another tenant's data. Default-deny + audit.

**No "demote" / "split" path.** Org gets demoted; complex transition. Plan for org-graph changes over time.

## What Done Looks Like (Recap)

You've shipped sub-account hierarchy when:

- Data model supports parent → workspaces (or deeper if needed)
- Permission model resolves across hierarchy with clear inheritance
- Billing supports per-org or per-workspace flexibly
- SSO can span the hierarchy via org-level config
- Cross-org reporting available to authorized admins
- Migration path for existing flat customers
- Performance tested at expected enterprise scale (1000+ workspaces under one org)
- Audit logs aggregate across hierarchy
- UI clearly shows org structure

## Mistakes to Avoid

- Building hierarchy too early
- Trees too deep (>5 levels)
- Permission semantics unclear
- Billing fragmentation hurting enterprise sales
- Cross-workspace queries unindexed
- Circular references possible in data
- SSO fragmented across workspaces
- Migration without customer communication
- Sub-account creation unrestricted
- Cross-org data leak via reporting
- Currency conversion sloppy
- Organization detachment impossible
- Performance issues at depth
- Audit logs scoped too narrowly
- Slug / URL conflicts unhandled
- Privacy / compliance overlooked across branches

## See Also

- [Multi-Tenancy](./multi-tenancy-chat.md)
- [Workspace / Tenant Switcher](./workspace-tenant-switcher-chat.md)
- [Workspace Templates / Cloning](./workspace-templates-cloning-chat.md)
- [Workspace Branding / Custom Domains / White-Label](./workspace-branding-custom-domains-white-label-chat.md)
- [Roles & Permissions](./roles-permissions-chat.md)
- [SSO / Enterprise Auth](./sso-enterprise-auth-chat.md)
- [Account Merge / Org Transfer](./account-merge-org-transfer-chat.md)
- [Audit Logs](./audit-logs-chat.md)
- [Customer Notes & Internal Annotations](./customer-notes-internal-annotations-chat.md)
- [Customer Reports & Scheduled Exports](./customer-reports-scheduled-exports-chat.md)
- [CSV / Data Export Patterns](./csv-data-export-patterns-chat.md)
- [Plan Upgrade, Downgrade & Mid-Cycle Billing Changes](./plan-upgrade-downgrade-billing-changes-chat.md)
- [Localized Pricing per Region](./localized-pricing-per-region-chat.md)
- [Quotas, Limits & Plan Enforcement](./quotas-limits-plan-enforcement-chat.md)
- [Account Suspension & Fraud Holds](./account-suspension-fraud-holds-chat.md)
- [Approval Workflows & Multi-Step Routing](./approval-workflows-multi-step-routing-chat.md)
- [Sandbox & Test Mode for SaaS APIs](./sandbox-test-mode-saas-apis-chat.md)
- [Custom Email Domain & White-Label Sending](./custom-email-domain-white-label-sending-chat.md)
- [Internal Admin Tools](./internal-admin-tools-chat.md)
- [Database Sharding / Partitioning](./database-sharding-partitioning-chat.md)
- [Data Residency / Region Pinning](./data-residency-region-pinning-chat.md)
- [Customer Managed Encryption Keys (BYOK)](./customer-managed-encryption-keys-byok-chat.md)
- [Settings & Account Pages](./settings-account-pages-chat.md)
- [Sidebar Navigation Implementation](./sidebar-navigation-implementation-chat.md)
- [Auth Providers (VibeReference)](https://viberef.dev/auth-and-payments/auth-providers.md)
- [Authentication (VibeReference)](https://viberef.dev/auth-and-payments/authentication.md)
- [Customer Segmentation & Tiering (LaunchWeek)](https://launchweek.dev/content/4-convert/customer-segmentation-tiering.md)
- [Strategic Account Planning (LaunchWeek)](https://launchweek.dev/content/4-convert/strategic-account-planning.md)
- [Buying Committee Navigation (LaunchWeek)](https://launchweek.dev/content/4-convert/buying-committee-champion-development.md)
- [B2B Procurement Navigation (LaunchWeek)](https://launchweek.dev/content/4-convert/b2b-procurement-navigation.md)
- [Annual Contract Negotiation (LaunchWeek)](https://launchweek.dev/content/4-convert/annual-contract-negotiation.md)