Developer Console
Sign In
Sign In
Developer Console

Appstore Billing Compatibility Subscriptions

Use this page to help you set up subscriptions in your app with the Appstore Billing Compatibility SDK.

Add subscription in Developer Console

To add subscriptions in your app, first you must create a subscription plan in the Developer Console. For detailed instructions on how to set up a subscription, see Create and Submit Single IAP items.

When setting up a subscription, have the following information available.

Data Description
Subscription Title String containing the title of your subscription.
Subscription SKU A unique string that becomes the ID for the subscription item. This SKU is also called a parent SKU for the term SKUs.
Description and images A display title, a description, and images for the subscription.
Subscription Terms The subscription periods provided to your customers. Terms are always defined under the subscription SKU. Every term has a unique SKU and a unique period.
Subscription term data
Subscription Term (also called Term Period or Term) Subscription terms start on the date of purchase. Valid values are Weekly, BiWeekly (every two weeks), Monthly, BiMonthly (every two months), Quarterly, SemiAnnually (every six months), and Annually (every twelve months).
SKU (also called Term SKU) SKU of the term which uniquely identifies this subscription term.
Free Trial (Optional) A free trial period for the subscription. Valid values are No (no free trial), 7 Days, 14 Days, 1 Month, 2 Months, and 3 Months.
Price (Optional) The price for your subscription term. Set a base price and let the console automatically calculate prices for other marketplaces, or manually set a price for all marketplaces.

Sample subscription plan

This example provides data for an app that offers a free option and a premium option. The free option offers basic functionality and the premium option offers exclusive privileges. To access the premium features, customers must have a valid subscription. The subscription has two terms:

  • A monthly plan with a price of 1.99 USD per month.
  • An annual plan with price of 9.99 USD per year. This plan also comes with a seven-day free trial.

To model this offer in the Developer Console, you would create a subscription plan with following details:

  • Subscription SKU: "com.example.sampleapp.premium"
    The name of this SKU indicates it's the SKU for the premium subscription.
  • Subscription Title: "Premium Subscription"
  • Description: "This is the premium subscription. Buy it to access exclusive features."
  • Subscription Terms: There are two terms for this subscription. One for monthly and another for annually.
    • Monthly Term:
      1. Subscription Term: Monthly
      2. SKU: "com.example.sampleapp.premium.monthly"
      3. Free Trial: No
      4. Price: 1.99 USD
    • Annual Term:
      1. Subscription Term: Annually
      2. SKU: "com.example.sampleapp.premium.yearly"
      3. Free Trial: 7 Days
      4. Price: 9.99 USD

Note

  • The annual term has a seven-day free trial period.
  • The monthly term has no free trial.
  • The SKU for the monthly term and the annual term are different from each other, and different from the subscription SKU.

Provide subscription details in app

After you have set up a subscription in the Developer Console, you must provide subscription details in your app. To do this, download the subscription IAP you created in the Developer Console as a JSON file, and add that file to your app's assets folder. To download the file:

  1. Navigate to the In-App Items tab of your app.
  2. Click Export Multiple IAPs > JSON.
  3. Click OK to confirm.
  4. Wait a moment for the file to generate. When it's ready, an option to download the file appears.
  5. Download the JSON file.

After you download the file, copy and paste it into your app's assets folder. The Appstore uses this file to establish an association between a parent subscription and its term SKUs.

The following is an example JSON based on the subscription plan that has a parent SKU of "com.example.sampleapp.premium" and term SKUs of "com.example.sampleapp.premium.monthly" and "com.example.sampleapp.premium.yearly".

{
    "com.example.sampleapp.premium.monthly": {
        "smallIconUrl": "http://",
        "title": "Premium Subscription",
        "itemType": "SUBSCRIPTION",
        "price": 0.0,
        "description": "This is premium subscription. Buy it to access exclusive features.",
        "languageTitleMap": {
            "US": "Premium Subscription"
        },
        "languageDescriptionMap": {
            "US": "Buy this subscription to get Infinite Gas in the app"
        },
        "currencyPriceMap": {
            "US": 0.0
        },
        "subscriptionParent": "com.example.sampleapp.premium",
        "term": "Monthly"
    },
    "com.example.sampleapp.premium.yearly": {
        "smallIconUrl": "http://",
        "title": "Premium Subscription",
        "itemType": "SUBSCRIPTION",
        "price": 0.0,
        "description": "This is premium subscription. Buy it to access exclusive features.",
        "languageTitleMap": {
            "US": "Infinite Gas Subscription"
        },
        "languageDescriptionMap": {
            "US": "Buy this subscription to get Infinite Gas in the app"
        },
        "currencyPriceMap": {
            "US": 0.0
        },
        "subscriptionParent": "com.example.sampleapp.premium",
        "term": "Annually"
    }
}

Port subscription plans

In May 2022, Google updated how it handles subscriptions. For details, see Recent changes to subscriptions in Play Console in the Play Console Help documentation. If you use legacy subscriptions, your apps uses the APIs and purchase flow before the changes in May 2022. In this flow, your app uses the querySkuDetailsAsync() method to fetch SKU details, followed by a call to the launchBillingFlow() method, which uses the SKU details. In this subscription model, a subscription plan has only one term.

If your app uses the APIs and purchase flow provided after May 2022, it uses queryProductDetailsAsync() to fetch product details, followed by the launchBillingFlow() method, which uses the product details and an offer token. In this subscription model, a subscription plan can have multiple terms. For more details, see Backward-compatible Play Billing Library upgrade in the Android developer documentation.

The Appstore Billing Compatibility APIs gives you the option to use either flow, as it includes a querySkuDetailsAsync() method and a queryProductDetailsAsync() method.

Last updated: Oct 27, 2023