Join us at Adapty Conf in Warsaw on June 13, 2024.
Secure your spot for free!

A complete guide on Apple’s Billing Grace Period

Disha Sharma

Updated: November 22, 2023

16 min read

Content

How to Handle Apple Billing Grace Period in an iOS App

As with any subscription-based service, when an iOS or Android subscription mobile app subscriber’s renewal payment fails, they lose access to their subscription benefits. A good percentage of such subscription renewal failures happen because of reasons like the declining of a payment method or insufficient funds. And a lot of times, subscribers aren’t even aware of these issues – losing access abruptly hugely impacts their app experience.

Apple’s App Store notes that because “such involuntary churn isn’t related to customer satisfaction,” it’s a good idea to create “a user experience that avoids subscriber loss due to a failed renewal.” Apple’s Billing Grace Period provision is all about this. 

Here’s how Apple describes its Billing Grace Period in its announcement post:

“Billing Grace Period lets subscribers whose auto-renewal failed due to a payment issue continue accessing your app’s paid content for a period of time while Apple continues to attempt to collect payment. There won’t be any interruption to the subscriber’s days of paid service or to your revenue if Apple is able to recover the subscription within the grace period.” 

So how does Apple’s Billing Grace Period actually work? Let’s find out. We’ll also see how you can enable it – and why you must!

What is Apple’s Billing Grace Period?

Apple explains that since billing issues cause involuntary iOS app churn – and that it’s not the app subscriber that’s chosen not to renew a subscription in such cases –  the user’s app experience mustn’t get impacted.

In fact, to prevent subscribers from losing access to their app or its premium features in instances of failed billing, Apple introduced its Billing Grace Period feature. Simply put, iOS’s Billing Grace Period is extended access to an app where a subscriber’s subscription failed to renew because of billing issues.

Below you’ve a subscriber whose subscription renewal has failed. When an iOS app’s subscription renewal payment fails, the subscription enters the billing retry state. In this example, since the app maker hasn’t enabled a billing grace period for the app, the subscriber either loses access to the app (if it’s a paid app) or gets downgraded to the free version (if it’s a free app) as soon as the subscription enters the billing retry state:

subscription renewal fail without Apple grace period
A subscription renewal failure

Such subscription payment processing fails can happen for a host of reasons. For example, if a user’s credit card (that they used to sign up) expires, their payment information becomes invalid, and as a result, their app’s subscription auto-renewal payment fails.

You can also see in the above graphic below how Apple starts its billing error recoveries when subscriptions fail to renew. However, in this example, the user loses access to the app (or its premium features) for a full 10 days until Apple can process the subscription payment successfully through its retries.

But when you enable Apple’s grace period for your app, your app subscriber doesn’t lose access to your app or its premium features even after their subscription payment fails. They enjoy uninterrupted access to their app for the whole of the “grace period” while Apple retries processing the failed payments.

Below, you’ve an iOS app user whose subscription renewal failed. However, since the app offers a grace period, the subscriber gets extended access to the app or its premium version while Apple tries to renew. In this case, because Apple is able to process a payment within the grace period, the user doesn’t experience any discontinuation of service: (The app in this example offers a 16-day grace period. You can specify how long your app’s grace periods can be.)

handling app store billing grace period a comprehensive guide google docs 9
A subscription renewal failure with a grace period (and a recovery happening within the grace period)

In the following case, in contrast, Apple fails to collect a subscription payment within the grace period, and so the user loses access post the grace period. However, when Apple is able to collect the payment (and recover the subscription), the subscriber regains access:

handling app store billing grace period a comprehensive guide google docs 10
A subscription renewal failure with a grace period (and a recovery happening post the grace period)

Good to read:

Apple’s Fiscal Calendar 2023 ⟶

There’s more to it… 

Apple’s Billing Grace Period also comes in handy when things like changes to payment policies happen and impact a large user segment at once. Take how the App Store had to stop processing subscription renewal payments for its Indian user base, for instance, when the country’s central bank (RBI) updated its auto-debit guidelines. 

In such situations, having a grace period gives you the time to ask your users to update their payment methods.

And it gives users the time they need to update their payment methods while enjoying uninterrupted access to the features/functionalities or content they pay a premium for. 

Apple’s Billing Grace Period also gives you more days of paid service. For example, if you offer a 28-day grace period, and the billing is successful on the 7th day, you don’t lose any revenue. However, if you don’t offer a billing grace period and the user still gets billed successfully on the 7th day after subscription discontinuation while Apple tries rebilling, you lose about 7 days’ worth of revenue.

How to enable Billing Grace Period for your iOS app

Here are a few simple steps to enable Apple’s Billing Grace Period for your iOS app.

Step #1: To enable Billing Grace Period for your iOS app, access your app inside your App Store Connect account.  

Step #2: Click “Subscriptions” under the Features section. 

Step #3: Next, set up your billing grace period lengths from the Billing Grace period section.

handling app store billing grace period a comprehensive guide google docs 2

Apple offers three grace period durations:

  • 3 days
  • 16 days
  • 28 days 
handling app store billing grace period a comprehensive guide google docs 1

Note that you can set grace periods only at the app level. Suppose you offer weekly, monthly, and yearly subscription plans (products) and set the grace period to be 3 days. In this case, Apple will automatically assign 3-day grace billing periods to all of your plans. Alternatively, if you choose a 28-day Billing Grace Period, Apple will automatically cap your weekly plan’s grace period at 6 days and set a 28-day grace period for your longer plans.

Step #4: Choose the subscribers that are entitled to the billing grace period. 

handling app store billing grace period a comprehensive guide google docs 3

If you choose to enable Billing Grace Period for all users, even subscribers who are on your free introductory offer or trial will get an extension on their subscription benefits. Note that you won’t lose any paid service days here if Apple can rebill them during the grace period. Alternatively, if you enable Billing Grace Period only for subscribers already on a paid plan, users on a free introductory offer/trial won’t get it.

Step #5: Deploy the grace period.

If you want to give your subscription billing grace period a test run, start by deploying it only to your sandbox environment. And if you’re sure, enable it in both your sandbox and production environments. 

handling app store billing grace period a comprehensive guide google docs 4

Finally, click Turn On.. and done!

handling app store billing grace period a comprehensive guide google docs 5

Apple makes it very easy to edit your billing grace period’s settings, like its grace period length, subscriber eligibility, and deployment environment. Any changes you make will reflect within 24 hours of making them.

10 ideas
to increase
paywall conversion

Get an ebook with insights
and advice from top experts

How does billing retry work?

At the heart of Apple’s Billing Grace Period lies its billing retries. If the App Store can’t process a renewal payment, it puts the subscription into the billing retry state, where these retries begin.

Once a subscription enters a billing retry state, Apple attempts to rebill over a period of 60 days. If the App Store can successfully process a subscription renewal payment within this period, it changes the billing date to the date of recovery (when this date is post the grace period, if a grace period is enabled); subsequent renewal payments happen on this date. And if payment retries fail, the subscription expires after the 60-day billing retry period. 

To track billing retries, the App Store uses a special property: “isInBillingRetry.” isInBillingRetry is a boolean value that is either true or false, depending on the state of the subscription. When Apple is able to process an app subscription renewal payment successfully, the value in this field remains “false.” But when the App Store fails to collect a user’s subscription renewal payment, this isInBillingRetry property’s value gets set to “true.” 

Once this happens, with Billing Grace Period enabled, the App Store puts the subscription into the billing grace period.

How to spot users in the Billing Grace Period?

If you can spot your users who enter the billing grace period, you can reach out to them via push notifications, in-app messaging, or channels like emails (if you collect them during your mobile app onboarding) and ask them to check their payment details.

You can tell them that they’ve entered their billing grace period and that their extended access will end when the grace period ends. 

You can also share the best payment methods for paying for their app subscription. Apple, for instance, stresses getting users to maintain their Apple ID balance and use it for payments. 

Said another way: If you spot users in the billing grace period, you can recover a good percent of your involuntary subscription churn. 

And that brings us to the question: “How can you know which user has entered the billing grace period?”
If you use an in-app payments infrastructure solution like Adapty, spotting users that enter the billing grace period is easy, as Adapty automatically captures the “entered_grace_period” subscription event (among 16 other key subscription lifecycle events like the starting, converting, or canceling of a trial):

handling app store billing grace period a comprehensive guide google docs 6 1
Adapty capturing the event of a user entering the grace period

Navigate to Analytics>Charts>Issues inside the Adapty dashboard, and you’ll find data on your grace period. Here’s a high-level snapshot:

handling app store billing grace period a comprehensive guide google docs 7
Adapty showing an app’s grace period user data/trends

For complete details on the users who entered the grace period, head to Profiles & Segments > Profiles, and you’ll see not just the users who are in the grace period but also the users whose subscription payment renewal gave a billing error (this is the state a subscription is in before it enters the grace period):

handling app store billing grace period a comprehensive guide google docs 11
Adapty’s CRM showing users in the Billing Grace Period

Adapty doesn’t just capture this event but can also relay it to your push notification tools like OneSignal and Pushwoosh:

handling app store billing grace period a comprehensive guide google docs 8 1
Using Adapty and push notifications tools to reach out to users in the billing grace period

With these integrations, you can reach out to your users in the grace billing period and ask them to fix their payment issues:

Adapty + OneSignal

Adapty + Pushwoosh

Another way to find your iOS app users who might be in the billing grace period is to review your transaction receipts. Apple suggests checking properties/fields like expiration_intent, is_in_billing_retry_period, and grace_period_expires_date_ms to find subscriptions in the grace period state. You need to read the grace period state and ensure that subscribers have complete access while the grace period is valid.

Wrapping it up…

Apple’s Billing Grace Period provision can be very effective for handling involuntary churn. By enabling a billing grace period for your iOS app, you won’t just recover a good percent of your existing subscribers that you’d otherwise lose to payment processing errors but also retain new subscribers that might be running into billing issues when migrating from their free trial to your app’s paid version.

Also, as you just saw, it only takes a few easy steps to implement Apple’s billing grace period. Even Apple recommends that you enable its Billing Grace Period provision in your app.

Moreover, when you use Apple’s Billing Grace Period with an in-app payments infrastructure solution like Adapty that can track when a user enters their billing grace period and push notification tools like One Signal or Pushwoosh, you can actually reach out to such users and prompt them to fix their payment issues.

Explore Adapty and learn how you can add in-app purchases like consumables, non-consumables, or subscriptions to your iOS or Android app in a few simple steps. Also see how Adapty can help you grow your app, right from learning valuable insights from your app onboarding stage to analyzing your app’s funnel and optimizing your paywalls with A/B tests, experimentation and personalizations. Sign up for Adapty’s free trial.

FAQs

Apple’s Billing Grace Period is the extended duration for which an iOS app subscriber can enjoy an app’s subscription benefits after their free introductory offer or ongoing subscription period is over while Apple tries to rebill them.

The App Store supports 3 default billing grace periods that let you extend to your subscribers a grace period of 3 days, 16 days, or a maximum of 28 days.

“Billing Retry state” is the state that an iOS app subscription enters when the App Store fails to collect its auto-renewal payment (due to billing issues).

You can enable Billing Grace Period in your iOS app by “Turning On” the “Billing Grace Period” setting that you can find in your App Store Connect account’s “In-App Purchases” section.
Unlock Industry Insights
Gain the edge with key insights from our State of in-app subscriptions in the US 2023 report. Essential for app professionals!
Get your free report now
Report in app US 2023 (book)

Recommended posts