Article

Enabling Status Update Notifications

Use server notifications from the App Store to monitor and respond to users' subscription status changes.

Overview

A status update notification is a server-to-server notification service for auto-renewable subscriptions. App Store sends notifications to your server informing you of real-time changes in a subscription's status.

Using the status update notification service is optional but recommended, especially if you offer subscription services across multiple platforms and you need to keep the subscription records updated. After you set up your server, you can start receiving notifications at any time by adding a server URL in App Store Connect.

Use the information from the notifications along with receipt validation to validate a user's current subscription status and provide them with appropriate service or promotional offers.

Configure Your Server to Receive Notifications

To receive status update notifications from the App Store:

Once you have taken these steps, your server is ready to receive status update notifications.

Receive Status Update Notifications

The App Store delivers JSON objects via an HTTP POST to your server for notable subscription events. Your server is responsible for parsing, interpreting, and responding to all status update notification posts.

The statusUpdateNotification is an HTTP POST. The body of the POST contains these data elements:

environment

Specifies whether the notification is for a sandbox or a production environment using the values Sandbox or PROD.

notification_type

Describes the subscription event that triggered the notification, as listed in Table 1.

password

Contains the same value as the shared secret you POST when validating receipts.

original_transaction_id

Contains the same value as the original_transaction_id in the receipt. Use this value to relate multiple iOS 6-style transaction receipts for an individual customer’s subscription.

cancellation_date

Specifies the date and time that Apple customer support canceled a transaction or the customer upgraded their subscription. This value is the same as the cancellation_date in the receipt. Posted only if the notification_type is CANCEL.

web_order_line_item_id

Specifies the primary key for identifying a subscription purchase. This value is the same as the web_order_line_item_id in the receipt. Posted only if the notification_type is CANCEL.

latest_receipt

Contains the latest base-64 encoded transaction receipt. Posted only if the notification_type is RENEWAL or INTERACTIVE_RENEWAL, and only if the renewal is successful.

latest_receipt_info

Contains the JSON representation of the latest_receipt. Posted only if renewal is successful. Not posted for notification_type CANCEL.

latest_expired_receipt

Contains the base-64 encoded transaction receipt for the most recent renewal transaction. Posted only if the subscription expired.

latest_expired_receipt_info

Contains the JSON representation of the latest_expired_receipt. Posted only if the notification_type is RENEWAL or CANCEL or if renewal failed and subscription expired.

auto_renew_status

Indicates the current renewal status for an auto-renewable subscription product as a boolean value ("true", "false"). This is the same as the auto_renew_status in the receipt.

auto_renew_adam_id

Indicates the user's preferred Apple ID for renewing the auto-renewable subscription in App Store Connect.

auto_renew_product_id

Indicates the product identifier of the auto-renewable subscription that the user's subscription renews. This value is the same as the auto_renew_product_id in the receipt.

expiration_intent

Indicates the reason a subscription expired. This is the same as the expiration_intent in the receipt. Posted only if notification_type is RENEWAL or INTERACTIVE_RENEWAL.

The App Store posts notifications for subscription events that are represented by the following notification types.

Table 1

Notification Types

INITIAL_BUY

Occurs at the initial purchase of the subscription. Store the latest_receipt on your server as a token to verify the user’s subscription status at any time, by validating it with the App Store.

CANCEL

Indicates that the subscription was canceled either by Apple customer support or by the App Store when the user upgraded their subscription. The cancellation_date key contains the date and time when the subscription was canceled or upgraded.

RENEWAL

Indicates successful automatic renewal of an expired subscription that failed to renew in the past. Check expires_date to determine the next renewal date and time.

INTERACTIVE_RENEWAL

Indicates the customer renewed a subscription interactively, either by using your app’s interface, or on the App Store in account settings. Make service available immediately.

DID_CHANGE_RENEWAL_PREF

Indicates the customer made a change in their subscription plan that takes effect at the next renewal. The currently active plan is not affected.

DID_CHANGE_RENEWAL_STATUS

Indicates a change in the subscription renewal status. Check the timestamp for the data and time of the latest status update, and the auto_renew_status for the current renewal status.

Respond to Status Update Notifications

Your server should send an HTTP status code to indicate whether the status update notification post succeeded:

  • Send HTTP 200 if the post was successful. Your server is not required to return a data value.

  • Send HTTP 50x or 40x to have the App Store retry the notification if the post was not successful. The App Store makes several attempts to retry the notification over a period of time but eventually stops after continued failed attempts.

Process Events with Up-to-Date Information

Once you enable status update notifications, you have up-to-date information on subscription status. Use the notification along with the latest receipt when you process events and update a user's service or promotional offers:

  • In your app, verify the latest receipt with the App Store. See Receipt Validation Programming Guide for more information.

  • Validate the user's current subscription status by cross-referencing the latest receipt with the latest status update notification using the original_transaction_id key.

See Also

Working with Subscriptions

Offering a Subscription Across Multiple Apps

Support a single auto-renewable subscription across multiple apps.