Migrating to Notifications V2

iOS only. This guide applies to Apple's App Store Server Notifications. Google Play uses a single version of Real-time Developer Notifications, so there is no V1 → V2 migration on Android, just follow the Google Play webhook setup.

If you're currently using App Store Server Notifications Version 1 (either with your own endpoint or another service), you can switch to RefundShield without any downtime.

What's Different in V2?

Version 2 of App Store Server Notifications uses signed payloads (JWS) for security and includes a richer set of notification types, including CONSUMPTION_REQUEST, which is what enables refund protection.

Note: CONSUMPTION_REQUEST is only available in V2. If you're on V1, Apple is not giving you a chance to respond to refund requests.

Migration Steps

1. Set up RefundShield: add your app and credentials as described in the App Store Connect Credentials guide
2. Update the notification URL in App Store Connect to your RefundShield webhook URL
3. Switch the version from V1 to V2 in the same settings panel
4. Save: the change takes effect immediately

What Happens to V1 Notifications?

Once you switch to V2, Apple stops sending V1 notifications. There is no overlap period. Any V1 notifications in flight will still be delivered, but new ones will use V2 format.

If You Use V1 for Other Purposes

If your backend currently processes V1 notifications for other purposes (e.g., subscription status tracking), you'll need to update your code to handle V2 format. Apple provides a migration guide in their documentation.

RefundShield only processes refund-related notifications. Other notification types (like subscription renewals) are forwarded to Apple as-is, they won't interfere with your existing logic if you handle them separately.