Skip to main content

​
Organization suspension and deletion lifecycle

The tenant provisioning lifecycle covers how an organization comes into being. This page covers the opposite end: the three ways an organization stops sending — an administrative suspend, a billing-driven pause, and tenant-initiated deletion — and the teardown sequence a full deletion runs through before the tenant schema is dropped.

​
Triggers: suspend vs pause vs delete

Three distinct trigger classes degrade an organization, and they do not compose: pausing and deletion do not run dunning, and a suspend is not a billing state.
  • Billing pause. The balance monitor flips outboundPaused = true as your wallet approaches zero, a billing threshold you configured trips, or a spending alert routes the account into pause. Paid outbound rejects with a SENDING_PAUSED/SENDING_BLOCKED (402) until the wallet recovers; the $0-channel carve-out (WhatsApp, Telegram, LINE, Push, web widget) may still send. The pause gate and its free-channel exemption are covered on the outbound pause gate page; rollback and recovery are on outbound pause recovery.
  • Administrative suspend. An operator with the admin tenant plane marks the organization, which the platform renders as subscription_status='suspended'. A fraud-console suspend does the same thing through a different surface. Either route sets outbound_paused so the hold blocks every channel — the free-channel exemption that a balance pause gets is deliberately not honored on a suspension.
  • Tenant-initiated deletion. Closing your account is not a cancelling→cancelled Stripe flow; it is an ordered teardown of the tenant plane, entry-pointed from the dashboard, the organization endpoint, or a Clerk webhook delete-receive. Deletion marks the organization subscription_status='deleted' and runs the sequence below.
The dunning counter is a separate model with its own page — the dunning lifecycle model. Dunning is the three-strike payment-failure counter behind an auto-freeze: it owns the payment_failed counter, the card-update-never-clears rule, and the successful-payment recovery. The three triggers above never advance the dunning counter; dunning_failed_3x is one of the account-lifecycle hold reasons, not the source of suspension here.

​
Suspension: the filter semantics

Operator surfaces can show you only the live roster or only the suspended cohort, because the admin tenants list filter resolves suspended and not_suspended at the SQL layer:
  • suspended — rows whose subscription_status = 'suspended', which includes admin and fraud-console suspends.
  • not_suspended — every effective status except suspended. A fraud-console suspend routes through the same hold as an admin suspend, and both are excluded together.
Client-side filtering would leak the suspended cohort onto page 2+ under keyset pagination, so the filter lands in the WHERE clause and the full set is scoped per request. A cancelling or past_due tenant is not suspended and passes the not_suspended filter. The suspend/resume actions live on the operator plane; nothing in the tenant’s own dashboard can self-suspend or self-restore. See operator vs admin plane for the two-plane split.

​
Deletion: the ordered teardown

A deletion is a sequence, not a single DELETE, and the order is the safety story — in-flight work drains before the schema goes:
  1. Drain in-flight webhook jobs. Queued webhook deliveries are cancelled so no delivery lands against a tenant whose webhook endpoint is about to disappear.
  2. Cancel campaigns. Every campaign row not already terminal flips to cancelled so the scheduler never dispatches a send against a closing organization.
  3. Cancel drip enrollments. In-flight journey enrollments are cancelled in the same sequence as the campaigns they feed.
  4. Purge org-scoped shared rows. Rows on the shared catalog that reference your organization — SIP credentials, Telegram bot credentials, SIP devices, hot-desk sessions, custom domains, voicemail boxes, inbound routes, per-user call-handling views, and API keys — are removed before the tenant schema drop. A soft delete alone would leave these children alive; the explicit purge is what stops a registered softphone or the Telegram webhook-health sweep from reviving a deleted org.
  5. Soft-delete the organization row. The organization record is marked deleted and its subscription status flips to deleted, so every status-gated guard refuses the organization immediately.
  6. Drop the tenant schema. The per-tenant database schema is dropped, so the tenant-plane data dies exactly once.
Every completed deletion returns a structured summary — counts of returned numbers, campaigns cancelled, enrollments cancelled, and webhook jobs drained — and each step writes an audit row into the tamper-evident chain before the schema drop, so a deletion is never a silent wipe.
Two always-on guards backstop the runtime edges the purge misses:
  • SIP registration and outbound dial authorization join back to the organizations catalog and reject with a recorded org_deleted reason when the owning organization is soft-deleted, so a registered device loses telephony at organization death rather than at credential expiry.
  • The Telegram webhook-health sweep excludes organizations whose row is soft-deleted, so a deleted tenant’s bot stops re-registering its webhook.

​
What a tenant can and cannot undo

Deletions run through a restore-safe path only for the early steps:
  • Drain, campaigns, and enrollments — recoverable in principle until the shared-row purge lands; the drain-and-cancel step is there so you can confirm the organization before teardown.
  • Shared-row purge and schema drop — one-way. The purge and drop are the point of no return; a support reviewer may manually re-provision numbers and webhooks, but the rows do not come back.
  • The organization record itself — marked deleted blocks every status-gated read path; un-deleting is a support action, not a dashboard toggle, and it does not re-derive the dropped schema.
If you did not intend to delete, reach support before the purge step runs. The audit rows in the sequence are the forensic timeline support uses.

​
GDPR and residency interaction

Deletion composes with the retention and residency planes:
  • Retention windows. Scheduled GDPR erasure uses the same ordered teardown that a manual close initiates; see retention windows and deletion for the per-data-class windows and the WORM export lane.
  • Residency pin. The tenant schema drop removes the data regardless of which region it was pinned to; the data placement and residency page covers what the pin governs while the organization is live.
  • GDPR posture. CDP retention windows and the tenant compliance defaults govern what you can configure; deletion is the endpoint those controls defer to.

​
Operator vs admin split

Suspension and deletion live on different planes:
  • Tenant plane. You trigger deletion through your dashboard, your organization endpoint, or an identity-provider delete webhook; a tenant never sees the suspended filter.
  • Operator plane. The admin console roster filter (suspended / not_suspended), the fraud-console suspend action, and restore review. Read operator vs admin plane to see how those routes are separated from tenant credentials and audited.

​
Cross-references