FULFILLMENT_ORDER_STATUS Notification Migration Guide

A new payload version of the FULFILLMENT_ORDER_STATUS notification is now available: 2026-07-04. This version introduces a redesigned schema aligned with the Fulfillment Outbound API v2026-07-04 model, to simplify correlating notification data with API responses without field mapping. Existing developers who subscribed using the legacy PayloadVersion 1.0 can continue to receive updates by noting the schema differences in this guide and updating their field references.

Both 1.0 and 2026-07-04 are supported. A subscription uses one payload version at a time, so you do not need to maintain subscriptions on both versions simultaneously.

What's new

1. New package-level event type: The v2026-07-04 notification adds a new SHIPMENT_PACKAGE_STATUS_CHANGED event that reports package delivery progress (IN_TRANSIT, OUT_FOR_DELIVERY, DELAYED, DELIVERED, UNDELIVERABLE, EXPIRED). The legacy notification had no package-level delivery events.
2. Estimated delivery time on packages: The notification includes packages[].deliveryTime — the estimated delivery date and time of the package. This estimate is available before the package is delivered, so you no longer need to call getOrder to obtain a delivery estimate.
3. Schema aligned with Outbound API v2026-07-04: Field names, object structure, and status values across the notification payload now match the getOrder and listOrders response model. Developers who have already migrated to the Outbound API v2026-07-04 will recognize the field names without additional mapping.

Key changes

1. EventType string replaced by eventType enumeration. The legacy EventType values "Order" and "Shipment" map to ORDER_STATUS_CHANGED and SHIPMENT_STATUS_CHANGED. These two events are not new — only the field name and values changed. SHIPMENT_PACKAGE_STATUS_CHANGED is the only new event type in v2026-07-04. Returns are no longer delivered via this notification.
2. Order status values changed: Complete, CompletePartialled, Unfulfillable, Processing → COMPLETE, COMPLETE_PARTIAL, UNFULFILLABLE, PROCESSING. The v2026-07-04 order status set also includes CANCELLED and INVALID.
3. Payload wrapper renamed to order. The legacy Payload.FulfillmentOrderStatusNotification wrapper is removed; order fields are now under Payload.order.
4. FulfillmentShipment single object replaced by order.shipments[] array. The array shape gives flexibility for future multi-shipment scenarios. Multiple shipments per order are not currently supported, so expect a single entry in shipments[].
5. FulfillmentShipmentPackages[] renamed to packages[]. PackageNumber (integer) is replaced by packageId (string). Carrier and tracking info are now nested under a tracking object.
6. StatusUpdatedDateTime replaced by EventTime. The event timestamp has moved to the notification envelope (top-level field), consistent with all other SP-API notification types.

This guide details the changes to the notification payload structure and the steps to update your subscription and parser.

Notification payload structure

The notification payload structure has been updated.

Parameters and structure:

Sample notification — shipment shipped:

v1.0 sample notification

{
  "NotificationVersion": "1.0",
  "NotificationType": "FULFILLMENT_ORDER_STATUS",
  "PayloadVersion": "1.0",
  "EventTime": "2020-01-11T00:09:53.109Z",
  "Payload": {
    "FulfillmentOrderStatusNotification": {
      "SellerId": "merchantId",
      "EventType": "Shipment",
      "StatusUpdatedDateTime": "2020-01-11T00:09:53.109Z",
      "SellerFulfillmentOrderId": "ABC123XYZ",
      "FulfillmentOrderStatus": "Complete",
      "FulfillmentShipment": {
        "FulfillmentShipmentStatus": "Shipped",
        "AmazonShipmentId": "SHIP901234",
        "EstimatedArrivalDateTime": "2020-01-14T22:59:59Z",
        "FulfillmentShipmentPackages": [{
          "PackageNumber": 123,
          "CarrierCode": "FEDEX",
          "TrackingNumber": "123456789"
        }]
      }
    }
  },
  "NotificationMetadata": {
    "ApplicationId": "amzn1.sellerapps.app.f1234566-aaec-55a6-b123-bcb752069ec5",
    "SubscriptionId": "7d78cc50-95c8-4641-add7-10af4b1fedc9",
    "PublishTime": "2020-01-11T00:02:50.501Z",
    "NotificationId": "2012e8e5-b365-4cb1-9fd8-be9dfc6d5eaf"
  }
}

v2026-07-04 sample notification

{
  "NotificationVersion": "1.0",
  "NotificationType": "FULFILLMENT_ORDER_STATUS",
  "PayloadVersion": "2026-07-04",
  "EventTime": "2026-07-04T00:02:48.501Z",
  "Payload": {
    "merchantId": "merchantId",
    "eventType": "SHIPMENT_STATUS_CHANGED",
    "order": {
      "orderId": "ABC123XYZ",
      "status": "PROCESSING",
      "shipments": [{
        "amazonShipmentId": "SHIP901234",
        "amazonFacility": { "facilityId": "FC456" },
        "status": "SHIPPED",
        "items": [{
          "lineItemId": "LI789012",
          "productIdentifier": { "amazonSku": "SKU123" },
          "amount": { "value": "2.0", "unit": "EACHES" },
          "packageId": "123",
          "shipmentItemId": "SI001"
        }],
        "packages": [{
          "packageId": "123",
          "status": "PROCESSING",
          "tracking": {
            "carrier": { "carrierCode": "FEDEX", "trackingNumber": "123456789" },
            "amazon": { "trackingNumber": "234567890" }
          },
          "shipmentItemIds": ["SI001"]
        }]
      }]
    }
  },
  "NotificationMetadata": {
    "ApplicationId": "app-id-d0e9e693-c3ad-4373-979f-ed4ec98dd746",
    "SubscriptionId": "subscription-id-d0e9e693-c3ad-4373-979f-ed4ec98dd746",
    "PublishTime": "2026-07-04T00:02:50.501Z",
    "NotificationId": "2012e8e5-b365-4cb1-9fd8-be9dfc6d5eaf"
  }
}

Updating your subscription

Update the payloadVersion in your createSubscription call from "1.0" to "2026-07-04". No other changes are needed to the subscription request.

v1.0 sample notification

POST /notifications/v1/subscriptions/FULFILLMENT_ORDER_STATUS

{
  "payloadVersion": "1.0",
  "destinationId": "your-sqs-destination-id"
}

v2026-07-04 sample notification

POST /notifications/v1/subscriptions/FULFILLMENT_ORDER_STATUS

{
  "payloadVersion": "2026-07-04",
  "destinationId": "your-sqs-destination-id"
}

📘

Note

If you have an existing active subscription with payloadVersion: "1.0", create a new subscription with payloadVersion: "2026-07-04" and delete the old one after validating your updated handler.

New event type

SHIPMENT_PACKAGE_STATUS_CHANGED

SHIPMENT_PACKAGE_STATUS_CHANGED is the only new event type in v2026-07-04. It fires when a package status changes to IN_TRANSIT, OUT_FOR_DELIVERY, DELAYED, DELIVERED, UNDELIVERABLE, or EXPIRED.

packages[].deliveryTime carries the estimated delivery date and time of the package, which is available before the package is delivered.

📘

Note

ORDER_STATUS_CHANGED and SHIPMENT_STATUS_CHANGED are not new — they correspond to the legacy EventType values "Order" and "Shipment". Only the field name (eventType) and the values changed.

Related topics

• FULFILLMENT_ORDER_STATUS notification reference — Field reference tables and payload schema.
• View order notifications with the Notifications API — Subscribe to and handle FULFILLMENT_ORDER_STATUS notifications.
• Fulfillment Outbound API Migration Guide — Migrate from Fulfillment Outbound v2020-07-01 to v2026-07-04.