Restoring In-App Purchases

What restore purchase is

When a customer reinstalls your app, moves to a new device, or signs in on a new device using their existing account, a previous in-app purchase may not be reflected in that session. The app store's restore purchase mechanism lets the customer regain access to content they have already paid for, without being charged again.

Because in-app purchases are processed by the app store rather than by Cleeng, restoring a purchase involves two parts: retrieving the purchase from the store, and submitting it to Cleeng so the customer's entitlements are brought up to date.

When it's needed

Restore purchase applies when a purchase exists in the app store but the current device - or the current Cleeng session - does not yet reflect the matching entitlement. Common cases:

• The customer signs in to the same account on a new device.
• The customer reinstalls the app.
• The purchase is recorded in Cleeng but is not currently assigned to the signed-in customer.

How it works with Cleeng

Note: Cleeng does not expose a "restore purchase" endpoint. Restore is a flow your app orchestrates using two endpoints: /purchases to synchronize the purchase, and /purchases/transfers when the purchase is already owned by another identified customer

1. The customer signs in to your app with their existing account.
2. The app requests the purchase from the app store SDK (for example Apple StoreKit 2, Google Play Billing). The store returns proof of purchase (for example, a purchase token on Google Play, or transaction data on Apple StoreKit 2).
3. The app submits that proof to the corresponding Cleeng Register purchase (/purchases) endpoint (for example Register Apple SK 2 purchase or Register Google Play purchase).
4. The /purchases endpoint responds with 202 Accepted and a synchronizationId. Validation against the store is asynchronous, so the response confirms only that the request was accepted for processing.
5. The outcome is delivered through the inappPurchaseSyncResult webhook (Apple StoreKit 2 and Google Play Billing); its result field carries the outcome, including values such as PURCHASE_RESTORED, PURCHASE_OWNERSHIP_TRANSFERRED, and PURCHASE_SYNCHRONIZED. You can also poll the check synchronization status endpoint (Check Apple SK2 purchase synchronization status or Check Google Play purchase synchronization status) to track the result.
6. If the result is OWNED_BY_ANOTHER_USER, it's recommended to display a message to the user, so they are aware and can fix the double account situation. Then you need to decide whether to transfer automatically or let the user decide whether the transfer should happen. To transfer, call the /purchases/transfers endpoint (Transfer Apple SK 2 purchase or Transfer Google Play purchase).

Check the App Flow diagram to visualize where the restore purchase process takes place.

Keeping entitlements in sync

To give customers reliable access, the app should check entitlements both in Cleeng and the app and reconcile them.

Running this check at sign-in, and whenever the customer tries to open gated content, keeps access consistent across devices and reduces support requests about missing subscriptions.