Skip to content
AppDues
Log in
Contact salesSign up

iOS Subscription Grace Periods: Enable and Parse Them

When a renewal payment fails, a subscriber does not have to lose access immediately. Apple's Billing Grace Period keeps entitlement active for the early part of the billing retry window, giving the payment method time to be fixed. This guide covers the two implementation steps: turning the feature on in App Store Connect and teaching receipt verification to use the new grace period date.

What a grace period changes

Billing failures are usually mundane: a card has expired, been replaced, or been declined for another reason. Without a grace period, the subscription can end as soon as the renewal fails, even though the subscriber may fix the payment method during Apple's retry attempts.

With Billing Grace Period enabled, access continues through the beginning of that retry state. The feature applies to iOS and macOS in-app subscriptions. It does not replace retry logic or payment recovery; it changes how long entitlement lasts while retries are still possible.

Enable it, then update verification

Support requires two separate changes. First, enable the feature for the app. Second, update receipt verification so it recognises the grace period expiry.

Checklist:

  • Confirm the app has at least one subscription product.
  • Open the app in App Store Connect.
  • Go to Features, then In-App Purchases.
  • Find Billing Grace Period and choose Turn On.
  • Confirm the prompt, including that purchase code has no bugs and the developer agreement has been read.
  • Update the receipt verification server to parse pending renewal info.
  • Test with a receipt that contains a grace period date and confirm the later of the two expiry dates is used.

If enabling the setting does not work in one browser, trying Safari was reported to resolve the issue for some developers.

Parsing pending renewal info

Once enabled, Apple adds grace period information to the pending renewal info section of the verifyReceipt response when a user enters the billing retry period. That section is an array of per-subscription dictionaries, so match each entry to its transaction using original_transaction_id.

The key fields to check are:

  • in_app: transactions with their normal expiry dates.
  • pending_renewal_info: renewal state for each subscription, including billing retry status.
  • grace_period_expires_date_ms: the grace period end date in milliseconds.
  • original_transaction_id: the join key between a pending renewal entry and its transactions.

The example receipt and the calculation logic are provided in protected modules code0001 and code0002.

Calculate the effective expiry

The usual calculation finds the latest expires_date_ms across in_app transactions for a subscription. Grace periods add one more comparison: find the latest grace_period_expires_date_ms across pending renewal entries for the same original_transaction_id, then take the maximum of the transaction expiry and the grace period expiry.

A common mistake is to replace the transaction expiry with the grace period date unconditionally. That can shorten access when the normal expiry is later. Another mistake is to compare dates across different subscriptions. Group both sets of dates by original_transaction_id first, then compare within each group.

Worked example: if a transaction expires on 24 February 2019 and its pending renewal entry shows a grace period ending on 11 June 2019, the effective expiry is the June date. If the grace period date were earlier than the transaction expiry, the transaction expiry would remain effective.

Apple versus Google

Google's implementation is simpler for existing code because it adjusts the affected transaction's expiry date directly, so grace period support can work without a separate step. Apple's design keeps the grace period date separate, which is more explicit but requires the extra comparison described above.

That extra logic is not difficult, but it is easy to overlook when receipt verification already handles multiple transactions, trials, and intro offers. Treat grace period parsing as part of entitlement calculation, not as an optional display field.

Grace period implementation checklist
CheckWhat to verify
App Store Connect settingBilling Grace Period is turned on for the app
Receipt fieldgrace_period_expires_date_ms is present in pending_renewal_info
Join keyEntries are matched by original_transaction_id
Effective expiryMaximum of transaction expiry and grace period expiry

Use the later date within each subscription; do not compare dates across different original_transaction_id values.

Frequently asked questions

Is Billing Grace Period enabled per app or per product?

Grace periods are set per app, not per subscription product. The app must have at least one subscription product to be eligible, and the setting is turned on in App Store Connect under Features, then In-App Purchases, then Billing Grace Period.

Where does the grace period end date appear in a receipt?

Look in pending_renewal_info for grace_period_expires_date_ms, matched to the transaction by original_transaction_id. Compare that date with the latest expires_date_ms from in_app for the same subscription and use the later date.

How does Apple's approach differ from Google's?

Google's approach changes the affected transaction's expiry directly, so existing expiry logic can work without a separate comparison. Apple's approach adds a separate grace period date that receipt verification must compare against the transaction expiry.

{
    "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"
        }
    ]
}