Overview of Real-Time Notifications
Amazon uses receipts to notify you about a customer’s purchase state for in-app items. A receipt contains the current order state and the in-app item details you defined. Without RTN, you follow a pull model to get the latest receipt status. In the pull model, you must periodically call Receipt Verification Service (RVS) to query Amazon services for updates. However, RTN uses a push model where Amazon provides real-time server push notifications. Amazon’s RTN server sends a notification to your back-end server with information about your customer’s purchase, which you can then verify with RVS. You can use Real-Time Notifications (RTN) in addition to Receipt Verification Service (RVS). The following diagram shows how the RVS and RTN processes interact.
The following is a description of the process shown in the diagram.
Steps 1–5: This is the regular RVS flow.
- User initiates an in-app purchase.
- App forwards the purchase receipt to your app server.
- App server sends a request to RVS server for validation of the receipt.
- RVS server confirms that the receipt is valid.
- Content delivered to the user.
Prerequisites
Before you can use Real-Time Notifications, make sure your environment is ready to receive RTN responses. Because RTN pushes messages to you, Amazon needs a secure, publicly reachable destination to send them to. You must have a back-end server that meets the following requirements:- Exposes an HTTPS endpoint that receives RTN responses
- Handles the HTTPS POST requests that Amazon sends
- Returns a
200response code to acknowledge each message - Uses valid SSL certificates from a trusted certificate provider
Live App Testing for RTN
Before you release your app, use Live App Testing (LAT) to confirm that your endpoint receives and processes Real-Time Notifications correctly. LAT lets you run real in-app purchase transactions in a controlled test environment without affecting live customers. When you make an in-app purchase through LAT, the Amazon server returns an RTN payload with the attributebetaProductTransaction=true. Use this attribute to distinguish test notifications from production notifications so your server handles each appropriately.
Real-Time Notification message details
Real-Time Notifications are delivered through a JSON message to your HTTPS endpoint. Each notification contains the following JSON payload. You can find additional information in the Amazon Simple Notification Service (SNS) Developer Guide. TheMessage attribute of a Real-Time Notification contains an escaped JSON with the following fields.
Supported notification types
RTN messages contain information about each type of in-app purchase (subscriptions, entitlements, and consumables). Amazon might add or change notification types over time. You will be informed of new notification types as they are added. Amazon generally recommends that you ignore any notification types not applicable to you. The following table describes the currently available notification types.| Notification Type | Description |
|---|---|
CONSUMABLE_CANCELLED | Consumable item was voluntarily or involuntarily cancelled. |
CONSUMABLE_PURCHASED | Consumable item was purchased. |
ENTITLEMENT_CANCELLED | Entitlement item was voluntarily or involuntarily cancelled. |
ENTITLEMENT_PURCHASED | Entitlement item was purchased. |
SUBSCRIPTION_AUTO_RENEWAL_OFF | Auto-renew feature for subscription was turned off. |
SUBSCRIPTION_AUTO_RENEWAL_ON | Auto-renew feature for subscription was turned on. |
SUBSCRIPTION_CANCELLED | A subscription was voluntarily or involuntarily cancelled. |
SUBSCRIPTION_CONVERTED_FREE_TRIAL_TO_PAID | An active free trial subscription was converted to paid subscription. |
SUBSCRIPTION_EXPIRED | A subscription was expired. |
SUBSCRIPTION_IN_GRACE_PERIOD | A subscription has entered grace period (if enabled). |
SUBSCRIPTION_OUT_OF_GRACE_PERIOD | User fixes the payment issue/failure of the subscription which was previously in grace period. |
SUBSCRIPTION_MODIFIED_DEFERRED | A subscription plan was modified with the “deferred” proration mode. The subscription plan is scheduled to change at the next renewal date. The current plan remains active until the renewal date. |
SUBSCRIPTION_MODIFIED_IMMEDIATE | A subscription plan was modified with the “immediate” proration mode. The existing plan is canceled with a prorated refund, and the new plan is activated immediately. The notification includes the canceled receipt ID. |
SUBSCRIPTION_PURCHASED | A subscription was purchased. |
SUBSCRIPTION_RENEWED | An active subscription was renewed. |
SUBSCRIPTION_SCHEDULED_TO_END | A subscription is scheduled to end because the auto-renew feature was turned off. Sent 10 days before for a customer’s monthly subscription is scheduled to end. Sent 30 days before a customer semi-annual/annual subscription is scheduled to end. |

