Notifications API v1 Use Case Guide
Subscribe to notifications that are relevant to a selling partner's business.
API Version: v1
What is the Notifications API?
You can use the Selling Partner API for Notifications to subscribe to notifications that are relevant to a selling partner's business. Using this API, you can create a destination to receive notifications, subscribe to notifications, delete notification subscriptions, and more. Instead of polling for information, your application can receive information directly from Amazon when an event generates a notification to which you are subscribed.
You can subscribe to notifications on behalf of sellers or vendors. To determine whether you can subscribe to a notification type on behalf of sellers only, vendors only, or both, go to notificationType
. 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
.
Build a backup mechanism
As a best practice, we recommend that you have a means to retrieve needed information in the event of an unexpected outage or delay in notification delivery.
Terminology
-
Amazon EventBridge: A serverless event bus that connects application data from your own applications, integrated Software-as-a-Service (SaaS) applications, and AWS services. For more information, refer to Amazon EventBridge.
-
Amazon Simple Queue Service (Amazon SQS): A fully managed message queuing service for microservices, distributed systems, and serverless applications. For more information, refer to Amazon Simple Queue Service.
-
Partner event source: Used by an AWS partner to send events to an AWS customer account. To receive these events, the customer must associate an event bus with the partner event source. For more information, refer to What Is Amazon EventBridge?
-
Event bus: Receives events from a source and routes them to target resources according to rules associated with the event bus. For more information, refer to EventBus.
Notification workflows
There are two separate workflows for receiving notifications. The workflow you use depends on the notification type that you want to receive.
Amazon EventBridge workflow
The following diagram provides an overview of the Amazon EventBridge workflow steps to subscribe to listings notifications.
Use this workflow to receive the following notification types:
-
BRANDED_ITEM_CONTENT_CHANGE
: Sent when there is a change to the title, description, bullet points, or images, for any ASIN that the selling partner has a brand relationship with. -
ITEM_PRODUCT_TYPE_CHANGE
: Sent when there is a change to the product type name of any ASIN that the selling partner has a brand relationship with. -
LISTINGS_ITEM_STATUS_CHANGE
: Sent when there is a listing status change including buyable transition, listing create, or listing delete for any SKU that the selling partner has. -
LISTINGS_ITEM_ISSUES_CHANGE
: Sent when there is an issues change for any SKU that the selling partner has. -
LISTINGS_ITEM_MFN_QUANTITY_CHANGE
: Sent when there is change in the available quantity of a listings item. -
PRODUCT_TYPE_DEFINITIONS_CHANGE
: Sent when there is a new Product Type or Product Type Version.
Refer to Tutorial: Set up notifications (Amazon EventBridge workflow).
Amazon Simple Queue Service workflow
Use this workflow to receive the following notification types:
-
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 betweenNORMAL
,AT_RISK
, andDEACTIVATED
. -
ANY_OFFER_CHANGED
: Sent when there is a change to 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 ofDONE
,CANCELLED
, orFATAL
. -
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 thatmarketplaceIds
is not a supported filter forORDER_CHANGE
. If you want to includemarketplaceIds
, you must useANY_OFFER_CHANGED
. -
PRICING_HEALTH
: Sent when a seller offer is ineligible to be the Featured 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 ofDONE
,CANCELLED
, orFATAL
. -
TRANSACTION_UPDATE
: Sent whenever there is a new transaction posted to the seller's account.
Refer to Tutorial: Set up notifications (Amazon Simple Queue Service workflow).
Tutorial: Set up notifications (Amazon EventBridge workflow)
Use this tutorial to receive any of the following notifications types:
-
BRANDED_ITEM_CONTENT_CHANGE
: Sent when there is a change to the title, description, bullet points, or images for any ASIN that the selling partner has a brand relationship with. -
ITEM_PRODUCT_TYPE_CHANGE
: Sent when there is a change to the product type name of any ASIN that the selling partner has a brand relationship with. -
LISTINGS_ITEM_STATUS_CHANGE
: Sent when there is a listing status change including buyable transition, listing create, or listing delete for any SKU that the selling partner has. -
LISTINGS_ITEM_ISSUES_CHANGE
: Sent when there is an issues change for any SKU that the selling partner has. -
LISTINGS_ITEM_MFN_QUANTITY_CHANGE
: Sent when there is change in the available quantity of a listings item. -
PRODUCT_TYPE_DEFINITIONS_CHANGE
: Sent when there is a new Product Type or Product Type Version.
If you want to receive any other notification type, skip this tutorial and go to Tutorial: Set up notifications (Amazon Simple Queue Service workflow).
Prerequisites
To complete this tutorial you need:
-
Authorization from the selling partners (sellers or vendors) for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
An AWS account. This AWS account will be responsible for charges related to receiving notifications. If you are not already an AWS customer, you can create a free AWS account. For more information, refer to AWS Free Tier.
-
A target resource to receive notification events from your Amazon EventBridge bus. For more information, refer to What Is Amazon EventBridge?
-
A basic understanding of Amazon EventBridge. For more information, refer to Amazon EventBridge.
Step 1. Create a destination
Call the createDestination
operation to create an Amazon EventBridge destination.
Note
You can only create one EventBridge destination per AWS account.
- Call the
createDestination
operation, passing the following body parameters:
Parameter | Description | Required |
---|---|---|
resourceSpecification |
The information required to create a destination resource. In this workflow, include the eventBridge specification.
Type: |
Yes |
name |
A developer-defined name to help identify this destination.
Type: string |
Yes |
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.
Request example
POST https://sellingpartnerapi-na.amazon.com/notifications/v1/destinations
{
"resourceSpecification":
{
"eventBridge":
{
"accountId": "123456789",
"region": "us-east-1"
}
},
"name": "YourDestinationName"
}
Response
A successful response includes the following:
Name | Description |
---|---|
resource |
The resource that will receive notifications associated with this destination.
Type: |
destinationId |
The destination identifier generated when you created the destination.
Type: string |
name |
The name of this destination.
Type: string |
Response example
{
"payload": {
"resource": {
"sqs": null,
"eventBridge": {
"name": "sellingpartnerapi.amazon.com/amzn1.sellerapps.app.15a75829-cd4a-4efc-b947-0cc39d874577",
"accountId": "123456789",
"region": "us-east-1"
}
},
"destinationId": "64a4a891-60dd-303f-89f9-43caf25cb3ec",
"name": "YourDestinationName"
}
}
- Save the following values:
-
resource:eventBridge:name
: Use this value in Step 2. Configure Amazon EventBridge to handle notifications. -
destinationId
: Pass in this value in Step 4. Create a subscription.
Step 2. Configure Amazon EventBridge to handle notifications
Associate an event bus with your partner event source. For definitions, refer to Terminology.
-
Go to Amazon EventBridge and sign in to the AWS Console using the AWS Account ID that you specified when you called the
createDestination
operation in Step 1. Create a destination. -
In the console, ensure that the AWS Region that you specified when you called the
createDestination
operation is selected. -
In the navigation pane, choose Partner event sources.
-
In the Partner event sources area, under Name, select the partner event source that matches the
resource:eventBridge:name
value returned in Step 1. Create a destination. The partner event source is in this format:aws.partner/sellingpartnerapi.amazon.com/{AWS Account Id}/{Application Id}
. -
On the new page that appears, choose Associate with event bus.
-
On the Associate with event bus page, leave the checkboxes empty and choose Associate.
You have created a partner event bus and associated it with your partner event source. Go to Step 3. Create a rule that starts on a notification event.
Step 3. Create a rule that starts on a notification event
Create a rule that watches for specific notification events and routes them to the target resource of your choice.
-
Go to Amazon EventBridge. If you are not already signed in to the AWS Console, sign in using the AWS Account ID that you specified when you called the
createDestination
operation in Step 1. Create a destination. -
In the Console, ensure that the AWS Region that you specified when you called the
createDestination
operation is selected. -
In the navigation pane, choose Rules.
-
Choose Create rule.
-
Enter a name and optional description for the rule.
-
For Event bus, select the bus that you associated with the partner event source.
-
Choose Next.
-
For Event source, select AWS events or EventBridge partner events.
-
For Creation method, select Use pattern form.
-
In Event pattern:
- Choose Event source, select EventBridge partners.
- For the Partner dropdown, select Amazon Selling Partner APIs.
- For the Event type dropdown, select All Events.
The event pattern that displays should be similar to the following, which indicates that you will receive all events emitted by
sellingpartnerapi.amazon.com
:{ "source": [ { "prefix": "aws.partner/sellingpartnerapi.amazon.com" } ] }
-
(Optional) Edit the event pattern to include rules that match only the notification events that you want. The following event pattern contains a rule that matches only
BRANDED_ITEM_CONTENT_CHANGE
events fromsellingpartnerapi.amazon.com
:{ "source": [ { "prefix": "aws.partner/sellingpartnerapi.amazon.com" } ], "detail-type": ["BRANDED_ITEM_CONTENT_CHANGE"] }
For information about creating more complex rules, refer to Event Patterns in the Amazon EventBridge Developer Guide.
-
Choose Next.
-
Now select the AWS service that is to act when an event of the selected type is detected. Enter other information specific to this target type, if required.
Note
For many target types, EventBridge needs permissions to send events to the target. In these cases, you can create a new IAM role or you can use an existing IAM role. Do one of the following:
- To create an IAM role, select Create a new role for this specific resource.
- To use an IAM role that you have already created, select Use existing role.
Note
To verify that events are coming through your EventBridge, you can use an SQS queue as a target for the rule you created, and then poll that SQS queue as notifications arrive.
-
(Optional) Choose Add another target to add another target for this rule if you need more than one.
-
Choose Next.
-
(Optional) Enter one or more tags for the rule. For more information, refer to Tagging Your Amazon EventBridge Resources in the AWS documentation.
-
Choose Next.
-
Choose Create rule.
Troubleshooting:
-
If you create a rule with an encrypted Amazon SQS queue as a target, you must include a decrypt action in your AWS Key Management Service key policy for the event to be successfully delivered to the encrypted queue. For more information, refer to My events are not delivered to the target Amazon SQS queue in the AWS documentation.
-
For more troubleshooting information, refer to Troubleshooting Amazon EventBridge in the Amazon EventBridge Developer Guide.
Step 4. Create a subscription
Subscribe to a notification type, to be delivered to the destination that you created in Step 1. Create a destination.
Note: We allow multiple subscriptions with different payload versions per application, notification type, and party (seller/vendor). For supported payload versions of different notification type, refer to notificationType
.
- Call the
createSubscription
operation, passing the following parameters:
Path parameters:
Parameter | Description | Required |
---|---|---|
notificationType |
Information about the notification type and payload version to which you want to subscribe.
Possible values: Type: string |
Yes |
Body parameters:
Parameter | Description | Required |
---|---|---|
payloadVersion |
The version of the payload object to be used in the notification. For supported payloadVersion for different notification types, refer to notificationType .
Type: string |
Yes |
destinationId |
The identifier for the destination where notifications will be delivered. Use the destinationId value that you saved in Step 1. Create a destination.
Type: string |
Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/ notifications/v1/subscriptions/BRANDED_ITEM_CONTENT_CHANGE
{
"payloadVersion":"1.0",
"destinationId":"3acafc7e-121b-1329-8ae8-1571be663aa2"
}
Response
Name | Description |
---|---|
subscriptionId |
The subscription identifier generated when the subscription is created.
Type: string |
payloadVersion |
The version of the payload object to be used in the notification. For supported payloadVersion for different notification types, refer to notificationType .
Type: string |
destinationId |
The identifier for the destination where notifications will be delivered.
Type: string |
Response example
{
"payload":{
"subscriptionId":" 7fcacc7e-727b-11e9-8848-1681be663d3e",
"payloadVersion":" 1.0",
"destinationId":"3acafc7e-121b-1329-8ae8-1571be663aa2"
}
}
You are now subscribed to receive BRANDED_ITEM_CONTENT_CHANGE
notifications.
Tutorial: Set up notifications (Amazon Simple Queue Service workflow)
Use this tutorial to set up your system to receive any of the following notifications types:
-
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 betweenNORMAL
,AT_RISK
, andDEACTIVATED
. -
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 ofDONE
,CANCELLED
, orFATAL
. -
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 thatmarketplaceIds
is not a supported filter forORDER_CHANGE
. If you want to includemarketplaceIds
, you must useANY_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 ofDONE
,CANCELLED
, orFATAL
. -
TRANSACTION_UPDATE
: Sent whenever there is a new transaction posted to the seller's account.
Warning
To receive any other notification type, refer to Tutorial: 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.
- Call the
createDestination
operation, passing the following body parameters:
Parameter | Description | Required |
---|---|---|
resourceSpecification |
The information required to create an SQS destination. This includes the sqs:arn value that you got from Step 1. Grant Selling Partner API permission to write to your SQS queue.
Type: object |
Yes. |
name |
A name that you specify to help you identify this destination.
Type: string |
Yes |
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.
Request example
POST https://sellingpartnerapi-na.amazon.com/ notifications/v1/destinations
{
"name": "YourDestinationName",
"resourceSpecification":
{
"sqs":
{
"arn": "arn:aws:sqs:us-east-2:444455556666:queue1"
}
}
}
Response
Name | Description |
---|---|
name |
The developer-defined name for this destination.
Type: string |
destinationId |
The destination identifier generated when you created the destination.
Type: string |
resource |
The resource that will receive notifications associated with this destination.
Type: object |
Response example
{
"payload": {
"name": "YourDestinationName",
"destinationId": "ExampleDestinationId",
"resource": {
"sqs": {
"arn": "arn:aws:sqs:us-east-2:444455556666:queue1"
}
}
}
}
- 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:
Parameter | Description | Required |
---|---|---|
notificationType |
Information about the notification type and payload version to which you want to subscribe.
Possible values: Type: string |
Yes |
Body parameters:
Parameter | Description | Required |
---|---|---|
payloadVersion |
The version of the payload object to be used in the notification. For supported payloadVersion for different notification types, refer to notificationType .
Type: string |
Yes |
destinationId |
The identifier for the destination where notifications will be delivered. Use the value you saved in Step 2. Create a destination.
Type: string |
Yes |
processingDirective |
Additional information passed to the subscription to control how notifications are processed. For example, you can use an eventFilter to customize your subscription to send notifications for only the specified marketplaceId , or select the aggregation time period at which to send notifications (for example, limit to one notification every five minutes for high frequency notifications). The specific features available vary depending on the notificationType .Note: This feature is currently only supported by the Type: |
No |
Request example (without a processing directive):
POST https://sellingpartnerapi-na.amazon.com/ notifications/v1/subscriptions/ANY_OFFER_CHANGED
{
"payloadVersion":"1.0",
"destinationId":"3acafc7e-121b-1329-8ae8-1571be663aa2"
}
Response
Name | Description |
---|---|
subscriptionId |
The subscription identifier generated when the subscription is created.
Type: string |
payloadVersion |
The version of the payload object to be used in the notification. For supported payloadVersion for different notification types, refer to notificationType .
Type: string |
destinationId |
The identifier for the destination where notifications will be delivered. Use the destinationId value that you saved in the previous step.
Type: string |
Response
{
"payload": {
"subscriptionId": "7fcacc7e-727b-11e9-8848-1681be663d3e",
"payloadVersion": "1.0",
"destinationId": "3acafc7e-121b-1329-8ae8-1571be663aa2",
}
}
Response
Name | Description |
---|---|
subscriptionId |
The subscription identifier generated when the subscription is created.
Type: string |
payloadVersion |
The version of the payload object to be used in the notification. For supported payloadVersion for different notification types, refer to notificationType .
Type: string |
destinationId |
The identifier for the destination where notifications will be delivered. Use the destinationId value that you saved in the previous step.
Type: string |
Examples that use a processingDirective
(Only supported by the ANY_OFFER_CHANGED
and ORDER_CHANGE
notificationTypes
)
Request example to create a subscription that sends notifications for only the specified marketplaceId
:
marketplaceId
:POST https://sellingpartnerapi-na.amazon.com/ notifications/v1/subscriptions/ANY_OFFER_CHANGED
{
"destinationId": "12d803a2-7e70-4bb2-a797-2b4b43e10051",
"payloadVersion": "1.0",
"processingDirective": {
"eventFilter": {
"eventFilterType": "ANY_OFFER_CHANGED",
"marketplaceIds": ["ATVPDKIKX0DER"]
}
}
}
Response example
{
"payload": {
"subscriptionId": "7318ddfb-18e4-4fe0-89f5-a437321d2e79",
"destinationId": "12d803a2-7e70-4bb2-a797-2b4b43e10051",
"payloadVersion": "1.0",
"processingDirective": {
"eventFilter": {
"marketplaceIds": [
"ATVPDKIKX0DER"
],
"eventFilterType": "ANY_OFFER_CHANGED"
}
}
}
}
Request example to create a subscription that limits the frequency of notifications to one every five minutes:
POST https://sellingpartnerapi-na.amazon.com/ notifications/v1/subscriptions/ANY_OFFER_CHANGED
{
"destinationId": "12d803a2-7e70-4bb2-a797-2b4b43e10051",
"payloadVersion": "1.0",
"processingDirective": {
"eventFilter": {
"eventFilterType": "ANY_OFFER_CHANGED",
"aggregationSettings": {
"aggregationTimePeriod": "FiveMinutes"
}
}
}
}
Response example
{
"payload": {
"subscriptionId": "b8877fdf-17a6-4d59-bb1d-9650d9d823e0",
"destinationId": "12d803a2-7e70-4bb2-a797-2b4b43e10051",
"payloadVersion": "1.0",
"processingDirective": {
"eventFilter": {
"aggregationSettings": {
"aggregationTimePeriod": "FiveMinutes"
},
"eventFilterType": "ANY_OFFER_CHANGED"
}
}
}
}
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 thenotificationId
property in theNotificationMetaData
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:
Name | Description |
---|---|
eventFilterType |
An eventFilterType value that is supported by the specific notificationType . This is used by the subscription service to determine the type of event filter.
Example: |
aggregationSettings |
A container to support aggregated filtering of notifications. Supports using an aggregationTimePeriod to limit (filter) the sending of notifications to a five or ten minute frequency.
Example: |
marketplaceIds |
A list of marketplace identifiers to subscribe to. To receive notifications for every marketplace, do not provide this list. marketplaceIds is not a supported filter for the ORDER_CHANGE notification. If you want to include marketplaceIds , you must use ANY_OFFER_CHANGED .
Example: |
orderChangeTypes |
A list of order change types to subscribe to. To receive notifications for every order change type, do not provide this list.
Possible values are BuyerRequestedChange and OrderStatusChange .
Example: |
For more information, refer to ProcessingDirective
in the API reference.
Request example that implements a processingDirective
with eventFilter
values for the ANY_OFFER_CHANGED
notification:
processingDirective
with eventFilter
values for the ANY_OFFER_CHANGED
notification:POST https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/ANY_OFFER_CHANGED
{
"payloadVersion": "1.0",
"destinationId": "3acafc7e-121b-1329-8ae8-1571be663aa2",
"processingDirective": {
"eventFilter": {
"marketplaceIds": [
"ATVPDKIKX0DER",
"A2EUQ1WTGCTBG2"
],
"aggregationSettings": {
"aggregationTimePeriod": "FiveMinutes"
},
"eventFilterType": "ANY_OFFER_CHANGED"
}
}
}
Response
{
"payload": {
"subscriptionId": "7fcacc7e-727b-11e9-8848-1681be663d3e",
"payloadVersion": "1.0",
"destinationId": "3acafc7e-121b-1329-8ae8-1571be663aa2",
"processingDirective": {
"eventFilter": {
"marketplaceIds": [
"ATVPDKIKX0DER",
"A2EUQ1WTGCTBG2"
],
"aggregationSettings": {
"aggregationTimePeriod": "FiveMinutes"
},
"eventFilterType": "ANY_OFFER_CHANGED"
}
}
}
}
Request example that implements a processingDirective
with eventFilter
values for the ORDER_CHANGE
notification:
processingDirective
with eventFilter
values for the ORDER_CHANGE
notification:POST https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/ORDER_CHANGE
{
"payloadVersion": "1.0",
"destinationId": "3acafc7e-121b-1329-8ae8-1571be663aa2",
"processingDirective": {
"eventFilter": {
"orderChangeTypes": ["BuyerRequestedChange"],
"eventFilterType": "ORDER_CHANGE"
}
}
}
Response
{
"payload": {
"subscriptionId": "7fcacc7e-727b-11e9-8848-1681be663d3e",
"payloadVersion": "1.0",
"destinationId": "3acafc7e-121b-1329-8ae8-1571be663aa2",
"processingDirective": {
"eventFilter": {
"orderChangeTypes": ["BuyerRequestedChange"],
"eventFilterType": "ORDER_CHANGE"
}
}
}
}
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:
Object | Description | Type |
---|---|---|
NotificationVersion |
The notification version. This controls the structure of the notification. | string |
NotificationType |
The notification type. NotificationType , combined with PayloadVersion, controls the structure of the Payload object . |
string |
PayloadVersion |
The payload version. PayloadVersion , combined with NotificationType , controls the structure of the Payload object . For supported payloadVersion for different notification types, refer to notificationType . |
string |
EventTime |
The date and time (in UTC) that the event which triggered the notification occurred. | string |
Payload |
The actionable data of the notification. The structure of the Payload is determined by NotificationType , in combination with PayloadVersion . |
JSON object For more information, refer to Notifications. |
NotificationMetadata
|
The notification metadata. This includes the following objects:
|
JSON object |
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
FulfillmentChannelType
Indicates whether the item is fulfilled by Amazon or by the seller.
Type: string
FulfillmentChannelType
values:
-
Amazon
-
Merchant
moneyType
moneyType
Currency type and amount.
The following table shows the properties of the MoneyType
object:
Name | Description |
---|---|
amount |
The currency amount. Type: number |
currencyCode |
Three-digit currency code. In ISO 4217 format. Type: string |
MoneyType
MoneyType
Currency type and amount.
The following table shows the properties of the MoneyType
object:
Name | Description |
---|---|
Amount |
The currency amount. Type: number |
CurrencyCode |
Three-digit currency code. In ISO 4217 format. Type: string |
Updated about 1 month ago