Push Notifications - NDR Eligible Shipments

This functionality, provided by Amazon Shipping, enables shippers and integrator to obtain NDR-eligible tracking IDs as soon as they become eligible, directly through their webhook. This eliminates the requirement for any external API requests. Developers, including shippers and integrator, have the ability to subscribe to updates for NDR eligible tracking IDs via their webhook URL endpoint.

Steps to subscribe:

1. The shipper/integrator needs to provide their Webhook URL, Application ID, Shipping Party Account ID (for whom NDR push notifications are being setup), and their technical point of contact to the integration POC within Amazon.
2. The integration POC will internally coordinate configuring and activating the subscription for notifications.

Below client identification (Authentication) mechanism is supported for push notifications (One of these has to be enabled by the Shipper/Integrator):

1. API key - An API key is a token that a client (Amazon) provides while sending tracking information to webhook URL. With API key auth, we send a key-value pair to the webhook endpoint in the request headers. Please refer to API Key Authenticationfor more details.
   Example: X-API-KEY: abcdef12345
2. Query parameter - A key value pair which will be passed in the URL. Using query parameters to authenticate requests is useful when we want to express a request entirely in a URL. Please refer to Query Parameter Authenticationfor more details.
   Example: https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Credential=
3. Username & Password - it's a key value pair which will be passed in header to authenticate the incoming request via username and password. Please Refer to Username and Password Authentication for more details.
4. OAuth authentication - The Open Authorization is a flexible authorization framework for securing application access to protected resources. OAuth 2.0 uses access tokens that are presented by client applications (on behalf of the end users) to access the protected resources. Please refer to OAuth Authorization for more details.

Push Notification payload includes the following elements:

Sample event:

{
  "version": "0",
  "id": "48af9743-336e-00eb-7194-de9975baa012",
  "detail-type": "NDR Events",
  "source": "AmazonShipping",
  "account": "434519225125",
  "time": "2024-02-21T19:33:09Z",
  "region": "eu-west-1",
  "resources": [],
  "detail": {
    "trackingId": "1809561149386",
    "referenceID": "795817695",
    "latestDeliveryAttemptedDate": "2023-12-27T01:35:24Z",
    "deliveryAttemptCount": "4",
    "shipmentStatus": "Undeliverable",
    "reasonCode": "Customer rejected",
    "paymentType": "CollectOnDelivery",
    "ndrDueDate": "2023-12-28T04:08:59Z",
    "expectedDeliveryDate": "2023-12-29T14:30:00Z",
    "shippingPartyAccountId": "A109W4MEBU BWQI",
    "appId": "amzn1.sp.solution.4622520d-ef11-4366-aa17-5ff8bb0b1010",
    "version": 4,
    "timeToLive": 1703188564
  }
}
 

FAQ

1. Which are the required fields in the payload?
TrackingId and NdrAction must always be provided as they are mandatory fields. Additionally, if the NdrAction is set to Reschedule, the rescheduleDate field becomes mandatory. Similarly, if the NdrAction is set to Reattempt, the additionalAddressNotes field is also required.

2. What is additionalAddressNotes?
AdditionalAddressNotes is the additional information associated with an address. These notes can include supplementary details that are relevant to the address of the recipient customer.

3. What type of data can we pass in additionalAddressNotes?
It should have information associated with an address and has character limit of 256. It must not include recipients' phone number or related personal information.

4. Will there be any change in NDR eligible shipments logic and what all information I receive as part of eligible shipment info?

With this product launch, we are not changing any logic for eligible shipments. We are providing an additional medium for shippers to share the feedback and receive NDR eligible shipments. Also, the information shared on the NDR eligible (excel) will be shared as part of NDR push notification for eligible shipments (except address filed)

5. Can I continue to share the feedback via bulk upload excel?

Yes, we are not restricting access for bulk upload excel. You can continue to use the bulk upload functionality to share the feedback.

6. We are not enabled for NDR push notifications, can we still send NDR feedback via API?

Yes, you can use NDR feedback API to send the feedback even without NDR push notifications. You can refer NDR UI to fetch eligible list and share the feedback for those tracking ids via API.

7. How to act on "Reason Codes"?

Here is a list of next actions to be taken by you for the respective reason codes:

o Address not found: You can choose “Reattempt with address notes” and provide additional address details in column K, also marked as “Address Notes”
o Unable to contact customer: You can choose “Reattempt with address notes” and provide additional phone number details in column K
o Customer unavailable/ Payment not ready: You can use “Reschedule” option to select date on which you want us to reattempt the delivery of the shipment.
o Rejected not required: You should contact the customer to determine the next step. Based on the customer response, select either “Return to origin approved” or “Reschedule” or “Re-attempt with additional notes” to re-attempt the shipment.

8. What are the available shipmentStatus and reasonCode?

o shipmentStatus:

Attempted
Rejected
Undeliverable

o reasonCode:

Not required
No items delivered
Customer rejected
Other
Inaccessible delivery location
Customer unavailable
Payment not ready
Unable to contact customer
Rescheduled by customer
OTP not available
Other
Bad weather
Business closed
Address not found
Customer not at address
Other
Out of jurisdiction
Wrong address
Unable to access
Customer rejected

9. Will we also get a summary via API?

No, we currently do not share the performance summary via API. However, you can continue to fetch from the NDR portal (https://ship.amazon.in/non-delivery-report)

10. How long does it take to enable the push notifications?

It takes 7-10 business days to enable the push notifications post receiving the details.

11. How can Shipper/ Integrator request for Push Notification Tracking?

Please write to [email protected] to request for push notification for your use-case.