Pre-Launch Announcement: “Amazon Shipping Tracking Enhancement” - Introducing Additional Information in Tracking API and Push Notifications!

We are thrilled to introduce additional information to provide finer level of details about tracking a package. These updates would be applied to Get Tracking API and Push Notification features.

What is improving?

Amazon Shipping is introducing additional fields and information into the tracking API and Push notifications to provide you with a finer level of detail when tracking packages. We are introducing new details to indicate when a parcels tracking event occurs in either a forward or reverse leg. We are adding a new field where additional details will be provided surrounding a packages status, e.g., if it was delivered to reception vs left on front porch, the reason for a package being rejected, or why it was marked as undeliverables. We will also provide additional events to the existing list to better allow you to track your package.

When it is happening?

The scheduled launch date is set for May 03, 2024.

What is included in this enhancement?

Following are the overview of three changes that are going to be available via this enhancement,

1.Shipment type

In order to determine whether a package is in transit to the recipient or if it's being returned back to the shipper, we added a new field shipmentType to provide which leg of the package an event occurred. It will indicate forward for the tracking events that happen when the package is in transit to the recipient, and returns for when the package is being returned. By checking the tracking events you can easily see what stage of the packages journey it is in.

2.Tracking detail codes

We will now provide you with additional details about the status of a package in the form of a new field called trackingDetailCodes. These are additional details that would provide additional value to users. This can include things like where the package was delivered if left in a safe place, why it was rejected, why the package was not delivered, etc. This will be separated out into the forward and reverse codes to allow you to differentiate which leg of the packages journey the events occurred.

3.List of Events and Statuses

We are expanding the list of possible event codes that we surface in the tracking response to include an event when a return shipping label is generated, and when a package is being held for the recipient to pick up. We are also creating a new status type for when a package is being held for customer pickup.

This feature will be available WW across US, UK, IN, IT, FR and ES.

What action is required from my end?

To leverage these new fields, ensure that your mapping is updated to accommodate the additional fields. Make the necessary adjustments in your systems or applications to capture and process the enhanced tracking data.

Sample request and response JSON for the API:

Get Tracking API Response Sample:

{
    "payload": {
        "alternateLegTrackingId": "UK0000313459",
        "eventHistory": [
            {
                "eventCode": "ReadyForReceive",
                "eventTime": "2023-12-11T04:11:31Z",
                "shipmentType": "FORWARD", //[New] Identifier for what leg of the shipment journey the event occurred
                "location": {}
            },
            {
                "eventCode": "PickupDone",
                "eventTime": "2023-12-11T17:01:39Z",
                "shipmentType": "FORWARD",
                "location": {
                    "city": "Coalville",
                    "countryCode": "GB",
                    "postalCode": "LE67 1PB",
                    "stateOrRegion": "Leicestershire"
                }
            },
            {
                "eventCode": "Rejected",
                "eventTime": "2023-12-11T17:03:30Z",
                "shipmentType": "FORWARD",
                "location": {
                    "city": "Coalville",
                    "countryCode": "GB",
                    "postalCode": "LE67 1PB",
                    "stateOrRegion": "Leicestershire"
                }
            },
            {
                "eventCode": "ReturnInitiated", //[New] type of tracking event
                "eventTime": "2023-12-11T17:03:30Z",
                "shipmentType": "RETURNS", // [New] Field that indicates that the event was related to a packages reverse journey
                "location": {
                    "city": "Coalville",
                    "countryCode": "GB",
                    "postalCode": "LE67 1PB",
                    "stateOrRegion": "Leicestershire"
                }
            },
            {
                "eventCode": "Undeliverable",
                "eventTime": "2023-12-11T17:03:30Z",
                "shipmentType": "RETURNS",
                "location": {
                    "city": "Coalville",
                    "countryCode": "GB",
                    "postalCode": "LE67 1PB",
                    "stateOrRegion": "Leicestershire"
                }
            }
        ],
        "promisedDeliveryDate": "2023-12-14T20:00:00Z",
        "summary": {
            "status": "InTransit",
            "trackingDetailCodes": // [New] This provides additional details about a shipment.
            {
                "forward": [
                    "Rejected",
                    " NotRequired"
                ], //[New] These are some of the additional details available, in this example it means the package was rejected by the recipient due to it no longer being required 
                "returns": [
                    "Undeliverable",
                    "Damaged"
                ] //[New] The forward and return leg are separated to distinguish which leg of the journey the status code is applicable to
            }
        },
        "trackingId": "UK0123456789"
    }
}

Change 1- Shipment Type field added:

Event

Type: A tracking event object

shipmentType New

Type: enum

Change 2- Tracking detail codes field added:

GetTrackingResult

The payload for the getTracking operation. There will be no changes to this object.

trackingSummary

A package status summary. This object will have a new field type to provide additional tracking details.

trackingDetailCodes New

Contains additional details related to the shipment status. This field includes both the detail codes for the forward and return leg of a shipment, if available. If the shipment is being returned, then the detail codes in the forward section will contain the final detail codes for the forward leg and any detail codes specific to the return leg of the journey will be populated in the returns section. The detail codes are optional and will only be populated when there is additional details available.

detailCodes New

Type : enum

Contains additional details related to the shipment status.

Change 3- New Event codes & Status:

EventCode

The tracking event type.

Type : enum

Status

The status of the package being shipped.

Type : enum

Push Notification changes:

The Push notifications will also be getting the new field types for the shipmentType and the trackingDetailCodes. The push notifications will only include the detail codes for the current shipment type, either forward or reverse. This means that if the shipment type is return, then the package is being returned to the shipper and any tags that are populated are associated with the return leg. To see the detail codes for the forward leg of a returning parcel a user can use the existing tracking API.

Push Notification Request Sample:

{
    "version": "0",
    "id": "2d1cf554-e7f0-2362-6b2d-dd36bd4677e2",
    "detail-type": "Tracking Detail",
    "source": "AmazonShipping",
    "account": "434519225125",
    "time": "2023-01-23T11:09:42Z",
    "region": "eu-west-1",
    "resources": [],
    "detail": {
        "shippingPartyAccountId": "A1QW4MEBU0BWQI",
        "trackingId": "test_tracking_id",
        "eventTime": "2023-01-16T15:39:23Z",
        "status": "InTransit",
        "alternateLegTrackingId": "65665589589",
        "eventCode": "PickupDone",
        "appId": "amzn1.sp.solution.4622520d-ef11-4366-aa17-5ff8bb0b9aea",
        "shipmentType": "FORWARD", // [New] field that indicates that the event was related to a packages reverse journey 
        "trackingDetailCodes": [
            "DeliveredToPorch"
        ], // [New] This provides additional details about a shipment.
        "version": 2,
        "timeToLive": 1679569781
    }
}

trackingDetailCodes New

detailCodes New

Type : enum

FAQs:

1. Are these fields available in the API Reference Docs?
   Yes, the updated tracking api response schema and push notification request schema will be available under API Reference Page on or before 03rd of May, 2024.

2. Can I keep using my GetTracking API after the rollout of new fields?
   Yes, you can continue using your API without mapping the new fields, ensuring backward compatibility.

3. Do I need to map the new fields in Push Notification immediately?
   No, you can continue using existing push notification without mapping the new fields and plan to incorporate the new fields.

4. Is there a way to opt out of receiving additional information as it affects my current mapping?
   We apologize, but currently, there isn't an option to opt out of receiving additional information for get tracking api and push notifications.