---
title: "Implementing iOS Subscription Grace Periods"
description: "Extend a subscriber’s access to your app while they are in a billing issue state."
language: "en"
publishedAt: "2019-09-13T09:49:02Z"
updatedAt: "2019-09-13T09:49:02Z"
authors:
  - name: "Jacob Eiting"
    url: "https://www.revenuecat.com/blog/author/jacob-eiting"
category: "Engineering"
categoryUrl: "https://www.revenuecat.com/blog/engineering"
readingTime: 2
canonical: "https://www.revenuecat.com/blog/engineering/ios-subscription-grace-periods"
---

# Implementing iOS Subscription Grace Periods

Extend a subscriber’s access to your app while they are in a billing issue state.

## Table of contents

- [iOS Grace Periods](#ios-grace-periods)
- [Enabling Billing Grace Period](#enabling-billing-grace-period)
- [Parsing the Pending Renewal Info](#parsing-the-pending-renewal-info)
  - [Example Receipt with Grace Period](#example-receipt-with-grace-period)
- [A Better Way](#a-better-way)
- [References](#references)

## iOS Grace Periods

In September 2019, Apple surprisingly [announced](https://developer.apple.com/app-store-connect/whats-new/?id=billinggraceperiod) they’d added support for grace periods to iOS and macOS in-app subscriptions. Grace Periods allow you to extend a subscriber’s access to your app while they are in a [billing issue state](https://developer.apple.com/documentation/storekit/in-app_purchase/reducing_involuntary_subscriber_churn?language=objc#overview). Billing issues happen, usually, when the users credit card on file with the App Store is declined for some reason (expired, etc.)

‍

![](https://cdn.sanity.io/images/c3qnx9b0/production/cc320982618c57a23a9ed10f81c0b4f5001a0941-1444x911.png)

Grace periods extend the subscription of a user for the beginning part of the billing retry state.

If you enable Grace Periods in App Store Connect, a new field will appear in the pending renewal info section of the StoreKit receipt whenever a user enters the billing retry period.

Supporting grace periods on iOS requires two things from the developer:

1. Enabling them in App Store Connect
1. Adding support for them in your receipt verification server
## Enabling Billing Grace Period

Grace periods are enabled on a per app basis and your app needs to have at least one subscription product to be eligible.

To turn on Billing Grace Period, navigate to your app in App Store Connect. In the toolbar, click **Features**, and in the left column, click **In-App Purchases**. You’ll see a new ‘*Billing Grace Period*’ section with a button to **Turn On**.

‍

![](https://cdn.sanity.io/images/c3qnx9b0/production/3c9d363fcf17ec4ccab8314c1e37ec43b62307b6-959x453.png)

You’ll get a popup window to confirm, and agree that your purchase code has no bugs and you’ve read the entire developer agreement.

‍

![](https://cdn.sanity.io/images/c3qnx9b0/production/8d1a9c6832810af59e60ea2c4ea520493783e97e-523x233.png)

*Note: Some developers experienced issues enabling Billing Grace Period that were resolved by switching to Safari.*

## Parsing the Pending Renewal Info

To provide the new grace period expiration date, Apple has added a new field to the pending renewal info section of the `/verifyReceipt` response. The pending renewal info on the receipt response is an array of dictionaries that contains per-subscription information, like renewal intents, original transaction versions, and billing issue states.

### Example Receipt with Grace Period

```javascript
{
    "in_app": [
    {
        "quantity": "1",
        "product_id": "com.products.monthly",
        "transaction_id": "580000296563423",
        "original_transaction_id": "580000296512323",
        "purchase_date": "2018-11-24 15:03:03 Etc\/GMT",
        "purchase_date_ms": "1543071783000",
        "purchase_date_pst": "2018-11-24 07:03:03 America\/Los_Angeles",
        "original_purchase_date": "2018-11-24 15:03:04 Etc\/GMT",
        "original_purchase_date_ms": "1543071784000",
        "original_purchase_date_pst": "2018-11-24 07:03:04 America\/Los_Angeles",
        "expires_date": "2019-02-24 15:03:03 Etc\/GMT",
        "expires_date_ms": "1551020583000",
        "expires_date_pst": "2019-02-24 07:03:03 America\/Los_Angeles",
        "web_order_line_item_id": "580000080123351",
        "is_trial_period": "false",
        "is_in_intro_offer_period": "false"
      },
    ],
    "pending_renewal_info": [
        {
          "expiration_intent": "2",
          "grace_period_expires_date": "2019-06-11 13:43:59 Etc\/GMT",
          "auto_renew_product_id": "com.products.monthly",
          "original_transaction_id": "580000296512323",
          "is_in_billing_retry_period": "0",
          "grace_period_expires_date_pst": "2019-06-11 06:43:59 America\/Los_Angeles",
          "product_id": "com.products.monthly",
          "grace_period_expires_date_ms": "1560260639000",
          "auto_renew_status": "0"
        }
    ]
}
```

‍The `/verifyReceipt` response will contain two interesting keys: the `in_app` array of transactions, and the `pending_renewal_info`.

Without grace periods, the normal mechanism for determining an expiration date would be to loop through the `in_app` array and find the latest expiration date. With grace periods, it becomes slightly more complicated: you also need to loop through the `pending_renewal_infos` and map any infos to their respective transactions and take the maximum between the grace period expiration and the transaction expiration.

```javascript
 response = get_verify_receipt_response(shared_secret, b64_encoded_receipt)

  # Find the max expires date
  expires_date_by_subscription = {}
  for tx in response['in_app']:
    old_date = expires_date_by_subscription[tx.original_transaction_id]
    if old_date is None:
      old_date = 0	
    expires_date_by_subscription[tx.original_transaction_id] = max(old_date, int(tx.expires_date_ms))

  # Find the grace period expiration dates
  grace_periods_by_subscription = {}
  for info in response['pending_renewal_infos']:
    old_date = grace_periods_by_subscription[info.original_transaction_id]
    if old_date is None:
      old_date = 0	
    grace_periods_by_subscription[info.original_transaction_id] = max(old_date, int(info.grace_period_expires_date_ms))	

  # Find the max of the two 
  expiration_dates = {}
  for subscription in grace_periods_by_subscription:
    if subscription in grace_periods_by_subscription:
      expiration_dates[subscription] = max(grace_periods_by_subscription[subscription], expires_date_by_subscription[subscription])
    else:
      expiration_dates[subscription] = expires_date_by_subscription[subscription]
```

It’s not a terribly complicated problem to solve, but it does add [one more thing](/blog/ios-subscriptions-are-hard) you need to think about when supporting in-app subscriptions.

## A Better Way

This is an instance where the support for grace periods coming out of Mountain View is actually better implemented. Google’s implementation allows you to skip a step by just modifying the expires date of the affected transaction, essentially giving you grace period support “for free.”

Also, if you are user of [RevenueCat](https://www.revenuecat.com/), grace periods for Apple and Google are automatically detected and handled by our receipt server and SDK.

## References

1. [https://developer.apple.com/app-store-connect/whats-new/?id=billinggraceperiod](https://developer.apple.com/app-store-connect/whats-new/?id=billinggraceperiod)
1. [https://help.apple.com/app-store-connect/#/dev58bda3212](https://help.apple.com/app-store-connect/#/dev58bda3212)
1. [https://developer.apple.com/documentation/storekit/in-app_purchase/reducing_involuntary_subscriber_churn?language=objc](https://developer.apple.com/documentation/storekit/in-app_purchase/reducing_involuntary_subscriber_churn?language=objc)
1. [https://developer.apple.com/documentation/storekit/in-app_purchase/reducing_involuntary_subscriber_churn?language=objc](https://developer.apple.com/documentation/storekit/in-app_purchase/reducing_involuntary_subscriber_churn?language=objc)
‍