Agency offboarding (staged exit)

Unpaid invoice lock (see [Wholesale & billing](/help/agency-wholesale-billing)) suspends agency staff first, then may pause clients after +7 days. Paying reverses it.

Offboarding is an irreversible disposition of the partner relationship: every client is transferred to direct billing or suspended with an audit trail, then the agency is cancelled and marked inactive. Do not treat unpaid `agency_invoices` as offboarding, and do not only flip `billing_status = cancelled` without running this flow.

Who can run it: platform admins only. Partner agency staff cannot start or complete offboarding from `/dashboard/agency`.

1. Sign in as a platform admin.
2. Go to Admin → Whitelabel (`/dashboard/admin/whitelabel`).
3. Open the partner agency, then choose Offboarding (also linked from the whitelabel list).

Direct URL: `/dashboard/admin/whitelabel/[agencyId]/offboard`.

The page loads state from `GET /api/admin/agency/offboarding` and a reconciliation report from `GET /api/admin/agency/offboarding/reconciliation`. Actions post to `POST /api/admin/agency/offboarding`.

Blocked agencies (Start offboarding is refused):

| Guard | Why | | --- | --- | | `is_default` | Platform default agency cannot be offboarded | | `billing_mode = platform_internal` | Actonia / internal — never billed via wholesale offboarding | | `billing_mode = external_quotes` | Enterprise direct (e.g. TFG) — not the wholesale offboarding path |

Save a new agency first before opening Offboarding (`…/offboard` on `new` is not valid).

On the offboarding page, under 1. Initiate:

1. Set Grace days (default 30, minimum 7, maximum 365).
2. Click Start offboarding.

That stamps `offboarding_started_at` and `offboarding_grace_until`. The agency and its clients stay fully working and the partner continues to be invoiced until you complete. Initiate does not suspend clients or cancel the agency.

Status cards show stage (In progress), grace until (with days left), and how many clients are still undecided.

Under 2. Disposition each client, decide every linked organisation before Complete. Clients are never deleted.

Optional transfer defaults (apply when you click Transfer):

• Transfer plan — retail `plan_code` (defaults to the agency’s `default_client_plan_code`, else `PLN_growth_01`)
• Stamp retail trial — opt-in checkbox; default off (only tick if commercially agreed)

| Action on the row | Outcome code | What happens | | --- | --- | --- | | Transfer to direct | `transfer_direct` | Clears `managing_agency_id`, sets retail plan / `billing_settings`, unsuspends if needed, notifies the client from ProfilePilot. Trial stamps only when the checkbox is on. | | Suspend | `suspend` | Sets `is_suspended` with `suspended_reason = agency_offboarding`, keeps data and `managing_agency_id` for audit |

Rows already suspended for offboarding show Decided · suspend. Other suspensions still need an explicit Transfer or Suspend disposition.

Complete is blocked while any client remains undecided (`undecidedCount > 0`). A transferred client must not keep `managing_agency_id`, or access/billing checks can leave them incorrectly free against an inactive agency.

Under 3. Complete, when undecided clients are 0 and the agency is still active:

1. Confirm the dialog — this is not reversible via unpaid-invoice restore.
2. Click Complete offboarding.

That sets `billing_status = cancelled` and `is_active = false`, then issues a final pro-rata wholesale `agency_invoices` row for the partial month (may be skipped with a reason when there is nothing to bill). Agency staff lose access to all clients once cancelled — expected.

Reconciliation report on the same page lists orgs still pointing at an inactive/cancelled agency without an intentional `agency_offboarding` suspension. A clean offboarding yields No problem rows.

Suspended clients retain data. Restoring a commercial relationship later is a new onboarding conversation — not the unpaid-invoice restore path.