Developer Console
Sign In
Sign In
Developer Console

Understanding Real-Time Notifications

Real-Time Notifications (RTN) are server-to-server push notifications that provide comprehensive data about in-app purchases in real time. You can use this information to monitor purchase state changes associated with your customer’s in-app purchasable items.

Overview of Real-Time Notifications

Amazon notifies developers about a user’s purchase state of in-app items via receipts. A receipt contains information about the IAP that developers define at the time of submitting an app along with order state. Currently, to get the latest receipt status, you need to follow a pull model by querying Amazon services by calling Receipt Verification Service (RVS) periodically.

With Real-Time Notifications, 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.

Real-Time Notifications can be used in addition to the existing RVS infrastructure. The diagram below demonstrates how the RVS and RTN processes interact. See the step breakdown below for detailed information about the processes.

Steps 1-5: These steps follow the request flow mentioned in the Receipt Verification Service Overview.

Step 6: Amazon Real-Time Notifications (RTN) sends a notification message about the customer’s in-app purchase to your app server (the developer’s back-end server).

Step 7: The app server sends a request to RVS server for validation of the receipt and obtains all information related to the receipt.

Step 8: The RVS server confirms the receipt’s validity and returns information associated with the receipt.

The Real-Time Notification flow (Steps 6-8) does not wait on the completion of the RVS flow (Steps 1-5) to be triggered. Both flows can be triggered in parallel.

Prerequisites

Before you can use Real-Time Notifications, you need to make sure your environment is set up to receive the RTN responses. Ensure you have a secure back-end server that meets the following requirements:

  • Your back-end server needs an HTTPS end point to receive RTN responses.
  • The back-end server must be able to handle HTTPS POST request sent by Amazon.
  • The back-end server must use valid SSL certificates from a trusted certificate provider.

Live App Testing for RTN

See the steps below to set up Live App Testing (LAT) for RTN.

  1. Execute an IAP purchase under Live App Testing.
  2. The Amazon server returns an RTN payload with the attribute betaProductTransaction=true.

Real-Time Notification Message Details

Real-Time Notifications are delivered via 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.

The Message attribute Real-Time Notification contains an escaped JSON with the following fields.

Field Data Type Description Example Response
receiptId String Unique identifier for the purchase. Max string length 200 characters and can include alphanumeric values and punctuation kyplB1fdRX1m6/GNAVW0l6jv9Nl1V/GemSopKBHM84w=
relatedReceipts Map Additional receipts that are associated with the notification sent cancelledReceiptId (Unique identifier for the previously cancelled receipt for SUBSCRIPTION_MODIFIED_IMMEDIATE notification)
appUserId String Identifier representing a distinct Amazon customer for your Appstore app. Max string length 128 characters and can include alphanumeric values and punctuation wE1EG1gsEZI9q9UnI5YoZ2OxeoVKPdR5bvPMqyKQq5Y=:1:11
notificationType String Notification type See the Supported Notifications table in the next section for details and examples.
appPackageName String App package name that identifies the app com.myapp.sample.android
timestamp Long Integer Epoch time 1402008634018
betaProductTransaction Boolean Indicates if the transaction is for Live App Testing product true/false

Supported Notification Types

RTN messages contain information about or each type of in-app purchase (subscriptions, entitlements, and consumables). The tables below describe the notifications that are currently available.

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.

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_PURCHASED A subscription was purchased.
SUBSCRIPTION_AUTO_RENEWAL_OFF Auto-renew feature for subscription was turned off.
SUBSCRIPTION_CANCELLED A subscription was voluntarily or involuntarily cancelled.
SUBSCRIPTION_EXPIRED A subscription was expired.
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.
SUBSCRIPTION_AUTO_RENEWAL_ON Auto-renew feature for subscription was turned on.
SUBSCRIPTION_RENEWED An active subscription was renewed.
SUBSCRIPTION_CONVERTED_FREE_TRIAL_TO_PAID An active free trial subscription was converted to paid subscription.
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.

FAQs

Answers to Frequently Asked Questions (FAQs) about Real-Time Notifications.

Q1. What is the format of Real-Time Notification messages?
Real-Time Notifications are delivered in JSON messages to your specified HTTPS endpoint. See “Real-Time Notification Message Details“ above for more details.
Q2. Will notifications be delivered in the exact order they were published?

The Amazon SNS service attempts to deliver messages from the publisher in the order they are published. However, network issues could potentially result in out-of-order messages at the HTTPS end point. It is recommended to check the timestamp attribute in the payload to check for out-of-order messages.

Q3. What are the possible delivery mechanisms supported?

Currently, we support only HTTPS endpoint for delivering notifications. Please refer to the Amazon SNS documentation for the required steps to set up the HTTPS endpoint.

Q4. What is the scope of origination of notification traffic?

AWS provides a list of Amazon IP addresses from which the traffic originates. Whenever there is a change in IP address space, AWS provides a mechanism to notify subscribers. Please refer to AWS IP address ranges documentation for the current list of IP address ranges.

Q5. How can I test my HTTPS endpoint with the test transaction?

You can test your HTTPS endpoint with Live App Testing (LAT). See Live App Testing for RTN above for details.

Q6. Do I need to call the RVS API for all the notification messages?

Yes, it is recommended to call the Receipt Verification Service (RVS) API to get the latest information about the receipt.

Q7. What is the SLA associated with the notification message?

The Real-Time Notifications service does not offer an official latency SLA. However, most notifications should be published within a few seconds of the event occurrence.

Q8. Can I create an allow list of Amazon IP address?

Yes, but this is optional. You can approve Amazon IP addresses so that Amazon can communicate with your servers. Check this list periodically for changes.

Last updated: May 22, 2024