Skip to content
AppDues
Log in
Contact salesSign up

App Store Server Notifications: What Each Event Really Fires For

Apple introduced server-to-server subscription notifications in 2017 as a way to cut down on receipt polling. The event names look self-explanatory, but several of them fire under conditions most developers do not expect. This guide maps each notification type to its real trigger, explains where the documented behavior and observed behavior diverge, and gives a checklist for keeping subscription state accurate.

How the notification channel is set up

You register a URL in App Store Connect, and Apple sends POST requests to that endpoint when subscription events occur. The appeal is obvious: instead of repeatedly asking Apple about a subscriber, your server hears about changes as they happen.

That appeal is partly real and partly misleading. Apple's own guidance recommends using these notifications together with receipt validation to confirm a user's current status before granting service. In practice, the notification alone is not a reliable statement of entitlement. Treat it as a hint that something changed, then confirm the current state from the receipt.

The six notification types at a glance

There are six notification types. On a first read, they suggest a clean lifecycle: a purchase produces INITIAL_BUY, a renewal produces RENEWAL, and a cancellation produces CANCEL. That reading is wrong in several important ways.

Use the table below as a working reference. The 'common assumption' column records what the name suggests; the 'actual trigger' column records what the event really indicates based on the behavior described in the original analysis.

Notification behavior reference

The following table is a narrative comparison built from the original analysis. It is not a substitute for Apple's current documentation; verify current behavior against Apple's live docs before relying on any single event.

INITIAL_BUY: the first purchase in a subscription group

INITIAL_BUY fires when the first subscription is purchased within a subscription group. That part matches the name.

The confusing part is the latest_receipt field. Apple's documentation says the base-64 encoded transaction receipt is posted only for RENEWAL or INTERACTIVE_RENEWAL, and only when the renewal succeeds. The original subscription management platform analysis, published in 2018, reported a different observation: latest_receipt appeared on every notification type except CANCEL. That observation is the source publisher's own testing, not a re-verification here, and it may not reflect current behavior. Confirm the current field behavior against Apple's live documentation before depending on either rule.

CANCEL: a refund signal, not a normal opt-out

Among the six event types, CANCEL is the one whose name most reliably leads people astray. It is not the signal that a subscriber has switched off auto-renew in App Store settings. Apple issues it only when a cancellation is processed through customer support, which in practice corresponds to a refund. For the ordinary case — someone deciding not to continue and changing their preference in the App Store — no notification of this kind is delivered at all. That leaves a real blind spot for anyone building retention logic on top of these events. If CANCEL is wired up as the churn trigger, the majority of voluntary opt-outs will pass by unseen. The auto-renew preference recorded in the receipt is where that decision actually shows up, so a receipt read remains the reliable way to find out that a subscriber has chosen to stop renewing.

RENEWAL: reactivation after expiry, not a normal renewal

RENEWAL does not fire on a scheduled renewal. Its actual trigger is a subscription that has already lapsed and is then started again by the user.

That leaves the most-wanted signal, a dependable ping at each renewal so cached expiration dates can be refreshed, without a notification behind it. Receipt updates therefore still need to run on a regular schedule.

INTERACTIVE_RENEWAL: user-initiated reactivation

INTERACTIVE_RENEWAL sits close to RENEWAL. Apple's description covers a customer who renewed interactively after a lapse, either through the app's interface or in App Store account settings, with service available immediately.

Both events concern subscriptions that had already expired. The split comes down to what set the reactivation in motion: INTERACTIVE_RENEWAL originates from the user acting in settings, whereas RENEWAL follows the resolution of a billing issue. For most server logic, that distinction adds complexity without much practical benefit.

DID_CHANGE_RENEWAL_PREF: narrower than it sounds

This event sounds like the answer to a common question: did the subscriber decide to renew or not? Knowing the moment a user opts out is valuable for cohort retention estimates, targeted offers, or a short survey about why they left.

Unfortunately, the event does not deliver that. Its only trigger is a user moving from one product to another inside the same product group. The auto-renew preference in the receipt carries the information developers actually want, yet no notification is sent when that preference changes.

What you can realistically do with these notifications

The practical answer is: not much on their own. The notifications can reduce polling in narrow cases, but only if you interpret each event carefully. Given the cost of wrongly withholding paid content, it is safer to poll more often than to trust a notification as the final word on entitlement.

A reasonable approach is to use notifications as a trigger to re-check the receipt, not as a replacement for that check. That keeps the latency benefit where it exists while preserving correctness.

Decision checklist for handling a notification

Use this checklist when a notification arrives:

  1. Identify the notification type and map it to the actual trigger, not the name.
  2. If the event is CANCEL, treat it as a refund signal and check whether the user still has access through another path.
  3. If the event is RENEWAL or INTERACTIVE_RENEWAL, confirm the subscription had expired before the event; do not assume a scheduled renewal occurred.
  4. If the event is DID_CHANGE_RENEWAL_PREF, check whether the user actually switched products within the same group.
  5. Refresh the receipt to confirm current entitlement before changing access.
  6. Keep a scheduled receipt refresh in place regardless of notifications.
  7. Log the notification payload alongside the receipt state so you can audit mismatches later.

Worked example: a lapse and a later reactivation

Suppose a subscriber lets a subscription expire and does not renew immediately. No RENEWAL event fires at the scheduled renewal time, because RENEWAL only applies after expiry. Later, the subscriber opens the app and restarts the subscription from the app's interface. That produces an INTERACTIVE_RENEWAL event, and service becomes available immediately.

If instead the lapse was caused by a billing problem and the subscriber fixes payment details in settings, the event is RENEWAL. In both cases, the server should refresh the receipt to confirm the new expiration date rather than relying on the event alone.

Two failures that look alike but are not

A refund-driven CANCEL and a voluntary auto-renew opt-out both end with the subscriber losing access eventually, but they arrive through different channels. The CANCEL notification covers the refund path. The opt-out path is only visible in the receipt's auto-renew preference. If your system treats them as the same event, you will either over-count refunds as churn or miss churn entirely.

A second distinction is between a scheduled renewal and a reactivation. A scheduled renewal produces no notification under the behavior described here, while a reactivation produces RENEWAL or INTERACTIVE_RENEWAL. Conflating them can make your renewal metrics look sparse or your reactivation metrics look inflated.

App Store server notification behavior reference
Notification typeCommon assumptionActual triggerReader action
INITIAL_BUYFirst purchase in a subscription groupFirst subscription purchased in a subscription groupConfirm receipt; latest_receipt may be present despite documentation
CANCELUser turned off auto-renewCancellation handled through customer support, effectively a refundDo not treat as churn; check auto-renew preference in receipt
RENEWALSubscription renewed on scheduleSubscription lapsed, then the user started it againRefresh receipt; do not rely on this for scheduled renewals
INTERACTIVE_RENEWALUser renewed from appUser set a lapsed subscription going again from settings or the appRefresh receipt; service is immediate
DID_CHANGE_RENEWAL_PREFUser opted out of renewalUser moved from one product to another inside the same product groupCheck receipt auto-renew preference for opt-out signals
(no event)Scheduled renewal fires an eventNo notification is sent for a normal scheduled renewalKeep scheduled receipt polling in place

Behavior described reflects the original 2018 subscription management platform analysis and may not match current Apple documentation or runtime behavior. Verify against Apple's live documentation before relying on any single event.

Frequently asked questions

Does a CANCEL notification mean the user turned off auto-renew?

No. CANCEL fires when a subscription is cancelled through customer support, which is effectively a refund. A normal auto-renew opt-out in App Store settings does not produce this notification. To detect opt-outs, check the auto-renew preference in the receipt.

Why does RENEWAL not fire when my subscription renews?

RENEWAL is sent when a subscription has already expired and the user later restarts it. A scheduled renewal does not produce this event, so you still need to refresh receipts on a regular schedule to keep expiration dates current.

Is latest_receipt only included for RENEWAL and INTERACTIVE_RENEWAL?

Apple's documentation says latest_receipt is posted only for RENEWAL or INTERACTIVE_RENEWAL and only when the renewal succeeds. The original subscription management platform analysis, published in 2018, reported latest_receipt present on every notification type except CANCEL. That finding is the source publisher's own testing, not a re-verification here. Confirm current behavior against Apple's live documentation before depending on either rule.

What is the difference between RENEWAL and INTERACTIVE_RENEWAL?

Both apply only to subscriptions that had already expired. INTERACTIVE_RENEWAL is initiated by the user from settings or the app, while RENEWAL follows resolution of a billing issue. For most server logic, the distinction adds complexity without much practical benefit.

Can I stop polling receipts if I use server notifications?

Not safely. The notifications do not cover scheduled renewals or normal auto-renew opt-outs, and Apple recommends using them together with receipt validation. Keep scheduled receipt polling in place and treat notifications as a trigger to re-check state.