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

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 endpoint (for example Register Apple SK 2 purchase or Register Google Play purchase).
4. Cleeng validates the purchase with the app store. If the signed-in customer has no matching entitlement, Cleeng grants it. If the purchase already exists in Cleeng but is assigned to an unidentified or different user, Cleeng transfers it to the signed-in customer.
5. Synchronization is asynchronous. 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.

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.