The ultimate guide to Android subscription testing

In-app purchases are among the most critical pieces of software in mobile applications. Testing comprehensively is a must to ensure potential customers don’t find issues when making a purchase. This is even more true when testing Android in-app subscriptions, which have a lot of extra cases to handle and test.

In this guide, we will cover how to test your app’s Android subscriptions on the Google Play Store, regardless of using RevenueCat, your own code, or any other mobile subscription platform. We’ll address all the associated features and edge cases you need to test for, so that users enjoy a smooth, frictionless buying experience. This guide will be updated over time as changes occur in this process or we figure out better ways to test, so please let us know if you have any suggestions.

Also have an iOS app? Check out our iOS subscription testing guide!

Just getting started with subscriptions, or want to level up your subscription infrastructure? Sign up to RevenueCat for free

Android subscription basics

A user who purchases a subscription expects to gain access to one or more pieces of content that would otherwise be locked. In other words, the user is granted one or more entitlements that give access to your app’s content while the subscription is active.

Here is some basic information about how subscriptions work on the Google Play Store:

Purchases will be associated with a user’s Google account
Google will not allow for the same subscription to be active more than once on the same Google account
The subscription will renew after each renewal period unless it’s canceled, or after six renewals for purchases done using licensed testers/test accounts. See more on licensed testers in the “Licensed testing” section below
If the user cancels a subscription, it will remain active until the end of the current subscription period

If you’re interested in learning what changes Google made to Android subscriptions at Google I/O 2022, check out our roundup of Google Play Billing Library 5.

Test utilities

Licensed testing

Google provides a mechanism called “licensed testing” to test purchases without charging testers. This is the recommended way to test Android purchases during development. For additional testing after launch, Google Play’s licensed testing allows you to have a sandbox environment to test purchases.

To use this feature, you must add your Google account as a licensed tester in your Google Play developer account. Note that there might be some propagation delay after doing this, so expect to wait a couple of hours for changes to take effect.

Please note that users added as licensed testers can purchase your app’s products and subscriptions without paying, even if they get the app directly from the Play Store. Licensed testing is meant as an internal testing tool only and is not recommended for use with external testers.

When using licensed testers’ accounts to purchase, you will see a message within the purchase dialog indicating that you’re performing a test purchase and will not be charged. Also, renewal periods and many feature periods are substantially shortened when using licensed testers, making it easier to test.

Android subscription testing period times

Additionally, when you make a purchase with a licensed tester account, you can select a test payment card in the purchase dialog that always declines. This will allow you to test Android subscription purchase failures and other situations. You can also change this payment method from the Play Store to test grace periods and account hold status.

Android subscription testing payment card

Test tracks

Google provides test tracks to test your Android subscription app with a smaller subset of users before you ship it to all users in the production track. For example, test tracks allow you to create some alpha/beta test groups to test your app before it actually hits all your users.

Test tracks can be:

Open: Anyone can join from the Play Store, up to a certain count limit that you can specify.
Closed: Joining requires a link.
Internal: This is the same as closed but is meant for internal users only and has a limit of 100 users.

You can create multiple closed tracks, but you can only have one internal and one open track. You can create test tracks for your apps from the Google Play console.

It’s important to note that all these users (whether open, closed, or internal testers) will be charged for their purchases unless they are also licensed testers. This can be great for testing your purchase implementation with a reduced number of users. On the other hand, if you want these users to test paid features of your Android app, including subscriptions or one-off in-app purchases, they would have to pay first.

There are some ways to bypass this limitation:

You can have a test-specific build with paid features unlocked. This works but has the downside that the app your testers see won’t be the same production users do.
Or, you can grant paid features to your test users programmatically or manually. In RevenueCat, we support both manual and programmatic; check out this post on using entitlements to grant access to specific parts of your app to find out more.

Order management

The order management section in the Google Play Console allows you to see all purchases made through your app. It also allows for some basic operations on user subscriptions as an administrator of your app. This is very useful for confirming that your test purchases are coming through correctly on Google’s side.

One of these operations it the refunding of purchases. While you should aim to test mostly through licensed tester accounts, it’s recommended to test your Android subscriptions using real accounts as well. you can do here is to refund purchases. This is especially important before you first ship to users, and whenever you make big changes in your purchasing implementation.

This means you’ll be paying real money when purchasing these subscriptions on non-licensed tester accounts. To avoid incurring charges needlessly, remember to always refund your purchases after performing non-licensed tester account testing.

Want to refund programmatically? Google provides an API that you can use. If you’re using RevenueCat, you should refund purchases from the dashboard instead of through the Play console. This allows us to have more correct and up-to-date data in the dashboard.

Google Play subscription management

This Google Play subscription management page can be found in the Play Store app or through a browser. It allows your users (or you, when testing) to check a lot of important information about subscriptions, such as:

Renewal information, i.e., whether or not the subscription will renew at the end of the current billing cycle.
The user’s current billing cycle expiration date.
Payment methods, including allowing changes to them. This can be especially useful when using licensed tester accounts as you can change between an approving or failing test card.
Subscription price.

This page also allows for operations like canceling, pausing, resubscribing, and upgrading/downgrading.

It’s recommended to provide your users an easy way to access this section of the Play Store. The link is https://play.google.com/store/account/subscriptions?sku=your-sub-product-id&package=your-app-package if they have an active subscription with your app, or https://play.google.com/store/account/subscriptions if not.

How to start testing

To start testing Android subscriptions, you will need to do a few things first:

Upload a signed build to a closed test track in the Google Play Console. While it’s not documented, there will likely be some propagation time after this step. We recommend waiting a couple of hours after you do this before testing. Once your app is approved, you don’t need to upload new builds to a test track every time — you can test with a local build.
Make sure your app is approved before you start testing.
Have a device or emulator with Android 1.6+ and the Google Play Store / Play Services installed. A real device is preferred, but if you’re testing on an emulator, make sure you use an image that has the Play Store included, as shown in the following image:

Select hardware for testing Android subscriptions

Set up a PIN code or other security measure for your device. While this is not documented, we have seen situations where testing subscriptions fails otherwise.
Log in on your device with a Google account. That same Google account must be added as a tester in the test track in the Google Play Console. If you log in with multiple Google accounts on your device, you might get unexpected results.
Opt into the test track with your Google account using the opt-in URL of the test track you uploaded your build into. Again, there might be some propagation time after this step.

how testers join your test Android subscriptions

This is also undocumented, but we recommend opening the Play Store at least once after logging in with your Google account but before testing purchases on your device.
The build you’re testing on should match the applicationId of the build on the Play Console.
You need to set up your subscriptions. We have a guide on setting up subscriptions in the Google Play Console here, which we recommend reading if you haven’t done this before. As with most changes done in the Google Play Console, we recommend waiting a couple of hours after creating these subscriptions to avoid any propagation issues.

After this, you will be able to purchase subscriptions inside your app.

Congratulations on completing the first step toward testing subscriptions in your app! 🎉

Subscription features and how to test them

The Play Store provides many different features within the subscription system. Some will need to be tested by every Android app using subscriptions, while others are optional and should be tested only if you support them. Here we will divide these features into “mandatory” and “optional” features and explain how to test each one.

We recommend testing these features using licensed testers first and then doing some basic tests on non-licensed-tester accounts before actually shipping to real users. Testing is also recommended when making big changes to your implementation. (Remember to refund your purchases from the “Order management” section in the Google Play Console, or via your RevenueCat dashboard to not lose money.)

Mandatory features

Initial purchase

How to test:

Perform a subscription purchase using a Google account that does not have that subscription active.
Verify that the purchase succeeds without errors; you should get an email from Google confirming the purchase, whether you’re using licensed testers or not.
Verify that the user has access to the content/entitlements associated with the subscription while the subscription lasts.
Verify that the subscription period is as expected. You can check this from the Subscriptions section in the Play Store.

Initial purchase (error)

How to test:

Try to perform a purchase of a subscription but fail to complete it. You can select a declining test card if using a licensed tester account or try to purchase without a connection.
The user should be shown a meaningful message for the error.
The user should not be given access to the entitlements.

Renewal

How to test:

Perform a purchase of a subscription.
The user should have the relevant content unlocked.
Wait until the first subscription period finishes. For licensed tester accounts, check the durations here.
The user should keep the unlocked content.

Cancelation

How to test:

Perform a purchase of a subscription.
The user should have the relevant content unlocked.
Cancel the subscription; you can do this from the subscriptions section in the Play Store.
The user should keep the relevant content unlocked until the current subscription period finishes.
After the subscription period finishes, the user should no longer have the content unlocked.

Resubscribing from the Play Store (restoring)

How to test:

Perform a purchase of a subscription.
Cancel the subscription.
The user should keep the relevant content unlocked until the current subscription period finishes.
Before the subscription finishes, resubscribe to it from the Play Store.
The user should keep the relevant content unlocked after the subscription period finishes.

Notes:

https://developer.android.com/google/play/billing/subscriptions#before-in-store

Refunding

How to test:

Perform a subscription purchase.
Verify that the user has the relevant content unlocked.
If you’re not a RevenueCat customer: From the Play Console, look for your order in the Order Management section using the Order ID (which should have been sent in the receipt email to your Google account) or email and refund it.
If you’re a RevenueCat customer: From the dashboard, look for your subscription using the order ID, email, or user ID, and refund it.
The user should stop having the relevant content unlocked.
The subscription shouldn’t auto-renew.

Account hold

When a payment fails during a subscription renewal, the subscription will enter into account hold subscription status after the optional subscription grace period, if it has any (explained in the “Grace period” section below). In this state, the user won’t have access to the entitlement but will be notified of the billing issues and offered a chance to fix them and recover. This status will last up to 30 days (or 10 minutes with internal testing).

How to test:

Perform a purchase of a subscription.
Before a renewal, change to a payment method that will fail. This is much easier to do in internal testing, where we can select a failing test card to renew the subscription from the Play Store.
Before the current subscription period finishes, the user should keep the relevant content unlocked.
After the current subscription period finishes, the user should not have the relevant content unlocked.
Change the payment method to a valid one.
The subscription should resume.
The user should regain access to the relevant content.

Notes:

If the account hold finishes without fixing the payment method, the subscription will be canceled.
If the subscription has an associated grace period, the subscription will enter the grace period state first before entering account hold status.

Optional features

Free trials

To test free Android subscription trials, we need a subscription with an associated “New customer acquisition” offer with a “Free trial” phase of any time duration. You can create this subscription from the Play Console.

Eligibility criteria:

When you create the free trial offer in the Play Console, you can decide which users will be eligible for that offer. There are two options:
- Users who have never purchased that specific subscription. In this case, only users who have purchased that specific subscription in your app with the same Google account won’t get the free trial.
- Users who have never purchased any subscription for your app. In this case, users who have purchased the same or a different subscription in the same Google account won’t get the free trial offer.

If you’re using RevenueCat, check out this question for the current approach to detect whether or not a user is eligible for a free trial.
Make sure you don’t promote free trials to users that are not eligible for it, since that creates a really bad user experience.
Note that eligibility criteria are associated with the Google account, not your app’s account system (if you have any).

How to test:

Perform a purchase of the subscription with free trial for an eligible user. The Play Store dialog should indicate that a free trial will be offered at no charge, and show the price and period of the subscription.
The user has access to the entitlement during the free trial period.
After the free trial period (3 minutes in internal testing), the subscription should renew with the normal price of the subscription.
The user should keep access to the entitlement after the free trial has expired (unless it’s been canceled).

Subscription pause

You can enable subscription pause for your app in the Play Console under the “Monetization setup” tab. With this setting enabled, users will be able to pause a subscription for a period of time, disabling renewals until the user removes the pause or it expires. This is useful for users who want to take a break from your app for a little while (for example, when going on a vacation) but still intend to keep using it.

How to test:

Perform a purchase of a subscription
Pause the subscription
The user should keep access to the relevant content after the subscription has been paused but before the current subscription period has expired.
The user should not have access to the relevant content after the subscription period finishes.
Resume the subscription after the subscription period finishes. This can be done from the Play Store.
The user should regain access to the relevant content.
The subscription should renew normally from that point onwards

Notes:

Subscription pause is not available on annual subscriptions.
After the pause period finishes, Google will automatically resume the subscription. If there is a problem with the payment method, the subscription will enter the account hold status.
Users can pause a subscription for up to 3 months (15 minutes with licensed testing).

Grace period

When a payment fails during a subscription renewal, you can optionally give the user some time to fix the problematic payment method without interrupting access to the relevant content. Each subscription can have a different grace period.

How to test:

Perform a purchase of a subscription with a grace period added.
Before a renewal, change to a payment method that will fail. As mentioned earlier, this is much easier to do in internal testing, where we can select a failing test card to renew the subscription from the Play Store.
The user should keep access to the relevant content before the current subscription period finishes.
The user should keep access to the relevant content after the current subscription period finishes but before the grace period expires (5 minutes in licensed testing).
Now there are two possibilities:
1. User fixes the payment method:
  - Before the grace period expires, change to a valid payment method.
  - The user should keep access to the relevant content after the grace period expires.
  - The subscription should renew normally.
2. User does not fix the payment method:
  - After the grace period expires, the user should lose access to the relevant content and enter account hold status.
  - The subscription should not renew anymore.

Resubscribing from the app (Resignup)

You can optionally allow users to resubscribe to a subscription from your app after they cancel it but before it expires. In such cases, you can either offer the same subscription the user canceled (a reactivation) or a different subscription while prorating the remaining subscription. This second case will be a subscription upgrade or downgrade and will be covered further below.

How to test resubscribing to an Android subscription:

Perform a subscription purchase.
Cancel the subscription.
From your app, reactivate the same subscription before it expires.
The user should keep access to the relevant content after the subscription period ends, as if the person never canceled.

Notes:

When resubscribing to the subscription in this way, note that a new subscription is generated internally, prorating the remaining time in the old subscription. This might be important for data collection purposes and to find the purchases in the Google Play Console.

Restore purchases

There are two main situations you should test here, depending on whether your app has its own account system.

If your app doesn’t have an account system:

Your app must provide access to the subscription if the user uninstalls and reinstalls your app or has multiple devices.

Steps to test when a user uninstalls and reinstalls your app:

Perform a purchase of a subscription.
Uninstall and reinstall the app with the same Google account.
The user keeps access to the relevant content after reinstalling.

Steps to test installation on multiple android devices:

Install the app on more than one device with the same Google account.
Perform a purchase of a subscription in one device.
The user has access to the relevant content in both devices.

If your app has an account system:

There is no great support from Google for this case, but there are different possible behaviors you could opt to follow. The main point to consider is that your users can only have the same subscription active once for each Google account. This means users might not be able to purchase the subscription on a different app-account if they already have the subscription active. As the developer, you can opt to grant the entitlements to all accounts that use the same Google account, offer a mechanism to transfer access to a specific account, or use some other technique. In any case, this should be tested thoroughly since it’s one of the most complex flows you will encounter. RevenueCat allows you to configure different behaviors for this type of situation when trying to restore purchases with your own account system.

Additionally, you should verify that restoring purchases won’t give access after a subscription has expired, whether you have an accounting system or not.

Testing Android subscription upgrades and downgrades

While a user has an active subscription — whether canceled or not — you can optionally offer a different subscription from your app with a different price, renewal period, or offers. This is called an upgrade or downgrade, depending on the change. There are different proration modes, each of which has different testing criteria:

Make sure you test thoroughly that the subscription duration and price after an upgrade/downgrade are what you expect them to be, depending on the proration mode.

The Play Store offers the ability to create promotional codes for your subscriptions that grant a free trial for users that redeem them. These codes can be redeemed on the Google purchase dialog or from the Play Store. There are two types of codes: one-time and custom. Custom codes can only be redeemed in the in-app purchase dialog and by users who haven’t previously subscribed, so make sure your users know these criteria. To test promo codes, you will first need to create a promo code of the type you want to test and then test different scenarios.

Since there are many different ways to test this, we won’t cover all of them here. Google recommends testing at least these:

Redemption before the app is installed. This is a very interesting case you need to account for. The steps here are as follows:
1. Before you install the app, redeem the promo code from the Play Store.
2. Install the app from the Play Store.
3. As soon as you open the app, the offer should be granted, and the user should have access to the relevant content
Redemption while the app is running in the foreground. Note that for this test, you need another device to test using the Google Play Store app. Be sure to test redemptions from different screens in your app.
Redemption with multi-window mode. This is when both your app and the Google Play Store app are being displayed at the same time.

Subscription Offers

Google added support for subscription offers in Google IO 22. There are different types of offers for subscriptions that allow you to offer new and existing users subscriptions with different pricing periods, including free trials, discounted periods, and so on. RevenueCat is actively working on supporting all these offers, and we will update this section once we have more comprehensive testing steps.

Automated subscription testing

You might have noticed that all the testing steps we suggested involve manual testing. As developers, we always try to automate repetitive tasks, especially tests — this results in more reliable and thorough testing, not to mention saving a ton of time! Unfortunately, Google currently doesn’t provide any mechanisms to simulate the purchase environment in unit tests.

The alternative is to automate purchase tests using UI tests. However, in addition to this being much slower and generally more brittle than unit tests, there are many complications with this approach:

Subscriptions are associated with Google accounts, so there can be problems when running tests in parallel or too quickly if you’re using the same Google account. Additionally, your test accounts need to be added as licensed testers.
It’s very difficult to test some features. Renewals would require you to wait on a test for at least a few minutes. Promo codes have a limit on the number of redemptions.

We hope Google will improve its support for automating purchase tests. Until then, this is doable, but it’s very difficult and limited.

Pre-launch testing

To test your subscriptions before launching the app to all users, you should create a closed track for internal users, upload your build to that track, and get your app approved for testing. Once that’s done, you should first test all the features you support with a licensed account. Once everything seems to work fine, you should run another few tests using a non-licensed account. The minimum list of features we recommend to test with a non-licensed account are:

Initial purchase
Renewal (you can create a weekly subscription to test faster)
Cancellation
Free trials
Restoring purchases

Summary

In-app purchases, especially subscriptions, are very complex to implement and maintain. However, it is vitally important for both you and your subscribers to support all the features the Play Store provides, which is why you need to thoroughly test everything.

If you’re struggling with implementing in-app subscriptions, check out our open source SDKs. They handle the pain points of in-app subscriptions, so you can get back to building your app.

The ultimate guide to Android subscription testing

Android subscription basics