Subscribe to shipment tracking notifications

The SHIPMENT_TRACKING_MILESTONE_CHANGED notification type sends real-time tracking milestone updates for a shipment as it moves through Amazon's supply chain. Each subscription tracks a single shipment tracking identifier. After the subscription is active, the subscription delivers notifications to your configured destination whenever a milestone update occurs for the subscribed shipment.

Prerequisites

To complete this tutorial, you need:

• A configured destination (SQS or EventBridge) where notifications will be delivered.

Step 1: Create a subscription

1. Request an LWA access token with scope sellingpartnerapi::shipments:track.

2. Call the createSubscription operation with the following endpoint:

   HTTP

   POST https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/SHIPMENT_TRACKING_MILESTONE_CHANGED
   

3. Set payloadVersion to 2026-01-30.

4. Set destinationId to the ID of your configured destination.

5. Set processingDirective.eventFilter.eventFilterType to SHIPMENT_TRACKING_MILESTONE_CHANGED.

6. Set processingDirective.eventFilter.trackingIdentifier to exactly one shipment tracking identifier that scopes the subscription to a specific shipment. For supported identifier types, refer to TrackingIdentifier.

7. Submit the request and save the subscriptionId from the response. You will need it in Step 2.

The following examples show a complete request body for different supported identifier types.

By AFTN

{
  "payloadVersion": "2026-01-30",
  "destinationId": "e761781b-a01b-4b73-8000-92add5944d23",
  "processingDirective": {
    "eventFilter": {
      "trackingIdentifier": { "aftn": "AFTN987654321" },
      "eventFilterType": "SHIPMENT_TRACKING_MILESTONE_CHANGED"
    }
  }
}

By carrier tracking number

{
  "payloadVersion": "2026-01-30",
  "destinationId": "e761781b-a01b-4b73-8000-92add5944d23",
  "processingDirective": {
    "eventFilter": {
      "trackingIdentifier": {
        "carrierTracking": {
          "trackingNumber": "1Z999AA1234567890"
        }
      },
      "eventFilterType": "SHIPMENT_TRACKING_MILESTONE_CHANGED"
    }
  }
}

Step 2: Fetch information for a subscription

To retrieve details about the subscription you created in Step 1, use an LWA access token with scope sellingpartnerapi::notifications to call the getSubscriptionById operation.

📘

Note

The getSubscription operation is not supported for the SHIPMENT_TRACKING_MILESTONE_CHANGED notification type.

1. Use the subscriptionId from the createSubscription response and the notification type SHIPMENT_TRACKING_MILESTONE_CHANGED to construct your request.

2. Submit the request.

The following example shows a request to retrieve subscription details.

GET https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/SHIPMENT_TRACKING_MILESTONE_CHANGED/4520f632-166c-4cfe-a649-e3f9e4a13255