Implement a promotion

Promotions, or promo codes, let you give one-time products or trials to subscriptions free-of-charge to a limited number of users. The user enters a promo code in your app or in the Google Play Store app and receives the item or subscription trial at no cost. You can use promo codes in many ways to creatively engage with users, such as the following:

  • You might distribute cards with promo codes at an event, and users would enter their promo codes to unlock a special in-game item.
  • You might give codes to employees so they can share them with their friends and family.
  • You might send a promo code to people who buy your app during a certain period of time.

For subscriptions, note the following:

  • Promo codes offer free trials to subscriptions and not free subscriptions. Free trial subscriptions auto-renew into paid subscriptions at the end of the free trial.
  • Promotions do not extend other free trials. If a subscription begins with a free trial without requiring a promo code, a promotion would override the original free trial length.
  • Custom codes can be used only by new subscribers. Users who have purchased a subscription in the past are not eligible to use a custom code.
  • One-time use codes can be used by any subscriber. For example, users who have already purchased a subscription in the past are still eligible for a free trial through a one-time use promotion code.

Use the Google Play Console to assign promo codes. To create a promo code, see Create promotions.

Redeem a promo code

A user can redeem a promo code in one of the following ways:

  • Manually enter the code in the Google Play Store app.
  • Click on the down arrow next to the form of payment in the Google Play purchase screen and clicking the Redeem link.

Figure 1 shows a purchase screen with a down arrow. Figure 2 shows the Redeem link. Figure 3 shows the screen where users enter their promo code.

Figure 1. Google Play product redemption dialog.
Figure 2. Payment dialog showing the Redeem button.
Figure 3. The promo code screen.

Generate a promo URL

When redeeming a promo code, the user can manually enter a promo code in the Google Play Store. Alternatively, you can generate a URL that sends the user to the Google Play Store and auto-populates the Enter code field. Use the following format for a promo code URL:

https://play.google.com/redeem?code=promo_code

Figure 4 shows the Google Play app Redeem Code dialog:

Figure 4. Google Play app Redeem Code dialog.

After the user presses Redeem, if the latest version of your app is installed, the Google Play Store prompts the user to open the app. Otherwise, the Google Play Store prompts the user to update or download your app.

Support promo codes in your app

You must also make changes within your app to identify and handle promo codes. Your app must call the queryPurchases() method whenever the app starts or resumes. This method returns a bundle of all current, unconsumed purchases, including purchases the user made by redeeming a promo code. The simplest approach is to call queryPurchases() in your activity's onResume() method, since that callback fires when the activity is created, as well as when the activity is unpaused. Calling queryPurchases() in onStart() and onResume() guarantees that your app finds out about all purchases and redemptions the user may have made while the app wasn't running. Furthermore, if a user makes a purchase while the app is running and your app misses it for any reason, your app still finds out about the purchase the next time the activity resumes and calls queryPurchases().

Your activity's onPurchasesUpdated() method receives a response intent that identifies when a purchase is completed. However, your app should still call queryPurchases() in onStart() and onResume() in case the purchase and consumption workflow didn't complete. For example, if the user successfully redeems a promo code and then your app crashes before the item is consumed, your app still receives information about the purchase when the app calls queryPurchases() on its next startup.

Your app should also support the scenario where a user redeems a promo code in the Google Play Store app while the app is running. Your app can find out about the redemption through the onPurchasesUpdated() listener.