App Store Server Notifications V2 in 2026: A Step-by-Step Tutorial for Refunds, Renewals, and Consumption Requests

Apple has closed the version 1 path: version 1 notifications and the App Store Receipts endpoint are deprecated, and the instruction now reads "implement the version 2 endpoint on your server" instead. For an app with live subscriptions this is not a cosmetic migration — the notification stream is how your server learns that a renewal succeeded, that a refund was issued, that billing is being retried, or that Apple is asking you to justify a refund request. This tutorial walks the full 2026 setup: enabling version 2 in App Store Connect, verifying the JWS, mapping every notification type and subtype, and using the App Store Server API for the state that a notification only describes at a point in time.

Step 1 — Fix the two endpoints before you touch App Store Connect

You need one HTTPS URL for production and, optionally, a second one for sandbox; Apple explicitly allows you to use the same URL for both environments. Your server must support TLS 1.2 or later. If the URL contains a port, it must be either 443 or 1024 and above — https://example.com:1234/notifications is a valid shape, a low privileged port is not. And if your edge terminates behind an IP allow list, add Apple's 17.0.0.0/8 subnet, which applies to sandbox and production alike. All of this is documented in Enabling App Store Server Notifications.

Step 2 — Turn on version 2 per environment

In App Store Connect open your app, then App Information > App Store Server Notifications. Production and sandbox are configured separately, and each environment independently chooses version 2 or the deprecated version 1 — which is what lets you run the new format in production while the old one still has to work elsewhere, or the reverse. Apple's stated migration path is to test version 2 in the sandbox environment first and only then move production. One behaviour worth knowing before you start debugging: the TEST notification is always sent in the version 2 format, no matter which version your configured URL expects.

Step 3 — Answer with the right status code, then work asynchronously

Respond with an HTTP status code of 200-206 if the POST was handled successfully. If it was not handled, send a 50x or 40x to have the App Store retry the notification. The practical pattern is: read the body, verify it, enqueue it, reply 200, and do the real work in a worker. Do not hold the connection open while you call your own database, your email provider, or the App Store Server API. Retries are there to protect you from infrastructure failure, not from a slow handler — and every retry you trigger is a duplicate event you then have to suppress.

Step 4 — Decode the payload

The body is a responseBodyV2 object whose only meaningful field is signedPayload, a JWS. Parse it into its header, payload and signature representations, then Base64URL-decode the payload to get the responseBodyV2DecodedPayload. At that level you get notificationType, subtype, version, signedDate and notificationUUID. Exactly one of four data objects is present: data for in-app purchase events, carrying a signedTransactionInfo and — for auto-renewable subscriptions — a signedRenewalInfo; summary, which appears only for a RENEWAL_EXTENSION with the SUMMARY subtype; appData; or externalPurchaseToken, which appears only on an EXTERNAL_PURCHASE_TOKEN notification.

Step 5 — Verify every signature, not just the outer one

All three signed representations — signedPayload, signedTransactionInfo and signedRenewalInfo — carry their own JWS signature, and each has to be validated; use the algorithm named in the header's alg parameter. In practice that means checking the x5c certificate chain up to Apple's published root, which you download from the Apple certificate authority page (the current root for this service is AppleRootCA-G3.cer). Do not hand-roll this: Apple publishes the App Store Server Library for Python, Java, Node.js and Swift, which performs the verification and the decode for you. A handler that Base64-decodes the payload and skips verification is trivially spoofable — anyone who learns your notification URL can grant themselves a subscription.

Step 6 — Map notificationType and subtype onto your entitlements

The version 2 enum defines 23 notification types, and 19 subtypes that qualify some of them; both lists are published on notificationType and subtype. The ones that decide whether a paying customer keeps access:

• SUBSCRIBED — with subtypes INITIAL_BUY, RESUBSCRIBE, UPGRADE and DOWNGRADE. Grant access and record the product identifier, not just "subscribed".
• DID_RENEW — with subtypes BILLING_RECOVERY and BILLING_RETRY. A renewal that arrived after a payment problem still arrives here, so treat it as a normal extension of access.
• DID_FAIL_TO_RENEW — with the GRACE_PERIOD subtype when the customer is inside a grace period. Access usually continues here, which is the whole point of grace periods.
• GRACE_PERIOD_EXPIRED — the grace period ran out. This is the point to downgrade, not at the failed charge.
• EXPIRED — with subtypes VOLUNTARY, BILLING_RETRY and PRODUCT_NOT_FOR_SALE. The last one matters if you pull a product from sale while people still hold it.
• DID_CHANGE_RENEWAL_STATUS (AUTO_RENEW_ENABLED / AUTO_RENEW_DISABLED) and DID_CHANGE_RENEWAL_PREF (UPGRADE / DOWNGRADE) — a customer who turned auto-renew off is still entitled until the period ends, so never revoke on AUTO_RENEW_DISABLED.
• REFUND, REFUND_DECLINED, REFUND_REVERSED, REVOKE and RESCIND_CONSENT — the revocation side. A reversed refund means the money came back to you, so the entitlement has to come back to the customer too.
• CONSUMPTION_REQUEST — Apple is asking for evidence about how the purchase was used; see step 7.
• OFFER_REDEEMED, PRICE_CHANGE, PRICE_INCREASE (ACCEPTED / PENDING), RENEWAL_EXTENDED and RENEWAL_EXTENSION (SUMMARY / FAILURE) — commercial and date changes that usually require a customer notification rather than an access change.
• METADATA_UPDATE, MIGRATION, ONE_TIME_CHARGE, TEST and EXTERNAL_PURCHASE_TOKEN (with the UNREPORTED subtype when Apple generated a token it has no report for).

The full catalogue with the current additions lives in the notifications changelog — Apple adds fields and values over time, so re-read it before you assume your handler is complete.

Step 7 — Answer a CONSUMPTION_REQUEST inside 12 hours

When a customer requests a refund for any product type — consumable, non-consumable, non-renewing or auto-renewable — Apple sends a CONSUMPTION_REQUEST. If the customer consented, you can respond by calling Send Consumption Information with the usage data Apple asks for, and Apple documents a 12-hour response window from the moment the notification arrives. If the customer did not consent, you do not respond at all. Two rules are easy to get wrong: the consent you need for this API is separate from the consent you collected for tracking or advertising, and you are the party responsible for obtaining valid consent before sharing usage data with Apple.

Step 8 — Use the App Store Server API for state, not for the event

A notification describes a moment. Before you write entitlements, resolve the present:

• Get Transaction Info for a single transaction, including its revocation reason and date.
• Get All Subscription Statuses for the authoritative view of a customer's subscriptions.
• Get Refund History when you need the refunds for an original transaction identifier.
• Extend a Subscription Renewal Date to compensate a service outage. Two properties make this a one-way door: after the extension takes effect there is no way to reverse it, and family members' subscriptions are extended automatically while direct requests for a family member's subscription are not supported. The extension period also does not count toward the one year of paid service Apple uses when calculating commission rate.

Step 9 — Prove the pipe works before you rely on it

Call Request a Test Notification and the App Store sends a TEST notification to your endpoint. That call returns a token you pass to Get Test Notification Status within six months to see how your server actually answered. Separately, if your endpoint was down at 3am, Get Notification History returns the version 2 notifications the App Store attempted to send: 180 days in production, 30 days in the sandbox, 20 records per page with a continuation token, and full notification contents. Remember what that history is: each record reflects the state at the time the notification was originally sent, not the current state.

Step 10 — The operational rules that keep the pipeline correct

• Read environment before you write anything. Sandbox traffic reaches sandbox URLs; if a shared handler writes production entitlements from a sandbox event, testing becomes a data incident.
• Deduplicate on notificationUUID. Retries and your own re-processing produce the same event more than once; store the identifier and drop repeats.
• Never treat a notification as a receipt. A build that only listens for SUBSCRIBED and DID_RENEW, and ignores REFUND, REVOKE and REFUND_REVERSED, leaks paid access permanently. Handle the whole lifecycle or hand the verification to Apple's library and ask the Server API.
• Keep your own event log. When a customer disputes access, the notification history and your own log are what let you reconstruct the decision.
• Plan for the endpoint being part of production. It needs monitoring, a request timeout far below the connection budget, and a queue — not a synchronous call chain into your billing system.

Sources

• Apple Developer — App Store Server Notifications: developer.apple.com/documentation/appstoreservernotifications
• Apple Developer — App Store Server Notifications V2: app-store-server-notifications-v2
• Apple Developer — Enabling App Store Server Notifications: enabling-app-store-server-notifications
• Apple Developer — notificationType and subtype enums: notificationtype / subtype
• Apple Developer — responseBodyV2DecodedPayload: responsebodyv2decodedpayload
• Apple Developer — App Store Server API: developer.apple.com/documentation/appstoreserverapi
• Apple — App Store Server Library (Python): github.com/apple/app-store-server-library-python
• Apple — certificate authority: www.apple.com/certificateauthority