Notifications API

The Notifications API enables WMS systems to subscribe to Amazon SP-API order change notifications, allowing real-time order updates via Amazon SQS.

Overview

Amazon SP-API provides a notifications system that pushes order updates to an SQS queue instead of requiring polling. Data Border handles the complex setup of:

Creating an SQS destination in Amazon
Creating a subscription for ORDER_CHANGE notifications
Managing subscription lifecycle

SQS Setup Required: Before using this API, you must create an SQS queue in AWS and configure the appropriate IAM permissions for Amazon to publish messages.

Authentication

All notification endpoints require seller-level authentication:

Header	Required	Description
`x-seller-access-token`	Yes	Valid seller access token (JWT)

Endpoints

Register Notification

Registers or updates an Amazon SP-API notification subscription for order change events.

POST /api/notification/registerNotification

Request Body

{
  "sqsArn": "arn:aws:sqs:us-east-1:123456789012:my-order-notifications",
  "recreateSubscription": false
}

Field	Type	Required	Description
`sqsArn`	string	Yes	Full ARN of your AWS SQS queue
`recreateSubscription`	boolean	No	If `true`, deletes existing subscription and creates new one (default: `false`)

Response

New subscription created:

{
  "message": "Notifications registed."
}

Subscription already exists:

{
  "message": "Notifications already registed."
}

Example Request

curl -X POST https://adb.example.com/api/notification/registerNotification \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "sqsArn": "arn:aws:sqs:us-east-1:123456789012:amazon-order-updates",
    "recreateSubscription": false
  }'

How It Works

Registration Flow

sequenceDiagram
    participant WMS
    participant ADB
    participant Amazon as Amazon SP-API

    WMS->>ADB: POST /api/notification/registerNotification
    ADB->>ADB: Validate seller access token
    ADB->>Amazon: Get grantless token (client_credentials)
    Amazon->>ADB: Return grantless access token
    ADB->>Amazon: GET /notifications/v1/destinations
    Amazon->>ADB: Return existing destinations
    alt Destination doesn't exist
        ADB->>Amazon: POST /notifications/v1/destinations
        Amazon->>ADB: Return new destination ID
    end
    ADB->>Amazon: GET /notifications/v1/subscriptions/ORDER_CHANGE
    Amazon->>ADB: Return existing subscription (or 404)
    alt recreateSubscription = true AND subscription exists
        ADB->>Amazon: DELETE subscription
    end
    alt No subscription exists
        ADB->>Amazon: POST /notifications/v1/subscriptions/ORDER_CHANGE
        Amazon->>ADB: Return new subscription
    end
    ADB->>WMS: Return success message

Loading diagram...

Notification Type

Data Border currently supports only the ORDER_CHANGE notification type, which sends updates when:

New orders are placed
Order status changes (e.g., shipped, cancelled)
Order items are updated
Shipping information changes

AWS SQS Setup

1. Create SQS Queue

Create a standard SQS queue in your AWS account:

aws sqs create-queue \
  --queue-name amazon-order-notifications \
  --region us-east-1

2. Configure Queue Policy

The queue must allow Amazon SP-API to publish messages. Apply this policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sellingpartnerapi.amazon.com"
      },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:YOUR_ACCOUNT_ID:amazon-order-notifications",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "YOUR_ACCOUNT_ID"
        }
      }
    }
  ]
}

3. Register with Data Border

Once the queue is created and configured, register it with Data Border using the endpoint above.

Message Format

ORDER_CHANGE notifications arrive in your SQS queue with this structure:

{
  "notificationType": "ORDER_CHANGE",
  "payloadVersion": "1.0",
  "eventTime": "2024-01-15T10:30:00.000Z",
  "payload": {
    "OrderChangeNotification": {
      "SellerId": "A1EXAMPLE",
      "AmazonOrderId": "123-4567890-1234567",
      "OrderChangeType": "OrderStatusChange",
      "OrderChangeTrigger": {
        "TimeOfOrderChange": "2024-01-15T10:30:00.000Z",
        "ChangeReason": "Shipped"
      },
      "Summary": {
        "MarketplaceId": "ATVPDKIKX0DER",
        "OrderStatus": "Shipped",
        "FulfillmentType": "MFN"
      }
    }
  },
  "notificationMetadata": {
    "applicationId": "amzn1.sp.solution.abc123",
    "subscriptionId": "sub-123456",
    "publishTime": "2024-01-15T10:30:01.000Z",
    "notificationId": "notif-789012"
  }
}

Error Handling

Common Errors

Invalid SQS ARN:

{
  "is_adb_error": true,
  "success": false,
  "error": {
    "message": "Error creating destination",
    "amazon_response": {
      "errors": [{
        "code": "InvalidInput",
        "message": "Invalid SQS ARN format"
      }]
    }
  }
}

Permission Denied:

{
  "is_adb_error": true,
  "success": false,
  "error": {
    "message": "Error creating destination",
    "amazon_response": {
      "errors": [{
        "code": "AccessDenied",
        "message": "SP-API does not have permission to send messages to this SQS queue"
      }]
    }
  }
}

Best Practices

Use Dead Letter Queues: Configure a DLQ for your SQS queue to capture failed message processing
Enable Long Polling: Set ReceiveMessageWaitTimeSeconds to 20 for efficient message retrieval
Idempotent Processing: Notifications may be delivered more than once; design your handler to be idempotent
Monitor Queue Depth: Set up CloudWatch alarms for queue depth to detect processing issues
Recreate Sparingly: Only use recreateSubscription: true when troubleshooting; it disrupts the notification flow temporarily

Seller Management - Get seller access tokens
Authentication - Token lifecycle
Amazon SP-API Notifications - Official Amazon documentation