# Customer identity and ownership

Your application chooses an App User ID and authenticates it. CherrySub stores an app-scoped customer record and its aliases, purchase ownership, and resolved access. Dashboard accounts and project members are a different identity system.

## Choose a stable App User ID

Use an opaque, durable identifier from your user database. The API accepts a non-empty UTF-8 string up to 512 bytes, excludes control characters, and trims surrounding whitespace. Avoid using an email address that can change, a device advertising identifier, or a display name.

The same text under another CherrySub app is not automatically the same customer. Keep the App User ID consistent between your authentication middleware, token broker, receipt submission, and subscriber read. SDK path construction supports Unicode and reserved characters; custom HTTP clients must URL-encode the path segment.

## Establish the customer through verified evidence

Minting a customer token authenticates the intended subject; it does not fabricate a paid customer or purchase. Before a customer alias exists, a subscriber read can return 404. A valid purchase submission establishes/updates the customer and verified purchase binding.

Do not grant premium access because a token was minted or a storefront popup succeeded. Check the returned subscriber access after verification.

## Purchase ownership and restore

Customer aliases and purchase ownership are separate. A verified restore can transfer a specific purchase binding to another authenticated customer. That transfer does not implicitly merge or alias their entire customer identities. An older observation cannot reverse a newer transfer.

Design the restore UX around your application's account policy: show which application account is signed in, explain a restore action, and submit the store evidence using a token for that account. A raw request cannot choose the store app from its JSON; the API key selects it.

There is no documented general-purpose merge/alias-management endpoint or dashboard customer-transfer button in this preview. Do not simulate a merge by copying database rows or by trusting a user-supplied customer ID in your token broker.

## Switching accounts safely

1. Stop showing access state cached for the departing user.
2. Invalidate the departing user's in-memory token provider.
3. Revoke server-side customer tokens if your logout policy requires it.
4. Authenticate the new user and obtain a token for that exact App User ID.
5. Fetch the new user's subscriber state and product set.
6. Run an explicit restore only when your UX and account policy call for it.

An in-flight token refresh started before invalidation must not become the new user's token. The supplied cache providers prevent this cache-repopulation race, but application-owned state still needs to be cleared.

## Anonymous use and migration

CherrySub does not automatically decide your anonymous-to-identified user policy. If you support anonymous sessions, your backend must authenticate and consistently identify them, and your application must define the transition to a registered account. Do not assume RevenueCat's alias/restore behavior is identical.

For an existing app, preserve your stable user IDs and test representative restores before cutover. Historical imports, arbitrary customer merges, and automatic migration of another provider's aliases are not currently a one-command feature. [Migration](/docs/migration).

## Investigate an ownership issue

Find the transaction under the correct app, inspect its customer, compare the listed App User IDs with your broker's authenticated subject, and inspect the event history around the restore. Check both stores' grant contributions before concluding a user has lost all access. Support notes record investigation context; they do not alter identity or access.