What’s new in Apphud: SplitMetrics Acquire Integration, Experiments Improvements, SDK UpdatesLet’s see
Why Apphud?PricingContact
October 21, 2019
9 min read

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.

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 a user updates their 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.

All in all, the Apple grace period offers its users favorable conditions. If the customer manages to recover within the grace period, there will be no interruption in the days that they paid for the provided service nor in the revenue you will get for auto-renewable subscriptions

If billing error recoveries are made after the expiration of the grace period but during the total billing retry period, they will continue to have the existing behavior, and the renewal will happen on the recovery day. With that, a new billing cycle will start. Luckily for the customers, they will not have to pay for the provided services within the grace period.

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 Does Billing Retry Work?

If a subscription period is close to its expiration, the card added by the user is charged by Apple. If this operation fails, a new status called “Billing Retry state” is applied to the customer. They may be subject to it for 60 days max. 

On the next day of renewal, there will be an attempt by Apple to renew the subscription till the customer is in this Billing Retry state. Until it is finished, the subscribers are not able to use add-ons they have acquired before in the app. Should the payment be a success, the recurring payments will resume in 10 days. This makes it more difficult to analyze subscriptions and negatively affects the user’s level of contentment with the service.  

There will be is_in_billing_retry_period and expiration_intent fields in the user receipt. They mean that there was an unsuccessful attempt to receive a payment.

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

The iOS receipt validation service will help you with this. 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 <code class='inline-code'>is_in_billing_retry_period</code> 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 themself.

Notify user about billing issue in your app

In both cases, it's a good practice to notify users about billing issue and prompt them to update payment method.

You can implement some banner view or a full-screen controller that will navigate a user to their 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 does it work in Apphud?

Apple’s subscription grace period is definitely a great tool to put to use. 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 their card in case of billing issuePrompt a user to update their 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 has simplified the path to the list of active subscriptions. Now they appear on the screen with your apps updates:

Since iOS 13 user can cancel a subscription much easierSince 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

UPDATE. Since the publication of the article Rules has been significantly improved in Apphud. Now we support scheduled and manual push campaigns, allowing you to run campaigns whenever you want to your custom audience.

This mechanic of handling billing issues 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.

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

Co-founder at Apphud
Ex iOS app and game developer. 11 years in the industry since iOS 3. More than 50 apps are in the background with 4 exits. Entrepreneur and traveler.