Notification — Amazon External FulFillment API Documentation

What is the Notifications API? ¶

The Selling Partner API for Notifications lets you 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 triggers a notification to which you are subscribed.

Amazon External Fulfillment API raises event notifications whenever order status changes for an order]. Examples include the creation of an order for a seller, or the marketplace cancellation of an order that a seller is currently fulfiling.

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 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?

Notification Workflows - Amazon Simple Queue Service Workflow ¶

Use this workflow to receive the following notification types:

EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_CHANGE: Sent whenever there is a change in the order status for Warehouse Integration order (Valid values for statuses are ACCEPTED, CONFIRMED, PACKAGE_CREATED, PICKUP_SLOT_RETRIEVED, INVOICE_GENERATED, SHIPLABEL_GENERATED, SHIPPED*, DELIVERED* and CANCELLED).

Tutorial: Set up notifications (Amazon Simple Queue Service workflow)

Prerequisites

To complete this tutorial, you will 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 Selling Partner API permission to write to your SQS queue

To receive notifications, you must grant Selling Partner API permission to write to your SQS queue.

Open the AWS Management Console and sign in with your AWS credentials.
From the console, open Amazon Simple Queue Service.
Select the Standard queue where you want to receive notifications.
Choose the Access Policy tab.
From the Access policy (Permissions) section, select Edit. The Edit Test Queue page opens.
Scroll down to Access policy, then select the Policy generator link. The AWS Policy Generator opens in a new tab.
In Step 1 of the policy generator, select SQS Queue Policy.
In Step 2 of the policy generator:
- Set Effect to Allow.
- Set Principal to 437568002678.
- Set Actions to SendMessage and GetQueueAttributes.
- Enter the SQS ARN value in Amazon Resource Name (ARN).
- Choose Add Statement and verify the details.
In Step 3 of the policy generator, select Generate Policy. A dialog box with the new policy opens.
Copy the policy.
Navigate back to the Amazon SQS queue, open the Access policy tab, then paste the policy into the Access Policy (Permissions) section.
Save the changes.
Reference the queue's Details section and note the ARN for this queue. You will pass this value using the arn parameter when you call the createDestination operation in Step 2. Create a destination.

Note: If you are using server-side encryption (SSE), then you must provide Selling Partner API access to your key 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": "*"
    }
  ]
}

Refer to Key Management for more information.

Step 2. 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-eu.amazon.com/notifications/v1/destinations

{
  "name": "YourDestinationName",
  "resourceSpecification": {
    "sqs": {
      "arn": "arn:aws:sqs:eu-west-1: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:eu-west-1:444455556666:queue1"
      }
    }
  }
}

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

Step 3. 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, please check 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: EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_CHANGE Type: string	Yes

Body parameters:

Parameter	Description	Required
payloadVersion	The version of the payload object to be used in the notification. Supported payloadVersion: "1.0" 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

Request example :

POST https://sellingpartnerapi-eu.amazon.com/notifications/v1/subscriptions/
EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_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. Supported payloadVersion: "1.0" 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 Example :

POST https://sellingpartnerapi-eu.amazon.com/notifications/v1/subscriptions/
EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_CHANGE
{
    "payloadVersion":"1.0",
    "destinationId":"3acafc7e-121b-1329-8ae8-1571be663aa2"
}

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. Supported payloadVersion: "1.0"	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, see Notification example below.
NotificationMetadata	The notification metadata. This includes the following objects: ApplicationId – The identifier for the application that uses the notifications. Type = string SubscriptionId - A unique identifier for the subscription which resulted in this notification. Type = string PublishTime - The date and time (in UTC) that the notification was sent. Type = string NotificationId - A unique identifier for this notification instance. Type = string	JSON object

Notification example:

{
  "notificationVersion": "1.0",
  "notificationType": "EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_CHANGE",
  "payloadVersion": "1.0",
  "eventTime": "2024-01-22T13:32:15.686Z",
  "payload": {
    "externalFulfillmentShipmentNotification": {
      "merchantId": "ABCDEFGHIJKL",
      "locationId": "ec4621aa-76a7-4e5f-b158-4c8b0ac87",
      "shipmentId": "U3CgWfn",
      "channelName": "FBA",
      "shipmentStatus": "CONFIRMED"
    }
  },
  "notificationMetadata": {
    "applicationId": "amzn1.sp.solution.9531e-5d47-45e5-aa9a-11dcd3b00cf",
    "subscriptionId": "d2d37640-e1f-46b-ad4-71a5e5520f",
    "publishTime": "2024-01-22T13:32:17.197Z",
    "notificationId": "b7f4884b-a046-43ca-8cb4-fb0f106321"
  }
}

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 at the AWS Documentation portal.

External FulFillment API Documentation

Event Notifications¶

What is the Notifications API? ¶

Terminology ¶

Notification Workflows - Amazon Simple Queue Service Workflow ¶