improved

Launch Announcement: Additional Information in Tracking API and Push Notifications available WW.

We are thrilled to announce that additional information to provide finer level of details about tracking a package has been introduced WW. These updates are applied to Get Tracking API and Push Notification features.

Why is this important?

Amazon Shipping has now additional fields and information into the tracking API and Push notifications to provide you with a finer level of detail when tracking packages. We have introduced these new details to indicate when a parcels tracking event occurs in either a forward or reverse leg. We have added 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 have also extended the existing list of events to better allow you to track your package.

What is included in this enhancement?

Following are the overview of three changes available now 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 have 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 are now providing 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 have expanded 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 have also created a new status type for when a package is being held for customer pickup.

These features are available WW across US, UK, IN, IT, FR and ES.

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

NameDescriptionSchema
eventCode (required)The tracking event type.EventCode
location (optional)The location where the person, business or institution is located.Location
eventTime (required)The ISO 8601 formatted timestamp of the event.String (date-time)
shipmentType (required) NewIndicates whether the event is for the forward or reverse leg.shipmentType

shipmentType New

Type: enum

ValueDescription
FORWARDThe packages journey to the end recipient
RETURNSThe package is being returned back to the shipper

Change 2- Tracking detail codes field added:

GetTrackingResult

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

NameDescriptionSchema
trackingId (required)The carrier generated identifier for a package in a purchased shipment.TrackingId
alternateLegTrackingId (required)The carrier generated reverse identifier for a returned package in a purchased shipment.AlternateLegTrackingId
eventHistory (required)A list of tracking events.Event
promisedDeliveryDate (required)The date and time by which the shipment is promised to be delivered.String (date-time)
summary (required)A package status summary.TrackingSummary

trackingSummary

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

NameDescriptionSchema
status (optional)The status of the package being shipped.Status
trackingDetailCodes (optional) NewContains additional details related to the shipment status.trackingDetailCodes

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.

NameDescriptionSchema
forward (optional)Contains detail codes that provide additional details related to the forward leg of the shipment.detailCodes array
returns (optional)Contains detail codes that provide additional details related to the return leg of the shipment.detailCodes array

detailCodes New

Type : enum

Contains additional details related to the shipment status.

ValueDescription
BusinessClosedAttempted delivery but the business was closed
CustomerUnavailableAttempted delivery but the Recipient was Unavailable
PaymentNotReadyAttempted delivery but cash was not available from Recipient
OtpNotAvailableAttempted delivery but the recipient did not have the PIN available
DeliveryAttemptedDelivery was attempted
UnableToAccessAttempted delivery but could not access the recipient location
UnableToContactRecipientAttempted delivery but is unable to contact the recipient to coordinate delivery
DeliveredToBehindWheelieBinShipment delivered behind wheelie bin
DeliveredToPorchShipment delivered to front porch or front door
DeliveredToGarageShipment delivered to garage
DeliveredToGardenShipment delivered to garden
DeliveredToGreenhouseShipment delivered to greenhouse
DeliveredToMailSlotShipment delivered to letterbox/Mail slot
DeliveredToMailRoomShipment delivered to mailroom
DeliveredToNeighborShipment delivered and signed for by neighbor
DeliveredToRearDoorShipment delivered to rear porch or rear door
DeliveredToReceptionistShipment delivered to reception
DeliveredToShedShipment delivered to shed
SignedShipment delivered and signature received
DamagedShipment was damaged. When paired with "REJECTED" this indicates the Recipient refused to accept the shipment because the shipment was damaged. When paired with "UNDELIVERABLE" it means the shipment was undeliverable due to being damaged and may be returned to the seller.
IncorrectItemsRecipient refused to accept the shipment because the shipment contains the incorrect item
NotRequiredRecipient refused to accept the shipment because the recipient did not want the shipment
RejectedRecipient refused to accept the shipment
CancelledByRecipientShipment was cancelled by the recipient. This tag is paired with the rejected Shipment status
AddressNotFoundShipment is undeliverable and is returning to seller because the address was missing or incorrect
HazmatShipmentShipment is non-compliant Hazmat
UndeliverableShipment is undeliverable and is returning to seller

Change 3- New Event codes & Status:

EventCode

The tracking event type.

Type : enum

ValueDescription
ReadyForReceivePackage has been created and is ready for pickup at the shipper's location. This is a pre-transit status event code.
PickupDonePackage has been picked up by the service provider.
DeliveredPackage has been delivered. When this tracking event occurs with the leg type of "REVERSE" this means that the package has been successfully returned to the shipper.
DepartedPackage has departed from a particular location in carrier network.
DeliveryAttemptedDelivery was attempted, but was unsuccessful.
LostPackage is lost.
OutForDeliveryPackage is out for delivery.
ArrivedAtCarrierFacilityPackage is in transit and has been received at a carrier location.
RejectedPackage was rejected by the recipient.
UndeliverablePackage is undeliverable.
PickupCancelledPickup scheduled for the package was cancelled.
ReturnInitiated NewReturn label has been generated.
AvailableForPickup NewPackage held for recipient pickup.

Status

The status of the package being shipped.

Type : enum

ValueDescription
PreTransitPackage has been created but has not been picked up.
InTransitPackage has been picked up and is in transit.
DeliveredPackage has been delivered successfully.
LostPackage is lost.
OutForDeliveryPackage is out for delivery.
RejectedPackage has been rejected by the recipient.
UndeliverablePackage was undeliverable.
DeliveryAttemptedDelivery was attempted to the recipient location, but was not delivered.
PickupCancelledPickup was cancelled for the package.
AwaitingCustomerPickup NewPackage held at facility for the customer pickup.

Push Notification changes:

The Push notifications have also got 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

NameDescriptionSchema
trackingDetailCodes (optional) NewContains status codes that provide additional details related to the forward leg of the shipmentdetailCodes array

detailCodes New

Type : enum

ValueDescription
BusinessClosedAttempted delivery but the business was closed.
CustomerUnavailableAttempted delivery but the Recipient was Unavailable.
PaymentNotReadyAttempted delivery but cash was not available from Recipient.
OtpNotAvailableAttempted delivery but the recipient did not have the PIN available.
DeliveryAttemptedDelivery was attempted
UnableToAccessAttempted delivery but could not access the recipient location
UnableToContactRecipientAttempted delivery but is unable to contact the recipient to coordinate delivery
DeliveredToBehindWheelieBinShipment delivered behind wheelie bin
DeliveredToPorchShipment delivered to front porch or front door
DeliveredToGarageShipment delivered to garage
DeliveredToGardenShipment delivered to garden
DeliveredToGreenhouseShipment delivered to greenhouse
DeliveredToMailSlotShipment delivered to letterbox/Mail slot
DeliveredToMailRoomShipment delivered to mailroom
DeliveredToNeighborShipment delivered and signed for by neighbor
DeliveredToRearDoorShipment delivered to rear porch or rear door
DeliveredToReceptionistShipment delivered to reception
DeliveredToShedShipment delivered to shed
SignedShipment delivered and signature received
DamagedShipment was damaged. When paired with "REJECTED" this indicates the Recipient refused to accept the shipment because the shipment was damaged. When paired with "UNDELIVERABLE" it means the shipment was undeliverable due to being damaged and may be returned to the seller.
IncorrectItemsRecipient refused to accept the shipment because the shipment contains the incorrect item
NotRequiredRecipient refused to accept the shipment because the recipient did not want the shipment
RejectedRecipient refused to accept the shipment
CancelledByRecipientShipment was cancelled by the recipient. This tag is paired with the rejected shipment status.
AddressNotFoundShipment is undeliverable and is returning to seller because the address was missing or incorrect
HazmatShipmentShipment is non-compliant Hazmat
UndeliverableShipment is undeliverable and is returning to seller

FAQs:

  1. Are these fields available in the API Reference Docs?
    Yes, the updated tracking api response schema and push notification request schema are available under API Reference Page and Tracking Push Notification.

  2. 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.

  3. 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.

  4. 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.

  5. 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.