documenso/.agents/plans/dark-hazel-beam-swap-subscription-between-orgs.md

date, title

date	title
2026-03-04	Swap Subscription Between Orgs

Overview

Add the ability for admins to move a subscription (and its associated Stripe customerId) from one organisation to another, when viewing a user in the admin panel. The target org must be owned by the same user and must be on the free plan (no existing active subscription).

Context & Data Model

• Organisation has a 1:1 optional Subscription and a customerId (Stripe customer ID, @unique)
• Organisation has a 1:1 OrganisationClaim that tracks entitlements (team count, member count, feature flags)
• Subscription also stores a redundant customerId and has organisationId (@unique)
• When a subscription is removed from an org, its OrganisationClaim should be reset to the FREE claim
• Relationship chain: User --owns--> Organisation --has--> Subscription + OrganisationClaim

Constraints

• paid → free only: The target org must NOT have an active subscription (status ACTIVE or PAST_DUE). It must be on the free plan.
• same owner: Both source and target orgs must be owned by the same user (the user being viewed).
• The customerId must move with the subscription to the target org (cleared from source, set on target).
• The Stripe subscription object itself is NOT modified — only the DB-level mapping changes. The Stripe customer stays the same; we just reassociate it to a different org.

Implementation Plan

1. Backend: TRPC Admin Route

Files to create:

• packages/trpc/server/admin-router/swap-organisation-subscription.types.ts
• packages/trpc/server/admin-router/swap-organisation-subscription.ts

Request schema (ZSwapOrganisationSubscriptionRequestSchema):

z.object({
  sourceOrganisationId: z.string(),
  targetOrganisationId: z.string(),
});

Response schema: z.void()

Route logic (in a single prisma.$transaction):

1. Fetch source org with subscription + organisationClaim
2. Fetch target org with subscription + organisationClaim
3. Validate:
   • Source org has an active subscription (status ACTIVE or PAST_DUE)
   • Target org does NOT have an active subscription (no subscription record, or status INACTIVE)
   • Both orgs have the same ownerUserId
4. In a transaction: a. Clear customerId on source org (set to null) b. Set customerId on target org to the source's customerId c. Move the Subscription record: update organisationId to target org ID d. Copy the source org's OrganisationClaim entitlements to the target org's OrganisationClaim (originalSubscriptionClaimId, teamCount, memberCount, envelopeItemCount, flags) e. Reset the source org's OrganisationClaim to the FREE claim (using createOrganisationClaimUpsertData(internalClaims[INTERNAL_CLAIM_ID.FREE]) pattern from on-subscription-deleted.ts)

Note on ordering: Because Organisation.customerId is @unique, we must clear the source first, then set the target — or do both in a transaction that handles the constraint. Prisma transactions handle this correctly as they apply all writes atomically.

Register the route:

• Import in packages/trpc/server/admin-router/router.ts
• Add under organisation as swapSubscription
• Call path: trpc.admin.organisation.swapSubscription

2. Frontend: Dialog Component

File to create:

• apps/remix/app/components/dialogs/admin-swap-subscription-dialog.tsx

Props:

type AdminSwapSubscriptionDialogProps = {
  trigger?: React.ReactNode;
  sourceOrganisationId: string;
  sourceOrganisationName: string;
  userId: number;
} & Omit<DialogPrimitive.DialogProps, 'children'>;

Dialog behavior:

1. Opens when the trigger is clicked (from the organisations table actions dropdown)
2. Fetches the user's owned orgs via trpc.admin.organisation.find.useQuery({ ownerUserId: userId })
3. Filters to only show orgs that are on the free plan (no active subscription) and excludes the source org
4. Displays a select dropdown to pick the target org
5. Shows a warning alert: "This will move the subscription from {source} to {target}. The source organisation will be reset to the free plan."
6. On submit, calls trpc.admin.organisation.swapSubscription.useMutation()
7. On success, shows a toast, invalidates relevant queries, and closes the dialog

UI layout (following existing dialog patterns like admin-organisation-create-dialog.tsx):

• DialogHeader with title "Move Subscription" and description
• A select dropdown listing eligible target orgs (name + url)
• An Alert explaining what will happen
• DialogFooter with Cancel + "Move Subscription" buttons (submit button uses loading prop)

3. Frontend: Wire into the Organisations Table

File to modify:

• apps/remix/app/components/tables/admin-organisations-table.tsx

Changes:

• Import the AdminSwapSubscriptionDialog
• Add a new prop ownerUserId?: number to AdminOrganisationsTableOptions (needed so the dialog can query other owned orgs)
• Add a new dropdown menu item in the actions column: "Move Subscription" with ArrowRightLeftIcon from lucide
• Only render this item when the org row has an active subscription (subscription?.status === 'ACTIVE' || subscription?.status === 'PAST_DUE')
• The menu item renders inside AdminSwapSubscriptionDialog with trigger prop as the menu item

4. Frontend: Pass userId from User Detail Page

File to modify:

• apps/remix/app/routes/_authenticated+/admin+/users.$id.tsx

Changes:

• Pass ownerUserId={user.id} to <AdminOrganisationsTable> so it can forward this to the swap dialog

File Change Summary

File	Action	Description
packages/trpc/server/admin-router/swap-organisation-subscription.types.ts	Create	Request/response Zod schemas + TS types
packages/trpc/server/admin-router/swap-organisation-subscription.ts	Create	Admin mutation with prisma transaction
packages/trpc/server/admin-router/router.ts	Modify	Register route at organisation.swapSubscription
apps/remix/app/components/dialogs/admin-swap-subscription-dialog.tsx	Create	Dialog for selecting target org
apps/remix/app/components/tables/admin-organisations-table.tsx	Modify	Add "Move Subscription" action + accept ownerUserId prop
apps/remix/app/routes/_authenticated+/admin+/users.$id.tsx	Modify	Pass ownerUserId={user.id} to table

Edge Cases & Considerations

1. Stripe customer stays the same: The Stripe subscription is tied to a Stripe customer. We move the customerId to the target org, so webhook lookups (findFirst where customerId) will correctly resolve to the target org going forward.

2. @unique constraint on Organisation.customerId: Must clear source before setting target within the transaction. Prisma interactive transactions handle this correctly.

3. @unique constraint on Subscription.organisationId: Since the target org should not have a subscription record, updating the existing subscription's organisationId to the target should work. If the target has an INACTIVE subscription record, we need to delete it first.

4. Target org has INACTIVE subscription: The target org might have a stale INACTIVE subscription from a previous cancellation. In this case, delete the target's old subscription record before moving the source's subscription over.

5. Seat-based plans: If the subscription is seat-based, the Stripe quantity may not match the target org's member count. Consider calling syncMemberCountWithStripeSeatPlan after the swap as a post-transaction step.

6. OrganisationClaim transfer: Copy originalSubscriptionClaimId, teamCount, memberCount, envelopeItemCount, and flags from source claim to target claim. Reset source claim to FREE.

7. No Stripe API calls needed: This is purely a DB-level reassociation. The Stripe subscription, customer, and payment method all remain unchanged.