Set up notifications (Amazon Simple Queue Service workflow)

Learn how to set up your system to receive the following notifications using the Amazon Simple Queue Service workflow:

• ACCOUNT_STATUS_CHANGED. Sent when the Account Status changes for the developers subscribed selling partner/marketplace pairs. A notification is published when the selling partner's account status changes between NORMAL, AT_RISK, and DEACTIVATED.

• ANY_OFFER_CHANGED. Sent when there is a listing change for any of the top 20 offers, by condition (new or used), or if the external price (the price from other retailers) changes for an item listed by the seller.

• B2B_ANY_OFFER_CHANGED. Sent when there is a change in any of the top 20 B2B offers, in the form of any price change (either single unit or quantity discount tier prices) for an item listed by the seller.

• DETAIL_PAGE_TRAFFIC_EVENT: Sent at the beginning of every hour. This notification shares traffic data at an ASIN level and includes data for the previous hour, as well as any delayed data from up to 24 hours earlier. Each notification can include multiple ASINs, and a selling partner can expect to receive multiple notifications every hour.

• FBA_INVENTORY_AVAILABILITY_CHANGES. Sent when there is a change in the Fulfillment By Amazon (FBA) inventory quantities. This notification includes a snapshot of the FBA inventory in all eligible marketplaces in a particular region.

• FBA_OUTBOUND_SHIPMENT_STATUS. Sent when we create or cancel a Fulfillment by Amazon shipment for a seller.

• FEE_PROMOTION. Sent when a promotion becomes active.

• FEED_PROCESSING_FINISHED. Sent when any feed submitted using the Selling Partner API for Feeds reaches a feed processing status of DONE, CANCELLED, or FATAL.

• FULFILLMENT_ORDER_STATUS. Sent when there is a change in the status of a Multi-Channel Fulfillment order.

• ITEM_INVENTORY_EVENT_CHANGE: Sent at the beginning of every hour. This notification shares inventory data at an ASIN level, and includes data for the previous hour, as well as any delayed data from up to 24 hours earlier. Each notification can include multiple ASINs, and a selling partner can expect to receive multiple notifications every hour.

• ITEM_SALES_EVENT_CHANGE: Sent at the beginning of every hour. This notification shares sales data at an ASIN level and includes data for the previous hour, as well as any delayed data from up to 24 hours earlier. Each notification can include multiple ASINs, and a selling partner can expect to receive multiple notifications every hour.

• ORDER_CHANGE: Sent when there is an important change in the order. Important changes include order status changes and buyer requested cancelations. Note that marketplaceIds is not a supported filter for ORDER_CHANGE. If you want to include marketplaceIds, you must use ANY_OFFER_CHANGED.

• PRICING_HEALTH. Sent when a seller offer is ineligible to be the Featured Offer (Buy Box offer) because of an uncompetitive price.

• REPORT_PROCESSING_FINISHED. Sent when any report that you have requested using the Selling Partner API for Reports reaches a report processing status of DONE, CANCELLED, or FATAL.

• TRANSACTION_UPDATE: Sent whenever there is a new transaction posted to the seller's account.

🚧

Warning

To receive any other notification type, refer to Set up notifications (Amazon EventBridge workflow).

Prerequisites

To complete this tutorial you need:

• Authorization from the selling partners for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

• An AWS Account. If you are not already an AWS customer, you can create a free AWS account. For more information, refer to AWS Free Tier.

• An Amazon Simple Queue Service (SQS) queue. For information about setting up an SQS queue, refer to Amazon Simple Queue Service.

Step 1. Grant the Selling Partner API permission to write to your SQS queue

To receive notifications to your SQS queue, you must grant the Selling Partner API permission to write to the queue. To grant permissions to your SQS queue, you can upload an AWS CloudFormation template or you can configure permissions manually by using the Amazon SQS console. For instructions, refer to Tutorial: Grant the SP-API Permission to an Amazon SQS Queue.

Step 2. Grant the Selling Partner API permission to access your server-side encryption key

If you're using server-side encryption (SSE), you must give the Selling Partner API access to your key by using the AWS Key Management Service (KMS). Consider using the following policy.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::437568002678:root"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*"
    }
  ]
}

For more information, refer to Key management.

Step 3. Create a destination

Call the createDestination operation to create an Amazon Simple Queue Service (SQS) destination.

📘

Note

Calling the createDestination operation does not require authorization from any selling partner. In this respect, this operation is a "grantless" operation and has a different authorization model from most other Selling Partner API operations. For more information, refer to Grantless operations.

Save the destinationId value as input for Step 3. Create a subscription.

Step 4. Create a subscription

Create a subscription to a notification type, to be delivered to the destination that you created in the previous step.

📘

Note

We allow multiple subscriptions with different payload versions per application, notification type, and party (seller/vendor). For supported payload versions of different notification types, refer to notificationType.

Call the createSubscription operation, passing the following parameters:

Path parameters:

Body parameters:

Processing notifications from your queue

There are several important properties of Amazon SQS queues that you must understand in order to process notifications properly:

• Selling Partner API does not support delivery to FIFO queues. You must use Amazon SQS standard queues to receive notifications.

• Selling Partner API standard queues do not guarantee that notifications will be received in the order they were sent. Standard queues provide best-effort ordering, which means that notifications are generally delivered in the same order as they're sent. However, occasionally, more than one copy of a notification might be delivered out of order. Therefore, you must design your application to accept notifications in any order.

• Amazon SQS standard queue notifications might be delivered more than once. Amazon SQS stores copies of your notifications on multiple servers for redundancy and high availability. On rare occasions, one of the servers that stores a copy of a notification might be unavailable when you receive or delete a notification. If this scenario occurs, the copy of the notification isn't deleted on that unavailable server, and you might get that notification copy again when you receive notifications. Therefore, you must design your application to accept multiple copies of any given notification.

• You can determine if a notification is a duplicate of a notification you have already received by looking at the notificationId property of the notification. You can find the notificationId property in the NotificationMetaData object of the notification.

For more information about processing notifications from Amazon SQS queues, refer to the Amazon Simple Queue Service Developer Guide and the Amazon Simple Queue Service API Reference in the AWS Documentation portal.

Processing Directives

A processing directive is an optional parameter that you can provide when you call the createSubscription operation. It can be used to change the behavior of a subscription for certain notificationTypes. It is currently only supported for use with the ANY_OFFER_CHANGED and ORDER_CHANGE notification types. Usage with an unsupported notification type results in a request failure with an HTTP 400 response.

Use a processingDirective to pass additional information to the subscription to control the processing of notifications. For example, you can use an eventFilter to customize your subscription to send notifications for only the specified marketplaceId, or to select the aggregation time period at which to send notifications (for example, limit to one notification every five minutes for high frequency notifications).

The following eventFilter values are supported:

For more information, refer to ProcessingDirective in the API reference.

Notification structure

Selling Partner notifications are in JSON format. Each notification contains a Payload object, which contains the actionable data of the notification. Notification Type, in combination with PayloadVersion, determines the structure of the Payload object.

A Selling Partner notification with NotificationVersion=1.0 contain the following properties:

Notification example:

{
  "NotificationVersion": "1.0",
  "NotificationType": "BRANDED_ITEM_CONTENT_CHANGE",
  "PayloadVersion": "1.0",
  "EventTime": "2019-03-20T18:59:30.194Z",
  "Payload":
  {
    "MarketplaceId": "ATVPDKIKX0DER",
    "BrandName": "Great Brand",
    "Asin": "B1234567",
    "AttributesChanged": [
      "bullet_point",
      "item_name",
      "product_description",
      "main_product_image_locator",
      "other_product_image_locator_1",
      "other_product_image_locator_2",
      "other_product_image_locator_3",
      "other_product_image_locator_4",
      "other_product_image_locator_5",
      "other_product_image_locator_6",
      "other_product_image_locator_7",
      "other_product_image_locator_8",
      "swatch_product_image_locator"
    ]
  },
  "NotificationMetadata":
  {
    "ApplicationId": "amzn1.sellerapps.app.f1234566-aaec-55a6-b123-bcb752069ec5",
    "SubscriptionId": "93b098e1-c42-2f45-93a1-78910a6a8369",
    "PublishTime": "2019-03-20T18:59:48.768Z",
    "NotificationId": "8e009934-da2c-4f9c-9bc7-93f23b7e1f60"
  }
}

Common types

Contains common types that are used by all notifications that are contained in the Notification payload objects.

FulfillmentChannelType

Indicates whether the item is fulfilled by Amazon or by the seller.

Type: string

FulfillmentChannelType values:

• Amazon

• Merchant

moneyType

Currency type and amount.

The following table shows the properties of the MoneyType object:

MoneyType

Currency type and amount.

The following table shows the properties of the MoneyType object: