Tutorial: Subscribe to the ORDER_CHANGE Notification
Learn how to subscribe to the ORDER_CHANGE
notification.
This tutorial covers how to use the ORDER_CHANGE
notification, which is sent whenever there is a change to the status of order availability. Subscribing to this notification will help decrease your order processing workload and improve the performance of your integration with Amazon Selling Partner API.
Benefits of the ORDER_CHANGE
notification
ORDER_CHANGE
notificationThe ORDER_CHANGE
notification offers the following benefits:
- Enough information to automate your subsequent workflows: You can now use the
ORDER_CHANGE
payload to get information about orders. The notification is also designed to notify you in the event a buyer requests a cancellation. - Events to get notified as needed: You will no longer need to keep polling the Orders API, saving server capacity.
- Consolidated payload at the order level: If you have multiple order items in the order, you will receive consolidated payloads at the order level. Triggering at the order level allows you to create a more efficient integration workflow.
- Event filters allow for filtered subscriptions: Event filters are now supported with the
ORDER_CHANGE
notification. With event filters, you can subscribe with a relevantOrderChangeType
to filter order notifications relevant to your business. We currently support buyer-requested cancellation and order status change. - Event filters extensible for future use cases: This new notification allows Amazon to add additional events related to orders in the future, like certain Easy Ship events or curbside pickup events.
- Time of change added to provide real-time event changes: The
ORDER_CHANGE
notification has the time of order change as a field in the payload. Implementing this into your integration allows you to provide real-time updates for your sellers.
Tutorial
The following tutorial will help you subscribe to and use the ORDER_CHANGE
notification.
Prerequisites
Before you subscribe to the ORDER_CHANGE
notification, your developer profile and app must have the Inventory and Order Tracking role or Amazon Fulfillment role assigned.
Important:
The previous version of this notification,
ORDER_STATUS_CHANGE
, have been deprecated. Subscribe to theORDER_CHANGE
notification and delete your subscription toORDER_STATUS_CHANGE
.
- Call the
getSubscription
operation to fetch thesubscriptionId
ofORDER_STATUS_CHANGE
.- With the
subscriptionId
, use thedeleteSubscriptionById
operation to delete the subscription to theORDER_STATUS_CHANGE
notification. Remember that thedeleteSubscriptionById
operation is a grantless operation.
Step 1. Subscribe to the ORDER_CHANGE
notification
ORDER_CHANGE
notification- Create a subscription to
ORDER_CHANGE
using processing directives.
The processingDirective
is used to pass additional information to the subscription to control the processing of notifications. For example, you can use eventFilter
to filter out notifications for a specific Order Change Type.
To use eventFilter
for ORDER_CHANGE
notifications, make sure to include eventFilterType
and orderChangeTypes
in the create subscription step.
-
Call the
createSubscription
operation. -
Add the parameter
ORDER_CHANGE
in thenotificationType
path variable.
The following payload shows how to set a filter to receive only notifications about order status changes. Make sure to include your destinationId
:
POST https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/ORDER_CHANGE
{
"payloadVersion": "1.0",
"destinationId": "e22gf420-1606-47c4-a393-91df6648d3da",
"processingDirective": {
"eventFilter": {
"orderChangeTypes": [
"OrderStatusChange"
],
"eventFilterType": "ORDER_CHANGE"
}
}
}
If the request is successful, you will receive this response:
{
"payload": {
"subscriptionId": "92d519e4-f208-493b-9092-d70cf546c383",
"destinationId": "e22gf420-1606-47c4-a393-91df6648d3da",
"payloadVersion": "1.0",
"processingDirective": {
"eventFilter": {
"orderChangeTypes": [
"OrderStatusChange"
],
"eventFilterType": "ORDER_CHANGE"
}
}
}
}
If you want to receive BuyerRequestedChange
information, you must include BuyerRequestedChange
in orderChangeTypes
to filter out relevant notifications. To receive order notifications from all order change types, add the eventFilterType
setting when subscribing to this notification.
Sample payload:
{
"destinationId": "e22gf420-1606-47c4-a393-91df6648d3da",
"payloadVersion": "1.0",
"processingDirective": {
"eventFilter": {
"eventFilterType": "ORDER_CHANGE"
}
}
}
Step 2. Receive notification messages
After the notification is correctly set up, you will receive messages in your Amazon Simple Queue Service (Amazon SQS) queue for all order status changes.
The following is an example of an ORDER_CHANGE
notification:
{
"NotificationVersion" : "1.0",
"NotificationType" : "ORDER_CHANGE",
"PayloadVersion" : "1.0",
"EventTime" : "2023-10-03T01:35:06.382Z",
"Payload" : {
"OrderChangeNotification" : {
"NotificationLevel" : "OrderLevel",
"SellerId" : "ABCDEFGFMDKELDW",
"AmazonOrderId" : "123-4567891-4567891",
"OrderChangeType" : "OrderStatusChange",
"OrderChangeTrigger" : {
"TimeOfOrderChange" : "2023-10-03T01:35:01.000Z",
"ChangeReason" : "Order Status Change"
},
"Summary" : {
"MarketplaceId" : "A2Q3Y263D00KWC",
"OrderStatus" : "Unshipped",
"PurchaseDate" : "2023-10-03T01:03:44.106Z",
"DestinationPostalCode" : null,
"FulfillmentType" : "MFN",
"OrderType" : "StandardOrder",
"OrderPrograms" : [ ],
"ShippingPrograms" : [ ],
"OrderItems" : [ {
"OrderItemId" : "12345207241",
"SellerSKU" : "SKU123",
"SupplySourceId" : null,
"Quantity" : 15
} ]
}
}
},
"NotificationMetadata" : {
"ApplicationId" : "amzn1.sp.solution.c4d.......",
"SubscriptionId" : "52ac10........",
"PublishTime" : "2023-10-03T01:35:07.931Z",
"NotificationId" : "e9b0f384........"
}
}
When you receive a notification, check the value of OrderChangeTypes
in the notification payload:
BuyerRequestedChange
: The buyer has initiated a cancellation. To cancel an MFN order, use thePOST_ORDER_ACKNOWLEDGEMENT_DATA
feed.OrderStatusChange
: The order status has changed. Check the changedOrderStatus
. If it isUnshipped
, you can now start preparing your order to fulfill the items purchased by buyers. This is a time sensitive task; being notified in real-time helps you fulfill orders in a timely manner. After shipping the product to the customer, you are also expected to confirm the shipment to Amazon, notifying the buyer that the product is out for delivery. Refer to How to confirm MFN Orders using SP-API for more information on confirming MFN orders using Selling Partner APIs.
The payload of the ORDER_CHANGE
notification now provides OrderItems
from the related order. When you use the OrderItems
information, you no longer need to call the getOrderItems
operation to know what items are in an order.
Conclusion
This tutorial covered how to subscribe to and use the ORDER_CHANGE
notification, which helps decrease your order processing workload and improve the performance of your integration with Amazon Selling Partner API.
Updated about 2 months ago