Tutorial: 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

The 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 relevant OrderChangeType 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 the ORDER_CHANGE notification and delete your subscription to ORDER_STATUS_CHANGE.

1. Call the getSubscription operation to fetch the subscriptionId of ORDER_STATUS_CHANGE.
2. With the subscriptionId, use the deleteSubscriptionById operation to delete the subscription to the ORDER_STATUS_CHANGE notification. Remember that the deleteSubscriptionById operation is a grantless operation.

Step 1. Subscribe to the ORDER_CHANGE notification

1. 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.

2. Call the createSubscription operation.

3. Add the parameter ORDER_CHANGE in the notificationType path variable.

The payload below shows how to set a filter to receive only notifications about order status changes. Make sure to include your destinatonId:

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:

1. BuyerRequestedChange: The buyer has initiated a cancellation. To cancel an MFN order, use the POST_ORDER_ACKNOWLEDGEMENT_DATA feed.
2. OrderStatusChange: The order status has changed. Check the changed OrderStatus. If it is Unshipped, 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.