Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

Google Play Billing Overview

Google Play Billing is a service that lets you sell digital content from inside an Android app, or in-app. This document describes the fundamental building blocks of a Google Play Billing solution. Knowledge of these building blocks is necessary to decide how to implement your specific Google Play Billing solution.

If you want to sell physical goods on Android, refer to Google Pay.

Note: Ensure that you comply with applicable laws in the countries where you distribute apps.

The following is a list of the high-level building blocks of a Google Play Billing solution:

  1. Google Play. An online store where users can download digital products.
  2. Google Play Console. The interface app developers use to publish apps on Google Play. App developers use the Google Play Console to identify details about their app, including any in-app products. For more information, refer to The Google Play Console.
  3. Google API Console. The console for managing backend APIs, such as the Google Play Developer API. Create service accounts here to verify purchases and subscriptions from your secure backend server.
  4. Android device. Any device used to run Android apps, such as a tablet or mobile phone.
  5. Android app. An application intended to run on an Android device.
  6. Secure backend server. A developer-provided server used to implement purchase verification or subscription features, such as real-time developer notifications.
  7. The Play Store app. The app responsible for managing all operations related to the Google Play Billing. All requests made by your app will be handled by the Play Store app.
  8. Google Play Billing Library. An API that developers use to implement Google Play Billing within an app.
  9. Google Play Developer API. A REST API used to programmatically perform a number of publishing and app-management tasks. It includes two components, the Subscriptions and In-App Purchases API used to manage in-app purchases and subscriptions, and the Publishing API to upload and publish apps, and other publishing-related tasks.
  10. Real-time developer notifications. Server push notifications that let you monitor state changes, such as SUBSCRIPTION_PURCHASED or SUBSCRIPTION_RECOVERED, for Play-managed subscriptions.

In-app product types

Google Play Billing can be used to sell two types of in-app products:

  • One-time products: an in-app product requiring a single, non-recurring charge to the user's form of payment. Additional game levels, premium loot boxes, and media files are examples of one-time products. The Google Play Console refers to one-time products as managed products, and the Google Play Billing library calls them "INAPP".
  • Subscriptions: An in-app product requiring a recurring charge to the user's form of payment. Online magazines and music streaming services are examples of subscriptions.

Purchase tokens and order IDs

Google Play Billing tracks products and transactions using purchase tokens and order IDs.

  • A purchase token is a string that represents a buyer's entitlement to a product on Google Play. It indicates that a Google user has paid for a specific product, represented by a SKU.
  • An order ID is a string that represents a financial transaction on Google Play. This string is included in a receipt that is emailed to the buyer, and third-party developers use the order ID to manage refunds in the Order Management section of the Google Play Console. Order IDs are also used in sales and payout reports.

For one-time products, every purchase creates a new token and a new order ID.

For subscriptions, an initial purchase creates a purchase token and an order ID. For each continuous billing period, the purchase token stays the same and a new order ID is issued. Upgrades, downgrades, and re-signups all create new purchase tokens and order IDs.

In-app product configuration options

One-time products and subscriptions have several common configurable options within the Google Play Console. Following are the most important common configurable options:

  • Title - A short description of the in-app product, such as “loot box.”
  • Description - A longer description of the in-app product, such as “A special in-game treasure chest containing useful stuff for your character.” This field may be used in your app's store listings page to describe your in-app product.
  • Product ID - A unique, human readable ID for your product. Product IDs are also called SKUs in the Google Play Billing Library.
  • Price / Default Price - The amount the user will pay for the in-app product. Default price has a slightly different meaning for one-time products than for subscriptions:
    • The default price for a one-time product reflects the amount (in that user’s preferred currency) the user will be charged for the product. The default price is charged to the customer once for each one-time product purchase.
    • The default price for a subscription is the price the user will be charged in that user’s preferred currency after they enter a regular billing cycle (subscriptions can have free trial and introductory pricing too). The default price is charged to the customer on a recurring basis for each subscription that a user has purchased.

    A single app can have multiple in-app products available for purchase, each with different Product ID and price. The Google Play Console provides pricing templates which are used to easily configure several in-app products that share the same price.

    Unique one-time product configuration options

    Promo codes are codes that a user uses to get a one-time product free of charge. The user enters the promo code in your app or in the Google Play Store app to receive the one-time product at no cost. Use promo codes to build a base of users for your one-time products.

    Unique subscription product configuration options

    The Google Play Console offers a lot of flexibility when creating subscription products. Following is a list of the options available for your subscription products:
    1. Billing period: The frequency at which a user is charged while their subscription is active. You can choose between weekly, 1 month, 3 months, 6 months, and annual billing periods in the Google Play Console.

      Billing continues indefinitely at the interval and price specified for the subscription. At each subscription renewal, Google Play charges the user account automatically, then notifies the user of the charges afterward by email.

    2. Free trial period: The frequency at which a user can access a subscription without being billed. A free trial period is a way to entice users to try your subscription before committing to purchase it.

      You can set a free trial period of 3 or more days.

    3. Introductory price: The price of the subscription over a certain number of initial, “introductory” billing periods. Introductory price is a way to entice users to try your subscription while simultaneously gaining some revenue. The Introductory price must be less than the subscription's normal price.
    4. Grace period: The amount of time a user’s subscription will remain active, giving the user additional time to fix their payment issue. A grace period starts when a user's form of payment, such as a credit card, is declined.
    5. Account hold: The state a subscription can enter when a user does not update their form of payment during the grace period. Account hold lasts 30 days during which time the subscription content is not available to the user.

    Warning: With the exceptions of a stated introductory price or a free trial period, you cannot change the price of a subscription after you have offered it for purchase.

    For more details about each of these options, refer to Add subscriptions and recurring charges in the Google Play Console help center.

    Next steps

    Now that you have studied most of the concepts of Google Play Billing, you are ready to implement Google Play Billing for your app. Implementing Google Play Billing involves the following steps:
    1. Configure your in-app products using the Google Play Console:
      1. Create a one-time product
      2. Create a subscription
    2. Use the Google Play Billing Library or Use In-app Billing with AIDL
    3. Test Google Play Billing