Integrate, analyze and improve subscriptions in your iOS app

Dev notes

Handling App Store billing grace period in iOS app

Recently Apple added a new feature called App Store billing grace period. It lets subscribers retain access to paid features even after subscription expired due to a billing issue. If user updates his payment information successfully, there will be no interruption in paid service.

Grace period length is fixed and depends on subscription duration. For weekly subscription grace period is set to 6 days, for other subscriptions lengths – 16 days.

To enable this feature go to App Store Connect, then to “In-App Purchases” section. Keep in mind, that even after you have turned on Billing Grace Period in App Store Connect, you will still need to add support for billing grace period in your app as well.

How to know whether user is currently in App Store billing grace period?

You need to use receipt validation to get JSON receipt data. The best practice is to use your own server for receipt validation. After you got JSON data, you will see a new field inside pending_renewal_info dictionary: grace_period_expires_date. This date is being calculated by adding 16 days (or 6 days for weekly subscription) from the latest receipt expires date.

You can read an article about how to validate App Store receipts.

If current date is between the latest receipt expires date and grace period expires date, then user is currently in billing grace period. You should also check that expiration_intent property is set to 2

If user successfully fixes billing issue, then a new receipt will appear in latest_receipt_info array and grace_period_expires_date will disappear in pending_renewal_info.

If user doesn’t fix the billing issue, then your subscription will become expired once grace period is over and you should lock premium service for the user.

Difference between grace period and is_in_billing_retry_period key

Besides new billing grace period, there is also old is_in_billing_retry_period key in pending_renewal_info JSON. This value will be set to 1, if user has billing issues and when billing grace period feature is turned off.

The difference is that when you enable billing grace period in App Store Connect, you must grant access to premium service. Apple didn’t handle this previously: each developer decided what to do by himself.

Notify user about billing issue in your app

In both cases, it’s a good practice to notify a user about billing issue and prompt him to update payment method.

You can implement some banner view or a full-screen controller that will navigate user to his account billing. Here is the simplest solution:

// example of navigating user to account billing
func handleOpenBilling(){
    let urlString = "https://apps.apple.com/account/billing"
    if let url = URL(string: urlString), UIApplication.shared.canOpenURL(url){                      UIApplication.shared.open(url)
}

How it works in Apphud?

Apphud automatically handles billing issues and billing grace period in your app without any code from your side. When billing issue occurs, user will get a push notification and a full-screen message will be shown upon launch. 

Prompt a user to update his card in case of billing issue.
Prompt a user to update his card in case of billing issue.

Apphud SDK also detects whether user is currently in billing grace period and returns subscription status as active. If you don’t have time implementing this feature by yourself, you can use Apphud

Reducing voluntary churn is important

Handling billing issue is not just a good practice, it also reduces voluntary churn in your app.

Reducing voluntary churn has become more relevant since iOS 13 release, because Apple had simplified the path to the list of active subscriptions. Now they appear at the screen with your apps updates:

Since iOS 13 user can cancel a subscription much easier.
Since iOS 13 user can cancel a subscription much easier.

This means that voluntary churn will increase, because users will more likely don’t forget to cancel their subscription. And you will probably need a solution to reduce churn and increase revenue from existing subscribers.

Rules in Apphud

This mechanic of handling billing issue is called a “Rule”. And it’s just one of our Rules. You can try other rules, that will help you to win back subscribers and reduce churn. Read more in this post.

Sign up to Apphud today and reduce pain of subscriptions implementation and start earning more.

Subscribe to our newsletter!