Account Merge & Organization Transfer

⬅️ Day 6: Grow Overview

If you're building B2B SaaS in 2026 with multi-tenant architecture, you'll face two thorny edge cases: account merge (user has 2 accounts; wants to merge) and organization transfer (workspace ownership transfers; customer acquired by another company; admin leaves with org). The naive approach: never built; users contact support; manual data juggling. The structured approach: deliberate UX for each scenario, careful data model design, audit trail, security checks, customer-facing self-serve where possible. These features are rarely top of roadmap until they're urgent (acquisition, customer escalation, compliance). Plan ahead. (See multi-tenancy-chat.md for tenant architecture; workspace-tenant-switcher-chat.md for switching context.)

1. Decide which scenarios to support

Different products have different needs.

Identify scenarios.

Account merge (user-level):

User created two accounts:
- Personal email + work email
- Work email A then work email B (job change)
- Wants both in one identity

Frequency: common; especially after job changes

Solution: merge user accounts; preserve membership in workspaces

Organization transfer (workspace-level):

Owner transfer:
- Original founder leaves; team continues
- Owner role moves to another admin

M&A:
- Customer acquired; merge two workspaces
- Or: keep separate; rebrand

Customer churn / departure:
- Account owner leaves company
- Org needs new owner

Frequency: occasional but high-stakes

Solution: transfer ownership; merge workspaces; export

Workspace merge:

Two workspaces become one:
- Same company; different teams
- M&A combining tools

Frequency: rare but critical when needed

Solution: merge workspaces preserving data

Account → Workspace move:

User moves from one workspace to another:
- Job change
- Department transfer

Frequency: common in enterprise

Solution: leave workspace + join new

For [PRODUCT], output:
1. Which scenarios apply
2. Frequency estimate
3. Priority
4. Self-serve vs support
5. UI / API design

The "build for M&A scenarios early" wisdom: enterprise customers expect support for acquisition merges. Without it, you lose deals or lose customers post-acquisition.

2. Account merge — data model

User-level merge.

Design account merge.

Goal: User A + User B → User A (with all data from B)

Data model considerations:

Source of truth:
- Pick one user as "primary"
- Other user "merges into" primary

Foreign keys:
- All `user_id` references in DB
- Update from secondary to primary
- E.g., comments.author_id, files.created_by

Profile data:
- Primary user's name, avatar, etc. wins
- Or: user picks during merge

Memberships:
- User A: workspace 1, workspace 2
- User B: workspace 2, workspace 3
- After merge: workspace 1, workspace 2, workspace 3
- Dedupe: workspace 2 (was both)

Permissions:
- Per-workspace
- Higher of two (admin > member)
- Or: explicit choice

Email handling:
- Primary email stays
- Add secondary as alias (or delete)
- Either email can log in (or just primary)

OAuth / SSO connections:
- Both users' connections move to primary

Sessions / tokens:
- Invalidate secondary user's sessions
- Force re-login

Notifications:
- Combine into primary
- Re-route from secondary

Audit log:
- Record merge event
- Who initiated; when; what data merged

Schema:

users table:
- merged_into_user_id (nullable)
- merged_at, merged_by_user_id
- Soft-delete secondary user (don't hard delete; preserves audit)

If hard delete needed (GDPR):
- After grace period (90 days)
- Anonymize references (or delete cascade)

Output:
1. Schema changes
2. Foreign key migration plan
3. Profile / email handling
4. Memberships dedup
5. Audit

The "don't hard delete on merge" rule: keeps audit trail. Soft-delete with merged_into pointer; can recover if mistake.

3. Account merge UX

User-facing flow.

Build merge UX.

Trigger:

User-initiated:
- Settings → Account → "Merge accounts"
- "I have another account I want to combine"

System-detected:
- Two accounts with same email domain
- Suggest: "Looks like you have another account. Merge?"

Verification:

Verify ownership of both:
- Logged in as primary
- Verify secondary via email link
- Both must confirm

Anti-fraud:
- Don't let attacker merge into victim
- 2FA recommended on merge

Selection:

Pick primary:
- "Which account should be the primary?"
- All data flows to primary

Profile preferences:
- "Use [primary]'s name + avatar?"
- Or pick one or other

Conflict resolution:
- Both have admin role on workspace → keep admin
- Both have items with same name → user disambiguates

Preview:

Show what will happen:
- "After merge, you'll have access to: [list workspaces]"
- "These items will be transferred: [count]"
- "Email [secondary email] will become an alias"

Confirmation:

Type to confirm:
- "Type 'merge' to confirm"
- Irreversible warning

Wait state:

If long-running:
- "Merging in progress..."
- Email when done
- Background job (see background-jobs-queue-management)

Success:

Confirmation:
- "Accounts merged. You're logged in as [primary]."
- Email to both addresses

Audit:

Log merge:
- "User merged secondary account at [timestamp]"
- Visible in account history

Anti-patterns:

Auto-merge without verify:
- Security risk
- Always require both-side consent

Lose data on merge:
- Items disappear
- Trust broken

No preview:
- Surprise outcomes
- Frustration

Output:
1. Merge UI flow
2. Verification mechanics
3. Conflict resolution
4. Preview + confirmation
5. Audit logging

The "two-sided verify" rule: both accounts must confirm. Prevents takeover via merge attack. Standard security pattern.

4. Organization ownership transfer

Workspace-level: who owns it?

Implement org ownership transfer.

Triggers:

Owner-initiated:
- Owner: "Transfer ownership to [member]"
- Owner role passes; original becomes member

Admin escalation:
- Owner left company
- Other admin claims (with verification)

System-detected:
- Owner inactive 6+ months
- Suggest other admins claim

Verification:

For owner-initiated:
- Owner confirms (signed in)
- New owner accepts (must be member)
- Maybe: 2FA

For admin escalation:
- Multiple admins approve (consensus)
- Or: support team verifies + manual

Schema:

workspaces:
- owner_user_id
- previous_owner_user_id (audit)
- ownership_changed_at, changed_by

Single-owner constraint:
- One owner at a time
- Or: multiple owners (some products)

Permissions cascade:

After transfer:
- New owner: full permissions
- Old owner: defaults to admin (configurable)
- Or: old owner removed entirely

Billing implications:

Stripe subscription:
- Tied to workspace; not user
- Owner change ≠ subscription change
- New owner sees billing UI

If billing tied to user:
- Migrate billing to new owner
- Update Stripe customer

Domain:

Custom domain:
- Stays with workspace
- New owner manages

Audit:

Log:
- Old owner, new owner, timestamp
- Who initiated

Output:
1. Transfer UI
2. Verification
3. Permissions cascade
4. Billing handling
5. Audit

The "owner-leaves" enterprise scenario: original founder departs; admin takes over. Without transfer, workspace is locked to absent owner. Critical feature.

5. Workspace merge

Two workspaces → one.

Implement workspace merge.

Use case:

Acquisition:
- Company A (workspace) acquires Company B (workspace)
- Merge into Company A

Reorg:
- Two teams' separate workspaces consolidate

Customer request:
- Create-by-mistake; want one

Complexity:

This is the hardest of the three.

Considerations:

Naming conflicts:
- Both have project "Q4 Roadmap"
- Solution: prefix with original workspace name
- Or: user disambiguates

Data ownership:
- Workspace B's items become workspace A's items
- Created-by users still link

Members:
- Workspace A members + workspace B members → all in A
- Dedupe (same email)
- Permissions: higher wins

Permissions / roles:
- Roles different in each
- Reconcile (use A's role taxonomy)

Integrations:
- Each had own integrations (Slack, Salesforce)
- Decide: keep one, both (dupes), or admin reconfigures

Subscriptions / billing:
- A's subscription continues
- B's subscription cancels (or refunds)
- Plan tier matches A (or upgrade)

Custom domains:
- Pick one; redirect other
- Or: discontinue B's

Process:

Manual / supported:
- Customer requests
- Support handles
- Most companies do this manually for now

Self-serve:
- Rare; usually too complex
- Some products offer for similar workspaces

Schema:

Soft delete vs hard merge:
- Hard merge: combine into A; B disappears
- Soft: maintain both; cross-link

Most B2B: hard merge with audit log.

Anti-patterns:

Auto-merge:
- Risky; data loss
- Always involve customer

Lose context:
- Items merge but lose original workspace context
- Confusing

No undo:
- Mistake permanent
- Provide rollback (within 30 days)

Output:
1. Merge process
2. Naming conflict resolution
3. Member dedup
4. Billing handling
5. Audit + undo

The "manual-process" reality for workspace merge: most B2B SaaS does it via support tickets + custom scripts. Self-serve too risky / rare.

6. User → workspace transfer

User leaves one workspace; joins another.

User workspace transfer.

Standard scenarios:

Job change:
- User leaves Company A; joins Company B
- Should they keep their content?

Most products: User keeps their identity; loses workspace access on departure.

Admin removes user:
- User no longer on workspace
- Their content stays; reassigned

User-initiated leave:
- "Leave workspace" button
- Their content stays; reassigned to org

Handling content created by user:

Options:

Keep with original user:
- Items show "Created by [removed-user]"
- Visible to current members
- Common pattern

Reassign to admin:
- "Created by [former member; reassigned to Admin]"
- Less common

Delete:
- Items removed
- Rare; usually too aggressive

Reassign workflow:

When admin removes user:
- "Reassign their content to: [pick member]"
- Or: keep with original

User self-leave:
- Less customization
- Content stays as-is

Re-invitation:

If user leaves + rejoins:
- New membership row (or reactivate old)
- Don't lose history

Cross-workspace identity:

Same user across workspaces:
- One identity (account)
- Multiple memberships
- See workspace-tenant-switcher

Anti-patterns:

Lose user content silently:
- Workspace data missing
- Trust damage

Hard delete on departure:
- Can't recover
- For non-GDPR scenarios, soft preserve

Output:
1. Departure scenarios
2. Content handling
3. Reassignment workflow
4. Re-invitation
5. Cross-workspace identity

The "content-stays-with-org" default: most B2B treats content as org-owned, not user-owned. Departure doesn't lose data.

7. Identity considerations — SSO + SCIM

Enterprise auth complicates merge.

Identity considerations.

SSO scenarios:

User has SSO via Google / Okta / Azure:
- Merge accounts: merge SSO mappings
- New owner takes SSO admin

Org has SAML SSO:
- Owner change doesn't affect SSO config
- New owner manages

SCIM provisioning:

If org uses SCIM (auto-provisioning):
- Users provisioned by IdP (Okta / Azure)
- Merge / transfer doesn't affect external provisioning
- IdP is source of truth

Multiple SSO providers:

If user has accounts via different IdPs:
- Account 1: Google SSO
- Account 2: Microsoft SSO
- Merge: both connections preserved

Single email constraint:

If your system: one email = one user
- Merge works straightforward

If multi-email:
- Add to account
- Both can log in

Verification:

For SSO:
- Trust IdP's verification
- Don't double-verify if SAML signed assertion

For password:
- Email-link verification
- Or: 2FA

Edge case: SSO required for org

If org requires SSO:
- Member with SSO mismatch can't log in
- Owner change to non-SSO user breaks org
- Validation: ensure new owner has SSO match

Output:
1. SSO mapping merge
2. SCIM handling
3. Multi-IdP handling
4. Verification
5. Edge case checks

The SCIM auto-resolves rule: if org uses SCIM, IdP provisions; ignoring local merge. Manual SSO matters more for SMB-mid.

8. Audit + compliance

These actions need audit trails.

Audit account merges + transfers.

Events to log:

Account merge:
- Initiator user_id
- Primary user_id, secondary user_id
- Timestamp
- IP / user agent
- Items affected (count, types)

Org transfer:
- Old owner, new owner
- Timestamp
- Initiator
- Reason (optional)

Workspace merge:
- Workspace IDs
- Initiator (often support staff)
- Timestamp
- Items moved

User → workspace transfer:
- User, workspace, action (joined / left / role change)
- Timestamp

Storage:

audit_logs table:
- id, action_type, actor_user_id
- target_type, target_id
- metadata (JSON; specific to action)
- created_at

Retention:
- Keep 7 years for compliance
- GDPR / SOC 2 typical

Visibility:

Admin-visible:
- Workspace admins see workspace audit
- Personal audit visible to user

Compliance access:
- Customer requests audit
- Export available (CSV / JSON)

Anti-patterns:

No audit:
- Can't reconstruct history
- Compliance fail
- Trust gap

Audit without context:
- "User merge happened"
- Without: who, what, why
- Useless for investigation

Output:
1. Event taxonomy
2. Schema
3. Retention
4. Visibility
5. Export

The 7-year retention: SOC 2, GDPR, financial regulations all expect long retention. Don't auto-delete audits.

9. Edge cases + gotchas

Common edge cases.

Same email in both accounts:

User A email: alice@example.com
User B email: alice@example.com (typo, dupe)
- Detect at signup; prevent dupe creation
- If exists: prompt merge instead of new account

User in same workspace twice:

Edge case: shouldn't happen
- DB unique constraint on (workspace_id, user_id)
- If somehow exists: dedupe on merge

Cross-region accounts:

Account in EU (GDPR) + account in US:
- Merge implications for data residency
- Might require: keep separate; cross-link
- Or: customer chooses

Recently-deleted account:

User deleted account; later wants to recover:
- Soft delete with grace period (90 days)
- Reactivate during grace
- After: hard delete; no recovery

Subscription / billing:

User on free plan + invited to paid workspace:
- Membership doesn't affect their personal billing
- Workspace billing per workspace

User on Pro personal + joins Free workspace:
- Their personal Pro continues
- Workspace remains Free

Conflicting permissions:

Accounts with admin role in different workspaces:
- Each role stays per-workspace
- No conflict

Custom data:

Workspace-scoped:
- User profile in workspace A vs B
- Some products: same profile everywhere
- Some: per-workspace profile

Output:
1. Edge case checklist
2. Detection logic
3. Resolution per case
4. Test plan
5. Customer communication

The "test rare scenarios" discipline: most edge cases happen rarely. When they happen, they're high-stakes. Test cases for: merge, transfer, dupe email, deletion / recovery, cross-region.

10. Customer-facing communication

How do users learn about / use these features?

Communicate features to users.

Discovery:

Help docs:
- "How to merge accounts"
- "How to transfer ownership"
- Searchable + linked from settings

In-product:
- Settings → Account → "Have multiple accounts? Merge"
- Settings → Workspace → "Transfer ownership"

Support escalation:

When user contacts support:
- "I have two accounts" → docs + self-serve link
- "Owner left" → escalate to support team

Critical changes — confirm twice:

Owner transfer:
- Email to old owner: "You're transferring ownership"
- Email to new owner: "You're becoming owner"
- Both confirm

Workspace merge (manual):
- Customer requests in writing
- Support confirms scope
- Schedule maintenance window
- Execute + verify
- Customer confirms success

Reversals:

Mistake on merge:
- 30-day undo window
- After: requires support intervention (and may not be possible)

Communication after:

Email confirmation:
- "Your accounts have been merged"
- "Ownership has been transferred"
- Audit log link

Anti-patterns:

Silent execution:
- User wonders if it worked
- Always confirm

No reversal path:
- Mistake permanent
- Add grace period

Manual-only without docs:
- User can't self-serve
- Document even manual processes

Output:
1. Help docs
2. In-product discovery
3. Email confirmations
4. Reversal mechanism
5. Support escalation paths

The 30-day undo: makes risky operations less risky. User merges accounts; realizes mistake; undo within 30 days.

What Done Looks Like

A v1 account/org management system:

Add later when product is mature:

The mistake to avoid: no audit trail. Can't investigate; compliance fails.

The second mistake: hard delete on merge. No recovery; mistakes permanent.

The third mistake: single-side verification. Security risk; takeover attack.