Migrate GA4 User Deletion to the Admin API

User deletion is a consequential data operation, not a routine SDK upgrade. Confirm the organization's approved request intake, identity verification, property ownership, retention obligations, and legal review before changing production. This guide describes the Google Analytics interface, not a legal conclusion. Assign separate owners for authorizing the request, implementing the call, and verifying the result when the business process requires that separation.

Inventory every legacy call, credential, queue, retry, dashboard, alert, and runbook that refers to the v3 User Deletion API or its upsert method. Record the GA4 properties each path can affect and the identifiers each source can supply. Disable undocumented side channels. A code search alone is not enough if scheduled jobs or external integration platforms can still submit legacy requests.

Google states that the legacy User Deletion API v3 has been sunset and directs implementations from its upsert method to the Admin API v1alpha SubmitUserDeletion method. The REST endpoint uses the GA4 property resource: POST to analyticsadmin.googleapis.com with the properties identifier and submitUserDeletion action. Replace endpoint, request model, authentication scope, client library, error handling, and response parsing together.

Do not perform a blind string substitution. The legacy payload used a property and nested identifier object, while the replacement request body uses one field from a union of supported user identifiers. Build typed validation at the request boundary and reject payloads that supply none or more than one identifier. Keep the property identifier explicit rather than deriving it from an untrusted client field.

Google documents analytics.edit as the OAuth scope required by submitUserDeletion and notes that it differs from the legacy analytics.user.deletion scope. Review whether the calling identity should retain any legacy scope after migration. Restrict the credential to the approved runtime and grant only the GA4 property access needed for the workflow. Do not place tokens or credential files in source control, logs, issue trackers, or browser history.

Enable the Google Analytics Admin API in the authorized cloud project and update the consent or workload-identity process according to the existing security design. Test token acquisition separately from deletion. A successful token does not prove the identity has access to the intended property, and broad account access should not be used merely to avoid maintaining a property allowlist.

The Admin API reference accepts one of userId, clientId, appInstanceId, or userProvidedData. Select the field that matches the identifier collected by the approved request workflow. Do not translate an email into a client ID, infer an app instance, or submit a CRM identifier as a GA4 user ID unless the implementation deliberately assigned that same value under an approved design. Ambiguous requests must pause for authoritative resolution.

Google provides normalization rules for user-provided email or phone data in the method reference. Apply those rules only when that identifier type is authorized, and protect the raw and normalized values as sensitive data. Store an irreversible audit fingerprint where possible instead of the value itself. Keep the mapping evidence inside the restricted privacy system, not in general analytics reports.

Assign an internal request ID before calling Google. Lock or deduplicate requests by approved property, identifier type, protected identifier fingerprint, and authorization event. Store attempt number, response class, and next retry time. Retry only transient failures according to the platform and organizational policy. Do not create parallel retries that can submit the same request repeatedly without visibility.

The successful response includes a deletionRequestTime timestamp. Store it with the internal request and compare it with the submission time. Treat receipt as accepted submission evidence, not proof that every downstream report has already changed. If the API returns an authorization, validation, or property error, stop that request and correct the broken boundary rather than changing identifiers or widening credentials speculatively.

Use an approved non-production or designated test property and synthetic identifier owned by the organization. Verify request validation, property allowlisting, authentication, endpoint, response parsing, logging redaction, deduplication, retries, and failure alerts. Do not submit a real customer's identifier merely to prove the migration. If a production smoke test is required, it must come from an authorized privacy request and follow the normal process.

Exercise missing identifier, multiple identifiers, invalid property, insufficient scope, network timeout, retry collision, and duplicate request cases. Confirm that logs never contain raw email, phone, client ID, app instance ID, token, or request body. Test the operator view and audit export as well as the API call. A technically successful deletion path that exposes identifiers in monitoring is not production ready.

Deploy the replacement behind an explicit version or feature flag when the architecture supports it. Pause new legacy submissions, drain or migrate the approved queue, switch the producer, and monitor the new path. Do not send one live request to both APIs for comparison. Google says the legacy API is sunset, so the migration verification should focus on the Admin API request and the organization's audit trail.

After cutover, confirm no scheduler, integration, or manual tool still calls the legacy endpoint. Revoke obsolete access according to the security plan and update runbooks. Reconcile accepted requests, failures, retries, and unresolved identity cases for the migration window. Keep deletion outcomes separate from general GA4 property data-deletion requests because the mechanisms and intended scope differ.