Skip to content

Account Deletion

View raw .md

How an account is deleted: a request that only schedules and locks it, a grace period that a sign-in cancels, and a scheduled purge that removes it for good.

On this page

Quick Reference#

Item Value
Request DELETE {prefix}/user (POST works too), auth:sanctum, answers 202.
Proof password, or a TOTP code or confirmation_token for a password-less account. A guest without a password sends no proof.
Grace period grace_days days; a sign-in during it cancels the deletion, except an orphan's, see Grace Period.
Immediate immediately: true queues the purge at once.
Purge php artisan magic-starter:purge-deleted-users; the host schedules it.
Events UserDeletionScheduled and UserDeletionCancelled.
Override SchedulesUserDeletion, ReleasesUserBilling and DeletesUsers.

Introduction#

Deleting an account is a two-step pipeline. The request only schedules the deletion and locks the account; nothing irreversible happens in an HTTP request. Once the grace period is over, the magic-starter:purge-deleted-users command deletes the account. A user who asks for an immediate deletion skips the wait: the same schedule runs and a queued job purges the account at once.

Throughout this document {prefix} is config('magic-starter.route_prefix'). The users table needs the deletion_scheduled_at and orphaned_at columns, published by add_deletion_columns_to_users_table.php, which is one of the core migrations magic-starter:install always publishes. Scheduling an account on a table without them fails with an exception that names the missing column.


Requesting Deletion#

Endpoint: DELETE {prefix}/user (POST is accepted as well)

Middleware: auth:sanctum

The caller confirms their identity with password. A password-less account uses a step-up proof instead: a TOTP code or a confirmation_token.

Success Response (202)#

json
{
  "data": {
    "deletion_scheduled_at": "2026-10-03T12:00:00.000000Z"
  },
  "message": "Your account will be deleted in 30 days. Sign in again before then to cancel the deletion."
}

The sentence tells the user how to cancel because every session was just signed out: signing in again within the grace period is the only way back.

With account_deletion.billing set to release, data also carries a billing block saying what happened to the user's subscriptions. In the default refuse mode the key is absent and the body is exactly the one above.

In one transaction, every Sanctum token of the user is revoked and every push device row is dropped, so the account stops signing in and stops ringing at once. The rows that hold the user's data stay until the purge. Scheduling an account that is already scheduled keeps the earlier date.


Immediate Deletion#

App Store Review Guideline 5.1.1(v) accepts a scheduled deletion only beside an option to delete at once. Send immediately: true in the same request:

json
{
  "password": "CurrentP@ssw0rd",
  "immediately": true
}

The request runs exactly the scheduled path: the same refusals, the same step-up proof, the same lock and stamp. Only then is a Jobs\PurgeUserNow job queued for the account, and the answer is still 202, because the deletion happens on the queue and never inside the request:

json
{
  "data": {
    "deletion_scheduled_at": "2026-10-03T12:00:00.000000Z",
    "immediate": true
  },
  "message": "Your account is being deleted. This cannot be undone."
}

A refusal or a missing proof answers as it does without the flag, and nothing is queued. A request without immediately, or with false, answers the scheduled body unchanged.

The job runs the purge command's own per-account decision with a cutoff of now, so it re-reads the account under a row lock and re-checks everything the purge does: a schedule cleared by a sign-in in the meantime is left alone, a team that gained a member un-schedules the account (or is handed on, when that is switched on), a billing subscription holds it, and the rest is deleted through DeletesUsers. It carries the account's key rather than the model, so a duplicate that runs after the account is gone does nothing.


Refusals#

A user who owns a team that deletion would damage, or whom a subscription bills directly, is refused before anything is locked. owns_shared_teams is the one refusal a host can switch off, with hand_on_shared_teams:

json
{
  "message": "You own teams that other people belong to. Hand them over or delete them before deleting your account.",
  "code": "owns_shared_teams",
  "team_ids": ["9a8b7c6d-..."],
  "errors": {
    "user": ["..."]
  }
}

The status is 422, and the client switches on code and uses team_ids to point the user at the teams to resolve. For subscription_active team_ids is empty, since the account itself is the reason.

team_has_active_subscription adds team_providers, a map from each team id in team_ids to the rail billing it, so the client can send the user to the right place:

json
{
  "message": "One of your teams has an active subscription. Cancel it first.",
  "code": "team_has_active_subscription",
  "team_ids": ["9a8b7c6d-..."],
  "team_providers": {
    "9a8b7c6d-...": "app_store"
  },
  "errors": {
    "user": ["..."]
  }
}

A value is stripe, app_store or play_store. A store is named from the team's plan_provider; anything else that refused did so on Cashier's own subscription rows and is stripe, since the provenance column is written by a webhook and can lag. The key is left out when there is nothing to name. A store subscription counts only while the team holds a paid tier, the same test HasEntitlement::entitled() answers: a plan above the free floor on a status that still grants. See Billing.

Code Cause
owns_shared_teams The user owns a team that another person belongs to. Deleting the user would take that person's data with it. Hand the team over or delete it first. A pending invitation is not a member. Never raised while hand_on_shared_teams is on.
team_has_active_subscription The user owns a team that a store subscription or a valid Stripe subscription is still billing. Cancel it first.
subscription_active The user itself is the billable subject (magic-starter.billing.billable is user) and a store or valid Stripe subscription is billing it. Cancel it first. Never raised while billing is release.
billing_release_failed Only while billing is release: Stripe refused or could not be reached while the user's subscription was being ended. Nothing was scheduled; the request can be repeated.

The Stripe check is Cashier's valid(), so a trial, a past_due dunning period and a subscription cancelled at period end all count as live until the period is over. In the default refuse mode this package never cancels a subscription for anyone; release is the opt-in that does, for the user's own subscription.


Grace Period#

The grace period is config('magic-starter.account_deletion.grace_days') (env MAGIC_STARTER_ACCOUNT_DELETION_GRACE_DAYS, default 30). 0 deletes at the next purge run with no grace period, which is not recommended for production.

Signing in during the grace period cancels the deletion, by any method: password, 2FA challenge, social login, OTP or guest. The sign-in response then carries the flag, and its message is the cancellation sentence:

json
{
  "data": {
    "user": { "..." },
    "token": "2|def456...",
    "deletion_cancelled": true
  },
  "message": "Account deletion cancelled. Your account is active again."
}

The user resource exposes deletion_scheduled_at, so a client that holds a token can tell that a deletion is pending.

An orphan is an account whose identity provider deleted it: Apple's account-deleted notification for a user with no password and no other active provider. Its deletion is scheduled without the refusals above, since nobody is left to act on them, and signing in by another method does not cancel it.


Purging#

bash
php artisan magic-starter:purge-deleted-users

The command selects every account whose deletion_scheduled_at is older than the grace period, and checks again what the scheduler checked, because the period is long enough for it to change:

Situation Outcome
The user owns a shared team (it gained a member during the grace period), and hand_on_shared_teams is off. Un-scheduled and reported. Deleting the user would take the new member's team with them.
The account owns a team that a subscription is still billing, or is itself billed by one (with billing set to release, only by a card subscription that is still valid: a store's does not hold it). Held and reported. It is left exactly as it was and retried on the next run.
The user signed in after the walk loaded them (the schedule was cleared). Cancelled: skipped without a change. The row is read again under a lock, so a sign-in that lands during the purge waits for it instead of racing the deletion.
An orphan owns shared teams, or the user does and hand_on_shared_teams is on. Each team moves to its earliest-joined admin, else its earliest-joined member, who becomes owner. Then the account is deleted.
Anything else. Deleted.

Deletion goes through the DeletesUsers contract in one transaction. The user's solo teams are deleted through DeletesTeams, so the billing guard runs on every one of them, and so are the ones they trashed, for good (a trashed team never counts as a shared one); memberships of other people's teams are detached; every linked social identity and every token is removed, and so are the user's database notifications, notification settings and newsletter subscription, together with the audit rows that describe them. A refusal part way rolls back the teams already deleted. The Apple grants are revoked and the profile photo is deleted only after the outermost transaction commits, because neither can be rolled back: a grant revoked for an account that then survives could not be restored.

Held and un-scheduled accounts are logged as well as printed, because the output of a scheduled run is usually discarded. One account failing is reported and the run moves on, and the exit code is non-zero when any failed. The last line is a tally:

text
Purge finished: 12 deleted, 1 held, 0 un-scheduled, 0 cancelled, 0 failed.

Handing On Shared Teams#

By default a user who owns a team another person belongs to cannot delete their account: the request is refused with owns_shared_teams, and the purge un-schedules a user whose team gained a member during the grace period. That is the safe answer for an application where a team is somebody's workspace. In an application where a team is a household, it is the wrong one: the person leaving is not taking the household with them.

Switch the refusal off with config('magic-starter.account_deletion.hand_on_shared_teams') (env MAGIC_STARTER_ACCOUNT_DELETION_HAND_ON_SHARED_TEAMS, default false):

php
'account_deletion' => [
    'grace_days' => 30,
    'hand_on_shared_teams' => true,
],

With it on:

  • DELETE {prefix}/user answers 202 for an owner of a shared team, and nothing changes hands yet: the team keeps its owner and its members for the whole grace period.
  • The purge moves each shared team to its earliest-joined admin, else its earliest-joined member, who becomes owner. The rule is the one an orphan's teams already follow, and it goes through TransfersTeamOwnership, so a host that rebinds that contract decides the heir's rights too. The leaving user stays on the team as an admin until DeletesUsers detaches them.
  • A team nobody else belongs to is deleted with the user, through DeletesTeams, as before. Every hand-on runs before it, in the same transaction as the deletion: a hand-on that fails rolls back the ones before it, the run reports the account as failed, and the user stays scheduled for the next run.
  • A team is read as shared when the purge runs, not when the user asked, so a member who joined during the grace period inherits like any other.

Billing is not affected. A shared team a store or Stripe subscription is still billing refuses the request with team_has_active_subscription and holds the purge, on either setting, because handing a team on does not settle who pays for it.


Releasing Billing#

By default a subscription that bills the user directly (magic-starter.billing.billable is user) refuses the request with subscription_active and holds the purge: the customer has to cancel first, and nothing is cancelled on their behalf. That is the conservative answer. An application that sells a subscription to the account, and tells the customer on its confirmation screen that deleting the account ends it, wants the other one.

Switch it with config('magic-starter.account_deletion.billing') (env MAGIC_STARTER_ACCOUNT_DELETION_BILLING, default refuse):

php
'account_deletion' => [
    'grace_days' => 7,
    'billing' => 'release',
],

A value that is neither refuse nor release raises a RuntimeException before anything is locked, rather than guessing which way a typo meant.

With release:

  • DELETE {prefix}/user is accepted for a user a subscription bills. Before the account is locked, the ReleasesUserBilling contract (default Actions\ReleaseUserBilling) ends what it can and reports the rest. It runs after every other refusal, so a refused request cancels nothing, and before the scheduler's own lock transaction, so that transaction never waits on Stripe. A caller that schedules inside a transaction of its own holds it open across the call: the Apple account-deleted handler applies its notification atomically, so a Stripe failure there rolls the whole notification back and Apple's redelivery is processed.
  • Stripe subscriptions are cancelled at once, with prorate and invoice_now off: no credit, no final invoice, and the remaining period is not refunded. This is not Cashier's cancelNow(), which prorates. Every subscription Stripe could still bill or activate goes, which includes one cancelled at the end of its period, one in dunning and one still waiting on its first payment. The local Cashier row is ended with it, rather than left valid until Stripe's customer.subscription.deleted webhook lands, so the purge of an immediate deletion is not held by the subscription its own request cancelled; the webhook then revokes the entitlement as usual. A subscription Stripe has no record of counts as ended.
  • A store subscription (App Store or Play) cannot be cancelled from here: it lives in the customer's store account. It does not stand in the way. The response names it so the client can send the person to the store's cancel screen, and the deletion goes ahead after the grace period either way.
  • A Stripe failure refuses the request with 422 billing_release_failed and locks nothing, so an account is never scheduled with its subscription still charging. The exception is reported and logged through the billing log. When a user has several subscriptions the ones cancelled before the failure stay cancelled, and repeating the request finds them ended.
  • An orphan is released too, since nobody is left to cancel for them, and a Stripe failure stops its schedule as well, so the identity provider's notification fails and is delivered again.
  • The purge and DeletesUsers no longer hold or refuse an account for the user's own store subscription. A card subscription still holds them. Neither releases anything itself (the purge holds a row lock and the deleter a transaction, and neither belongs across a remote call), so a card subscription that is still valid when they run is one the scheduler never saw: an orphan scheduled while the host still refused, which skips every refusal, an account locked by a SchedulesUserDeletion binding that does not release, a checkout completed after the lock. Deleting that user would leave Stripe charging a customer who no longer exists, so the purge holds the account and reports it, and DeletesUsers refuses with subscription_active. Scheduling it again in release mode (the admin panel's schedule action, or a new request) cancels the subscription, and the next purge deletes it. A team a store or Stripe subscription bills is not affected: it refuses the request with team_has_active_subscription and holds the purge on either setting. Under billing.billable = team the user has nothing to release.

The 202 body gains data.billing, on the scheduled and the immediate answer alike:

json
{
  "data": {
    "deletion_scheduled_at": "2026-10-03T12:00:00.000000Z",
    "billing": {
      "cancelled": [
        { "provider": "stripe", "id": "sub_1Nxyz..." }
      ],
      "store": [
        { "provider": "app_store", "manage_url": "https://apps.apple.com/account/subscriptions" }
      ]
    }
  },
  "message": "Your account will be deleted in 7 days. Sign in again before then to cancel the deletion."
}
Field Meaning
billing.cancelled Each subscription ended now: its provider (stripe) and the rail's id.
billing.store Each store subscription still billing, which the user has to cancel there: its provider (app_store or play_store) and the manage_url the store gave for it, null when it gave none.

Both lists are empty for a user nothing bills. A store subscription counts only while the user holds a paid tier, the test the team deletion guard applies.

Signing in during the grace period cancels the deletion as always, but a subscription cancelled by the release stays cancelled: the customer can subscribe again. Nothing restores the store's.

To end a rail this package does not know, or to add a step (a CRM, a refund), bind your own ReleasesUserBilling; the scheduler only reads the report it returns.


Scheduling the Purge#

The package registers the command and does not schedule it. Without a schedule line, nothing is ever deleted. Add one in routes/console.php:

php
use Illuminate\Support\Facades\Schedule;

Schedule::command('magic-starter:purge-deleted-users')->daily();

Daily is enough: the grace period is counted in days.


Lifecycle Events#

The package locks only what it owns. A host that runs work on the user's behalf (scheduled jobs, monitors, outgoing webhooks) pauses and resumes it on two events:

Event Dispatched Properties
Events\UserDeletionScheduled After the schedule commits: a user's request, an immediate one, or an orphan's. user, immediate (true when the purge was queued at once)
Events\UserDeletionCancelled When a sign-in during the grace period clears the schedule, and when the purge un-schedules an account whose team gained a member. user
php
use AnilcanCakir\MagicStarter\Events\UserDeletionCancelled;
use AnilcanCakir\MagicStarter\Events\UserDeletionScheduled;
use Illuminate\Support\Facades\Event;

Event::listen(UserDeletionScheduled::class, fn (UserDeletionScheduled $event) => /* pause */);
Event::listen(UserDeletionCancelled::class, fn (UserDeletionCancelled $event) => /* resume */);

UserDeletionScheduled fires again when an already scheduled account is scheduled once more, such as a provider notification delivered twice, so keep the listener idempotent. A deleted account fires no event of its own: its rows go with it through DeletesUsers.


Team Deletion Guard#

DeletesTeams is bound to Actions\SubscriptionGuardedDeleteTeam. It refuses to delete a team while either payment rail is billing it, for both DELETE {prefix}/teams/{team} and the purge:

  • a store subscription lives in the customer's App Store or Play account, which the application cannot cancel, so the owner has to cancel it there;
  • a Stripe subscription that Cashier reports as valid(), through the grace period of a cancelled one.

Each rail refuses with its own sentence, as a 422 validation error on the team field. The guard runs before the parent action detaches any member, so a refused team is left whole.


Customization#

Both halves are contract bindings, so a host can swap either:

Contract Default action Role
SchedulesUserDeletion Actions\ScheduleUserDeletion Refuses, releases billing when configured, locks and stamps the account, and queues PurgeUserNow for an immediate deletion. Returns the billing report.
ReleasesUserBilling Actions\ReleaseUserBilling Ends the card rail's subscriptions and reports the store's, when billing is release.
DeletesUsers Actions\DeleteUser The irreversible end, run by the purge.

See Action Contracts for how bindings work.

Gotchas#

Mistake Fix
Not scheduling magic-starter:purge-deleted-users The package registers the command and does not schedule it, so nothing is ever deleted. Add Schedule::command('magic-starter:purge-deleted-users')->daily().
Running an immediate deletion on the sync queue The purge then runs inside the request and a large team cascade can outlast it. Run a real queue worker.
Scheduling a deletion before the columns exist deletion_scheduled_at and orphaned_at ship in a core migration; without them scheduling throws and names the missing column.
Looking for a cancel endpoint There is none. A sign-in during the grace period cancels the deletion.
Writing a non-idempotent UserDeletionScheduled listener The event fires again when an already scheduled account is scheduled once more.
  • Profile: the user endpoint in the profile reference.
  • Social Login: the step-up proof a password-less account sends.
  • Teams: handing on a shared team and restoring one.
  • Billing: what releasing billing does to a subscription.
  • Action Contracts: SchedulesUserDeletion, ReleasesUserBilling and DeletesUsers.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.