Documentation
Developer HubAPI StatusSupport

View order notifications with the Notifications API

Learn how to subscribe to FULFILLMENT_ORDER_STATUS notifications to be aware of all the changes happening on the order.

A seller can subscribe to FULFILLMENT_ORDER_STATUS notifications to be aware of all the changes happening on the order.

To complete this tutorial, you need:

Prerequisites

📘

Note

Notifications are not sent for sandbox orders. When testing in the sandbox, use the updateOrderStatus and updatePackage sandbox-only operations to simulate status transitions. Refer to the Fulfillment Outbound Dynamic Sandbox Guide.

Step 1. Subscribe to FULFILLMENT_ORDER_STATUS notifications

Using the destinationId from your SQS destination setup, call createSubscription to subscribe to the FULFILLMENT_ORDER_STATUS notification type. Set payloadVersion to "2026-07-04".

POST https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/FULFILLMENT_ORDER_STATUS
{
  "payloadVersion": "2026-07-04",
  "destinationId": "your-sqs-destination-id"
}

Amazon delivers a notification to your SQS queue whenever an order, shipment, or package changes status.

Step 2. Understand the event types

Each notification includes an eventType field that indicates what changed. The FULFILLMENT_ORDER_STATUS notification supports three event types.

Order status updates (ORDER_STATUS_CHANGED)

Tracks changes to the overall fulfillment order state. ORDER_STATUS_CHANGED events contain the order object with lineItems[]; they do not include shipments or packages.

StatusDescription
PROCESSINGOrder received and being prepared for fulfillment.
COMPLETEThe order is closed. Every quantity was either fulfilled and shipped, or cancelled.
COMPLETE_PARTIALThe order is closed. Some items were fulfilled; others were cancelled or unfulfillable.
CANCELLEDThe order was cancelled.
UNFULFILLABLENo items could be fulfilled due to inventory issues.
INVALIDThe order could not be validated (for example, an invalid destination address).

Shipment status updates (SHIPMENT_STATUS_CHANGED)

Tracks changes at the shipment level.

StatusDescription
PROCESSINGShipment is being prepared at the fulfillment center.
SHIPPEDAll packages in the shipment have left the fulfillment center.
CANCELLEDThe shipment was cancelled.

Package status updates (SHIPMENT_PACKAGE_STATUS_CHANGED)

Tracks the delivery progress of individual packages. This is the most granular event type.

StatusDescription
PROCESSINGPackage is being prepared.
IN_TRANSITPackage is in transit to the destination.
DELAYEDDelivery has been delayed.
OUT_FOR_DELIVERYPackage is out for delivery.
DELIVEREDPackage was successfully delivered.
UNDELIVERABLEPackage could not be delivered.
EXPIREDThe package delivery attempt window has expired.

Step 3. Handle incoming notifications

The following examples show the Payload object for each key milestone in the order lifecycle. All examples use PayloadVersion: "2026-07-04".

Order placed

Amazon receives and validates the order.

{
  "merchantId": "merchantId",
  "eventType": "ORDER_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "PROCESSING",
    "lineItems": [{
      "lineItemId": "LI789012",
      "product": {
        "productIdentifier": { "amazonSku": "SKU123" },
        "perUnitDeclaredValue": { "currencyCode": "USD", "amount": "14.99" }
      },
      "amount": { "unit": "EACHES", "value": "2.0" },
      "cancelledAmount": { "unit": "EACHES", "value": "0" },
      "unfulfillableAmount": { "unit": "EACHES", "value": "0" }
    }]
  }
}

Unfulfillable

Amazon could not fulfill any items due to inventory issues. unfulfillableAmount equals the full ordered quantity.

{
  "merchantId": "merchantId",
  "eventType": "ORDER_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "UNFULFILLABLE",
    "lineItems": [{
      "lineItemId": "LI789012",
      "product": {
        "productIdentifier": { "amazonSku": "SKU123" },
        "perUnitDeclaredValue": { "currencyCode": "USD", "amount": "14.99" }
      },
      "amount": { "unit": "EACHES", "value": "2.0" },
      "cancelledAmount": { "unit": "EACHES", "value": "0" },
      "unfulfillableAmount": { "unit": "EACHES", "value": "2.0" }
    }]
  }
}

Partially fulfilled

Some items were fulfilled; others could not be. Check unfulfillableAmount per line item to determine which quantities were affected.

{
  "merchantId": "merchantId",
  "eventType": "ORDER_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "COMPLETE_PARTIAL",
    "lineItems": [{
      "lineItemId": "LI789012",
      "product": {
        "productIdentifier": { "amazonSku": "SKU123" },
        "perUnitDeclaredValue": { "currencyCode": "USD", "amount": "14.99" }
      },
      "amount": { "unit": "EACHES", "value": "2.0" },
      "cancelledAmount": { "unit": "EACHES", "value": "0" },
      "unfulfillableAmount": { "unit": "EACHES", "value": "1.0" }
    }]
  }
}

Cancelled

The order was cancelled. The order status is CANCELLED, and cancelledAmount equals the full ordered quantity.

{
  "merchantId": "merchantId",
  "eventType": "ORDER_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "CANCELLED",
    "lineItems": [{
      "lineItemId": "LI789012",
      "product": {
        "productIdentifier": { "amazonSku": "SKU123" },
        "perUnitDeclaredValue": { "currencyCode": "USD", "amount": "14.99" }
      },
      "amount": { "unit": "EACHES", "value": "2.0" },
      "cancelledAmount": { "unit": "EACHES", "value": "2.0" },
      "unfulfillableAmount": { "unit": "EACHES", "value": "0" }
    }]
  }
}

Shipped — single package

A shipment has left the fulfillment center. Use packages[].tracking.carrier to retrieve carrier tracking information. Because the order's single package has shipped, the order status is COMPLETE and the package status is IN_TRANSIT.

{
  "merchantId": "merchantId",
  "eventType": "SHIPMENT_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "COMPLETE",
    "shipments": [{
      "amazonShipmentId": "SHIP901234",
      "amazonFacility": { "facilityId": "FC456" },
      "status": "SHIPPED",
      "items": [{
        "productIdentifier": { "amazonSku": "SKU123" },
        "lineItemId": "LI789012",
        "amount": { "value": "2.0", "unit": "EACHES" },
        "packageId": "123",
        "shipmentItemId": "SI001"
      }],
      "packages": [{
        "packageId": "123",
        "status": "IN_TRANSIT",
        "tracking": {
          "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456789" },
          "amazon": { "trackingNumber": "234567890" }
        },
        "shipmentItemIds": ["SI001"]
      }]
    }]
  }
}

Shipped — multiple packages

Items in the order shipped in two separate packages. Iterate over all entries in packages[] to collect every tracking number.

{
  "merchantId": "merchantId",
  "eventType": "SHIPMENT_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "PROCESSING",
    "shipments": [{
      "amazonShipmentId": "SHIP901234",
      "amazonFacility": { "facilityId": "FC456" },
      "status": "SHIPPED",
      "items": [
        {
          "productIdentifier": { "amazonSku": "SKU123" },
          "lineItemId": "LI789012",
          "amount": { "value": "1.0", "unit": "EACHES" },
          "packageId": "123",
          "shipmentItemId": "SI001"
        },
        {
          "productIdentifier": { "amazonSku": "SKU123" },
          "lineItemId": "LI789012",
          "amount": { "value": "1.0", "unit": "EACHES" },
          "packageId": "456",
          "shipmentItemId": "SI002"
        }
      ],
      "packages": [
        {
          "packageId": "123",
          "status": "PROCESSING",
          "tracking": {
            "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456789" },
            "amazon": { "trackingNumber": "234567890" }
          },
          "shipmentItemIds": ["SI001"]
        },
        {
          "packageId": "456",
          "status": "PROCESSING",
          "tracking": {
            "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456790" },
            "amazon": { "trackingNumber": "234567891" }
          },
          "shipmentItemIds": ["SI002"]
        }
      ]
    }]
  }
}

Delivered

Each SHIPMENT_PACKAGE_STATUS_CHANGED event reflects the packages whose status changed. When packages in a multi-package shipment are delivered at different times, an event may include only the subset of packages that reached the new status — not necessarily every package in the shipment. Use packages[].deliveryTime for the estimated delivery time of a package.

{
  "merchantId": "merchantId",
  "eventType": "SHIPMENT_PACKAGE_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "COMPLETE",
    "shipments": [{
      "amazonShipmentId": "SHIP901234",
      "amazonFacility": { "facilityId": "FC456" },
      "status": "SHIPPED",
      "items": [{
        "productIdentifier": { "amazonSku": "SKU123" },
        "lineItemId": "LI789012",
        "amount": { "value": "1.0", "unit": "EACHES" },
        "packageId": "123",
        "shipmentItemId": "SI001"
      }],
      "packages": [{
        "packageId": "123",
        "status": "DELIVERED",
        "deliveryTime": "2026-07-03T18:45:00.000Z",
        "tracking": {
          "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456789" },
          "amazon": { "trackingNumber": "234567890" }
        },
        "shipmentItemIds": ["SI001"]
      }]
    }]
  }
}

Delayed

A package has encountered a delivery delay. Use the carrier tracking number to surface delay details to customers.

{
  "merchantId": "merchantId",
  "eventType": "SHIPMENT_PACKAGE_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "PROCESSING",
    "shipments": [{
      "amazonShipmentId": "SHIP901234",
      "amazonFacility": { "facilityId": "FC456" },
      "status": "SHIPPED",
      "items": [{
        "productIdentifier": { "amazonSku": "SKU123" },
        "lineItemId": "LI789012",
        "amount": { "value": "1.0", "unit": "EACHES" },
        "packageId": "123",
        "shipmentItemId": "SI001"
      }],
      "packages": [{
        "packageId": "123",
        "status": "DELAYED",
        "tracking": {
          "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456789" },
          "amazon": { "trackingNumber": "234567890" }
        },
        "shipmentItemIds": ["SI001"]
      }]
    }]
  }
}

Undeliverable or expired

The package could not be delivered (UNDELIVERABLE) or its delivery window expired (EXPIRED).

{
  "merchantId": "merchantId",
  "eventType": "SHIPMENT_PACKAGE_STATUS_CHANGED",
  "order": {
    "orderId": "ABC123XYZ",
    "status": "PROCESSING",
    "shipments": [{
      "amazonShipmentId": "SHIP901234",
      "amazonFacility": { "facilityId": "FC456" },
      "status": "SHIPPED",
      "items": [
        {
          "productIdentifier": { "amazonSku": "SKU123" },
          "lineItemId": "LI789012",
          "amount": { "value": "1.0", "unit": "EACHES" },
          "packageId": "123",
          "shipmentItemId": "SI001"
        },
        {
          "productIdentifier": { "amazonSku": "SKU123" },
          "lineItemId": "LI789012",
          "amount": { "value": "1.0", "unit": "EACHES" },
          "packageId": "456",
          "shipmentItemId": "SI002"
        }
      ],
      "packages": [
        {
          "packageId": "123",
          "status": "UNDELIVERABLE",
          "tracking": {
            "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456789" },
            "amazon": { "trackingNumber": "234567890" }
          },
          "shipmentItemIds": ["SI001"]
        },
        {
          "packageId": "456",
          "status": "EXPIRED",
          "tracking": {
            "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456790" },
            "amazon": { "trackingNumber": "234567891" }
          },
          "shipmentItemIds": ["SI002"]
        }
      ]
    }]
  }
}

Related topics

Updated 4 days ago

Policies and Agreements    Privacy notice   |   Conditions of use