Subscriptions

Subscriptions are configured using the Android Play Console. Once you have a subscription configured, you can add Google Play Billing to your app to enable a purchase flow for the subscription. Subscriptions have many characteristics mentioned in the Google Play Billing Overview, such as billing period, grace period, free trial, and so on. You should be familiar with these concepts before reading this section.

Purchase a Subscription

Purchasing a subscription product has no different than purchasing ant other In-App so you can use the same follow described at Purchase Flow guide.

Upgrade or downgrade a subscription

You can use PurchaseSubscriptionReplace method to upgrade or downgrade a subscription purchase. The method is similar to Purchase method except that it takes a list with exactly one already-purchased SKU to be replaced with the SKU being purchased. When the user completes the purchase, Google Play swaps out the old SKU and credits the user with the unused value of their subscription time on a pro-rated basis. Google Play applies this credit to the new subscription, and does not begin billing the user for the new subscription until after the credit is used up.

Note: You can only use this method for subscription purchases. If the passed product type is anything other than subscription the method returns BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Furthermore, the passed SKUs may not include SKUs for seasonal subscriptions.

Handle subscription-related states with Real-time Developer Notifications

Real-time developer notifications are server push notifications that give you the capability to monitor state changes, such as SUBSCRIPTION_PURCHASED or SUBSCRIPTION_RECOVERED, for subscriptions. Real-time Developer Notifications allow you to react proactively to state changes, to increase your engagement, and to reduce user turnover. To enable these notifications, see Real-time Developer Notifications.

If you have Real-time Developer Notifications enabled, your secure backend server receives notifications alerting you only of subscription state changes. You must call the developer API after receiving a Real-time Developer Notifications to get the complete status and update your own backend state. These notifications tell you only that the subscription state changed; it does not give you complete information of the subscription status.

When checking the developer API, you should always do the following:

• If expiryTimeMillis is in the future, always grant entitlement.
• If autoRenewing = false, try to get the user to resignup because the subscription will end at expiry time.
• If paymentState = 0,send the user to the subscriptions center using the subscriptions center deep-link to fix their payment issue.

In the future we may add additional state changes that impact a user’s entitlement, such as pausing a subscription or reactivating a subscription after it’s expired. So that your integration is ready for these features, be sure to handle any undefined notifications by calling the developer API and taking action as described above.

User is in a grace period - SUBSCRIPTION_IN_GRACE_PERIOD

The grace period lasts for a certain amount of time based on your in-app product setting in the Google Play Console. Google Play tries to renew the subscription during the grace period. To alert the user about the payment issue, provide a message in your app that tells users how to fix their payment method. Otherwise, the user will lose access to subscription. For example, "To prevent disruptions to your account, navigate to the Google Play subscription settings to fix your payment on Google Play." This message would link to the Google Play subscription settings so that the user can fix their payment method.

To determine how much time the user has in the grace period, call the Google Play Developer API. Google Play dynamically extends the expiryTimeMillis value until the grace period has expired. During this time period, you should check whether the user's subscription been cancelled, renewed, or placed on hold. You should check the user's current subscription status after expiryTimeMillis has passed to get the latest status of the subscription.

The contents of the JSON response vary depending on the state of the subscription, as shown in the following snippets. For example, if you query for a subscription during the grace period (form of payment is bad), the expiryTimeMillis is dynamically updated to a future timestamp and paymentState is set to 0:

{  
"kind": "androidpublisher#subscriptionPurchase",  
...  
"expiryTimeMillis": timestamp_in_future,  
"autoRenewing": true,  
...  
"paymentState": 0 # Payment pending  
}

If you query for a subscription after the subscription was successfully renewed (form of payment was updated), the expiryTimeMillis is set to a timestamp in the future and paymentState is 1:

{  
"kind": "androidpublisher#subscriptionPurchase",  
...  
"expiryTimeMillis": timestamp_in_future,  
"autoRenewing": true,  
...  
"paymentState": 1 # Payment received  
}

If you query the subscription after the grace period has lapsed, you will either find the subscription is on hold (if you enable Account Hold in the Google Play Console) or is cancelled (if you don't enable Account Hold in the Google Play Console). For sample JSON responses for SUBSCRIPTION_ON_HOLD and SUBSCRIPTION_CANCELLED, refer to the Account Hold - SUBSCRIPTION_ON_HOLD section.