queryPurchasesHistoryAsync. It was used to retrieve a user's purchase history for in-app products or subscriptions.
What is queryPurchasesHistoryAsync?
The queryPurchasesHistoryAsync method in Google Play Billing Library was used primarily to retrieve a user's past purchase history for in-app products and subscriptions. This was useful for displaying a record of all items a user had purchased in the past, even if they were no longer active. Key points on this method:
The method works asynchronously, meaning it doesn’t block the main thread, which is critical for maintaining app performance and a smooth user experience.
The method accepted a BillingClient.PurchasesResponseListener callback that processes the purchase history results. This callback is where the app would handle the returned data, such as displaying the purchase history to the user or using it for other in-app logic.
It required the ProductType (e.g., ProductType.INAPP or ProductType.SUBS) as an argument to specify whether to fetch in-app or subscription purchases.
As of Play Billing Library version 7, this method has been deprecated. Developers are now encouraged to use alternative approaches to handle purchase history and related functionalities.
How to check payment history in Google Play?
In Google Play Billing Library 7, the method queryPurchasesHistoryAsync has been deprecated without a comprehensive replacement. Let’s take a closer look at its former uses and explore how we can now achieve similar goals.First, it’s important to clarify that there are two overloads of the queryPurchasesHistoryAsync method. The older overload, which takes a skuType as an argument, was deprecated with the release of Google Play Billing Library 5. At that time, a new method using QueryPurchaseHistoryParams was introduced, allowing for the specification of product type instead of the now-deprecated SKU type. Despite these changes, the output of the methods remains consistent.Both versions of queryPurchasesHistoryAsync provided a list of the most recent purchases for each product of the specified type. Notably, this included expired, canceled, or consumed purchases. This method was commonly used for several key purposes:
- Restoring user entitlements, requiring information only about active subscriptions and non-consumed one-time purchases.
- Managing purchase cancellations and refunds.
- Tracking historical purchase data for analytics.
With this context in mind, let’s discuss how to achieve these goals without relying on the deprecated method.
Replacing queryPurchasesHistoryAsync for entitlements management
We only need to focus on active subscriptions and non-consumed one-time purchases to manage user entitlements. The queryPurchasesAsync method is the new approach we should adopt.
Previously, we used the following code:
Now, we should update it to:
The changes are minimal. The main difference is that the result will now be a list of Purchase objects instead of PurchaseHistoryRecord objects. However, we can still access all the essential information we previously retrieved, such as purchase tokens, timestamps, product IDs, quantities, and more.
Replacing queryPurchasesHistoryAsync to handle canceled or refunded purchases
For purchases that have been canceled or refunded (voided), there isn’t a direct alternative available on the mobile side. However, we can utilize Google’s Voided Purchases API, which retrieves all voided purchases for a particular project. You can specify a time range for your searches, allowing for periodic API calls.I won’t go into the details of setting up the Google API here, as I assume you’re already familiar with it if you’ve been managing purchase cancellations or refunds before. Contact us if you have questions on this.Additionally, it’s recommended to implement Real-Time Developer Notifications. This way, you’ll be notified whenever there’s a change in the status of a client’s purchase, including cancellations or refunds. The Voided Purchases API can serve as a supplementary source of information.
Replacing queryPurchasesHistoryAsync for analytics
For the final goal, we would have used queryPurchasesHistoryAsync for analytics, precisely to monitor past purchases. Unfortunately, moving forward, we no longer have a viable option for this. This means we can’t retrieve details about expired subscriptions or one-time purchases that have been consumed. As long as queryPurchasesHistoryAsync remains available, we can still utilize it. However, once it’s removed, our only choice will be to track purchases while they are active, resulting in the loss of any prior history if you haven’t already recorded it.
About Qonverison
At Qonversion, we utilize this method to manage user entitlements and track analytics effectively. It’s essential for us to monitor historical events, especially since we often have no data on a new client’s users’ purchases when they come on board. To address this, we’ve opted to continue using the deprecated method for the time being, while also preparing for the necessary migration once that method is phased out.
If you want to save time managing significant updates to the Google Play Billing Library, check out our SDK. It’s designed to keep you aligned with Google’s latest requirements without the stress of constant updates. That’s what we’re here for — to handle the complexity so you can stay focused on creating great user experiences and growing your app’s revenue.
Key Takeaways from queryPurchasesHistoryAsync deprecation
The queryPurchasesHistoryAsync method was deprecated in version 7 of the Google Play Billing Library and will be removed in version 8. Although you can still use the deprecated method for now, keep in mind that Google only supports apps using the two most recent major versions of the billing library. By the time version 9 is released, you’ll need to fully transition away from the deprecated method to the recommended alternatives. Given that you won’t be able to retrieve historical purchase data with the new methods, it’s advisable to migrate as soon as possible. This way, you can start tracking purchases moving forward and avoid losing any historical data later on.To transition from the outdated queryPurchasesHistoryAsync method, follow these steps:
Utilize the queryPurchasesAsync method to retrieve active subscriptions and non-consumed one-time purchases to manage entitlements.-
Implement the Voided Purchases API to manage cancellations and refunds alongside Real-Time Developer Notifications.
- Maintain your own purchase history, as there will be no alternative way to access consumed one-time purchases or expired subscriptions.
Useful links
- Google Play Billing Library 7 release notes
- Query Purchase History alternatives
- Deprecated queryPurchasesHistoryAsync method reference)
- Alternative queryPurchasesAsync method reference)
Kamo
SDK Engineer at Qonversion
Kamo works on SDK development, making integration easy for developers.
