Article

Enabling Server-to-Server Notifications

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

Overview

Server-to-server notifications (previously known as statusUpdateNotifications) are a service for auto-renewable subscriptions. The App Store sends notifications to your server of real-time changes in a subscription's status.

Using the server-to-server 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 notifications along with receipt validation to validate a user's current subscription status and provide them with services or promotional offers based on that status.

Configure Your Server to Receive Notifications

To receive server notifications from the App Store:

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

Receive Server-to-Server 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 server-to-server notification posts.

The server-to-server notification 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.

cancellation_date

Specifies the date and time the App Store processed the refund for a subscription either because the customer requested a cancelation through Apple customer support or upgraded their subscription, in a date-time format similar to the ISO 8601.

cancellation_date_pst

Specifies the date and time the App Store processed the refund for a subscription either because the customer requested a cancelation through Apple customer support or upgraded their subscription, in the Pacific Time zone.

cancellation_date_ms

Specifies the date and time the App Store processed the refund for a subscription either because the customer requested a cancelation through Apple customer support or upgraded their subscription, in UNIX epoch time format, in milliseconds. Use this time format for processing dates.

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.

latest_receipt

Contains the latest Base64-encoded transaction receipt.

latest_receipt_info

Contains the JSON representation of the latest_receipt. Note that this field is an array in the receipt but a single object in server-to-server notifications.

latest_expired_receipt

Contains the Base64-encoded transaction receipt for the most recent renewal transaction.

latest_expired_receipt_info

Contains the JSON representation of the latest_expired_receipt. Note that this field is an array in the receipt but a single object in server-to-server notifications.

auto_renew_status

Indicates the current renewal status for an auto-renewable subscription product as a boolean value ("true", "false"). Note that these values are different from those of the auto_renew_status in the receipt.

auto_renew_product_id

Indicates the product identifier of the auto-renewable subscription that the user's subscription renews.

auto_renew_status_change_date

Specifies the date and time when the subscription renewal status was updated, in a date-time format similar to the ISO 8601.

auto_renew_status_change_date_pst

Specifies the date and time when the subscription renewal status was updated, in the Pacific Time zone.

auto_renew_status_change_date_ms

Specifies the date and time when the subscription renewal status was updated, in UNIX epoch time format, in milliseconds. Use this time format for processing dates. Check auto_renew_status to get the latest value.

The App Store posts notifications for subscription events represented by the types in Table 1.

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 auto_renew_status_change_date_ms and the auto_renew_status in the JSON to know the date and time when the status was last updated and the current renewal status.

Respond to Server-to-Server Notifications

Your server should send an HTTP status code to indicate whether the server-to-server 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 server-to-server notifications, you have up-to-date information on subscription status. Use the notification along with the latest receipt when you process events:

See Also

Working with Subscriptions

Handling Subscriptions Billing

Build logic around the date and time constraints of subscription products, while planning for all scenarios for which you should control access to content.

Offering a Subscription Across Multiple Apps

Support a single auto-renewable subscription across multiple apps.

Reducing Involuntary Subscriber Churn

Prevent unintentional loss of subscribers due to billing issues.