Update Clerk user metadata without clobbering existing keys: PATCH merge vs PUT replace on /v1/users/{id}/metadata

Documented steps

1. Read current state first: GET https://api.clerk.com/v1/users/{user_id} with 'Authorization: Bearer <CLERK_SECRET_KEY>'. The User object carries public_metadata, private_metadata and unsafe_metadata.
2. To merge into existing metadata, call PATCH https://api.clerk.com/v1/users/{user_id}/metadata with 'Content-Type: application/json' and a body containing only the top-level metadata fields you intend to touch, e.g. {"public_metadata": {"plan": "pro"}}.
3. PATCH performs a deep merge: nested objects are merged key by key rather than replaced wholesale.
4. To delete a single key at any nesting depth via PATCH, set that key's value to null in the body. The key is removed.
5. To replace a metadata field entirely, call PUT https://api.clerk.com/v1/users/{user_id}/metadata. Each top-level field present in the body is overwritten in full with no merging; top-level fields omitted from the body are left unchanged.
6. Use PUT with {"public_metadata": {}} to clear a field completely.
7. Choose the right bucket: public_metadata is backend-write / frontend-read, private_metadata is backend-only, unsafe_metadata is writable by the end user from the frontend.
8. Keep anything you need inside the session token small; metadata mirrored into the JWT inflates every request's cookie/header.
9. After a backend metadata change, an already-issued session token still carries the old values until it refreshes.
10. SDK equivalents: clerkClient.users.updateUserMetadata(userId, { publicMetadata }) for merge semantics.