labels

Get label tracking information

Changed on

Retrieve the label's tracking information

get/v1/labels/{label_id}/track

Request

  • Base URL: https://api.shipengine.com
  • URL: https://api.shipengine.com/v1/labels/{label_id}/track
  • Auth: API key in header API-Key

Response

The request was a success.

tracking_numberstring

A tracking number for a package. The format depends on the carrier.

tracking_urlstring

Carrier Tracking Url, if available

status_code'UN' | 'AC' | 'IT' | 'DE' | 'EX' | 'AT' | 'NY' | 'SP'

The tracking status codes

ValueDescription
UNUnknown
ACAccepted
ITIn Transit
DEDelivered
EXException
ATDelivery Attempt
NYNot Yet In System
SPDelivered To Collection Location
status_detail_code'CARRIER_STATUS_NOT_MAPPED' | 'SHIPMENT_CREATED' | 'AWAITING_PICKUP_DROP_OFF' | 'DROPPED_OFF' | 'ELEC_ADVICE_RECD_BY_CARRIER' | 'PICKED_UP' | 'CUSTOMS_CLEARED' | 'CUSTOMS_PROCESSING' | 'DELIVERY_ARRANGED_WITH_RECIPIENT' | 'HUB_SCAN_OUT' | 'HUB_SCAN_IN' | 'IN_TRANSIT' | 'INFORMATION' | 'PARCEL_OVER_LABELLED' | 'PARCEL_UPDATE_NOTIFICATION' | 'RECEIVED_BY_CARRIER' | 'RECEIVED_LOCAL_DELIVERY_DEPOT' | 'SUB_CONTRACTOR_EVENT' | 'SUB_CONTRACTOR_RECEIVED' | 'PARCEL_REDIRECTED' | 'DELIVERY_SCHEDULED' | 'HUB_PROCESSING' | 'DELIVERY_RESCHEDULED' | 'ATTEMPTED_DELIVERY' | 'ATTEMPTED_DELIVERY_FINAL' | 'COD_AMOUNT_PAID' | 'CUSTOMER_CARDED' | 'OUT_FOR_DELIVERY' | 'AWAITING_COLLECTION_FROM_PICKUP_POINT' | 'COLLECT_AT_LOCAL_PO' | 'CUSTOMER_TO_COLLECT_FROM_CARRIER' | 'DELIVERED_TO_RECEPTION' | 'DELIVERED' | 'DELIVERED_DAMAGED' | 'DELIVERED_IN_PART' | 'DELIVERED_SPECIFIED_SAFE_PLACE' | 'DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION' | 'DELIVERED_TO_NEIGHBOUR' | 'DELIVERED_TO_PO_BOX' | 'PARCEL_COLLECTED_FROM_PICKUP_POINT' | 'POST_TRANSIT_STATUS' | 'PROOF_OF_DELIVERY' | 'PICKUP_FAILED' | 'NOT_YET_RECEIVED_BY_CARRIER' | 'PARCEL_DAMAGED' | 'ADDRESS_QUERY' | 'CARRIER_DELAYS' | 'DELAYED_NOT_CARRIER' | 'HELD_BY_CARRIER' | 'HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING' | 'HELD_BY_CUSTOMS' | 'INCORRECT_DECLARATION' | 'MISROUTED' | 'PARCEL_REPACKED' | 'RECD_BY_CARRIER_NO_ELEC_ADVICE' | 'COD_AMOUNT_NOT_PAID' | 'CUSTOMER_IDENTIFICATION_FAILED' | 'NO_ACCESS_TO_RECIPIENTS_ADDRESS' | 'CANCELLED' | 'CUSTOMER_MOVED' | 'HAZARDOUS_PROHIBITED' | 'NOT_COLLECTED_FROM_PICKUP_POINT' | 'NOT_DELIVERED' | 'NOT_DELIVERED_ADDRESSEE_DECEASED' | 'PARCEL_DISPOSED' | 'PARCEL_LOST' | 'PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY' | 'REFUSED_BY_CUSTOMER' | 'RETURN_TO_SENDER' | 'UNSPECIFIED_EXCEPTION' | 'TRACKING_EXPIRED' | 'DUTY_NOT_PAID' | 'PARCEL_REDIRECTED_BY_CARRIER' | 'DELIVERED_TO_PICKUP_POINT' | 'UNDELIVERABLE_RETURNED_TO_SENDER'

The tracking status detail codes

ValueDescription
CARRIER_STATUS_NOT_MAPPEDStatus not mapped. Please check the carrier's website for updates.
SHIPMENT_CREATEDYour tracking number is ready. Your parcel is waiting to be registered in the carrier system and scheduled for pickup.
AWAITING_PICKUP_DROP_OFFYour parcel is waiting to be handed over to the carrier.
DROPPED_OFFYour parcel has been dropped off and is ready for carrier processing.
ELEC_ADVICE_RECD_BY_CARRIERYour shipment is now in the carrier's system.
PICKED_UPYour parcel has been picked up by the carrier.
CUSTOMS_CLEAREDYour parcel has cleared customs and is continuing its journey.
CUSTOMS_PROCESSINGYour parcel is currently being processed by customs.
DELIVERY_ARRANGED_WITH_RECIPIENTYour parcel's delivery has been arranged with the carrier.
HUB_SCAN_OUTYour parcel has left the carrier's hub.
HUB_SCAN_INYour parcel has arrived at the carrier's hub for processing.
IN_TRANSITYour shipment is on its way between the carrier hubs.
INFORMATIONThe carrier has shared additional information about your parcel.
PARCEL_OVER_LABELLEDYour parcel's label has been updated by the carrier, which may affect tracking visibility.
PARCEL_UPDATE_NOTIFICATIONThe carrier has sent you an update on your parcel status via SMS or email.
RECEIVED_BY_CARRIERYour parcel has been received by the carrier and is beginning its journey.
RECEIVED_LOCAL_DELIVERY_DEPOTYour parcel has arrived at the local delivery depot and is almost ready for delivery.
SUB_CONTRACTOR_EVENTThe carrier has shared additional information about your parcel's handling by a delivery partner.
SUB_CONTRACTOR_RECEIVEDYour parcel has been received by the carrier's local delivery partner.
PARCEL_REDIRECTEDYour parcel has been redirected to a new delivery address per your request.
DELIVERY_SCHEDULEDYour parcel's delivery has been scheduled and will soon be out for delivery.
HUB_PROCESSINGYour parcel is being processed at a carrier hub.
DELIVERY_RESCHEDULEDYour parcel's delivery has been rescheduled due to operational issues.
ATTEMPTED_DELIVERYThe carrier attempted to deliver your parcel but was unable to complete delivery.
ATTEMPTED_DELIVERY_FINALThe carrier made a final attempt to deliver your parcel but was unable to complete delivery. Please check the carrier's instructions for next steps.
COD_AMOUNT_PAIDCash on delivery payment received.
CUSTOMER_CARDEDDelivery attempt failed. Please follow delivery instructions left by the carrier.
OUT_FOR_DELIVERYYour parcel is on its way and will be delivered today.
AWAITING_COLLECTION_FROM_PICKUP_POINTYour parcel is ready for collection at the selected pickup point.
COLLECT_AT_LOCAL_POYour parcel is ready for collection at your local post office.
CUSTOMER_TO_COLLECT_FROM_CARRIERYour parcel is available for collection from the carrier's local delivery unit.
DELIVERED_TO_RECEPTIONYour parcel has been delivered to your building's reception or designated mail area.
DELIVEREDYour parcel has been successfully delivered.
DELIVERED_DAMAGEDYour parcel was delivered but arrived with visible damage.
DELIVERED_IN_PARTPart of your shipment has been delivered. Check for updates on the rest.
DELIVERED_SPECIFIED_SAFE_PLACEYour parcel has been delivered to your specified safe place.
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATIONYour parcel was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details.
DELIVERED_TO_NEIGHBOURYour parcel was delivered to your neighbor.
DELIVERED_TO_PO_BOXYour parcel has been delivered to your specified PO Box.
PARCEL_COLLECTED_FROM_PICKUP_POINTYour package has been picked up from the pick up point.
POST_TRANSIT_STATUSThe carrier has added more information about your delivery.
PROOF_OF_DELIVERYThe carrier has confirmed delivery with proof, such as a signature or photo.
PICKUP_FAILEDParcel pickup failed. The delivery company will try again soon.
NOT_YET_RECEIVED_BY_CARRIERThe carrier has not yet received your parcel, which may cause a delay.
PARCEL_DAMAGEDYour parcel was damaged in transit but will still be delivered.
ADDRESS_QUERYThere is an issue with the delivery address, which may delay your parcel.
CARRIER_DELAYSYour parcel is delayed due to issues within the carrier network.
DELAYED_NOT_CARRIERYour parcel is delayed due to circumstances beyond the carrier's control.
HELD_BY_CARRIERYour parcel is being held due to an operational issue. Contact with the carrier for more information.
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSINGYour parcel is being held by the carrier for customs documentation checks. This may occur when the carrier must confirm documentation before the parcel can continue its journey.
HELD_BY_CUSTOMSYour parcel is being held at customs, which may delay delivery.
INCORRECT_DECLARATIONYour parcel has been incorrectly declared but is still moving forward for delivery.
MISROUTEDYour parcel was sent to the wrong place due to a routing error but is being redirected.
PARCEL_REPACKEDYour parcel was repackaged by the carrier due to damage and will still be delivered.
RECD_BY_CARRIER_NO_ELEC_ADVICEYour parcel has been received by the carrier but may experience delays due to missing pre-advice.
COD_AMOUNT_NOT_PAIDDelivery failed due to unpaid cash on delivery. Please follow carrier instructions.
CUSTOMER_IDENTIFICATION_FAILEDDelivery couldn't be completed as identification requirements were not met.
NO_ACCESS_TO_RECIPIENTS_ADDRESSThe carrier couldn't access the delivery location due to restricted entry.
CANCELLEDYour parcel has been cancelled.
CUSTOMER_MOVEDDelivery failed as the recipient is no longer at the specified address. Your parcel is being returned.
HAZARDOUS_PROHIBITEDYour parcel contains restricted items and will not be delivered.
NOT_COLLECTED_FROM_PICKUP_POINTYour parcel was not collected from the pickup point within the designated time and will be returned.
NOT_DELIVEREDAll delivery attempts failed. Your parcel is being returned to the sender.
NOT_DELIVERED_ADDRESSEE_DECEASEDThe parcel could not be delivered as the addressee is reported deceased.
PARCEL_DISPOSEDYour parcel has been disposed of due to its contents or condition and will not be delivered.
PARCEL_LOSTThe carrier has reported that your parcel is lost and will not be delivered.
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITYThe parcel cannot be delivered as it exceeds the carrier's service limits.
REFUSED_BY_CUSTOMERYou have refused the parcel, and it will be returned to the sender.
RETURN_TO_SENDERYour parcel is being returned to the sender due to delivery issues.
UNSPECIFIED_EXCEPTIONThe carrier has reported an issue with your parcel, but details are unavailable.
TRACKING_EXPIREDTracking for this parcel has expired. If you are still expecting this delivery, please contact the carrier for assistance.
DUTY_NOT_PAIDThe import taxes or duties for this package havent been paid and it may be subject to disposal by customs authorities if payment is not made.
PARCEL_REDIRECTED_BY_CARRIERThe carrier has redirected your parcel due to an operational issue. The package is likely being rerouted to a nearby pickup point. You may contact the carrier for more details about the new delivery location.
DELIVERED_TO_PICKUP_POINTYour package has been delivered to the pickup point. You will be notified when its ready for collection.
UNDELIVERABLE_RETURNED_TO_SENDERThe shipment has been returned to the sender. Please contact the sender for further information.
carrier_codestring

A shipping carrier, such as fedex, dhl_express, stamps_com, etc.

carrier_idinteger

The unique ID of the carrier account that was used to create this label

status_descriptionstring

Status description

status_detail_descriptionstring

Status detail description

carrier_status_codestring

Carrier status code

carrier_detail_codestring

Carrier detail code

carrier_status_descriptionstring

carrier status description

ship_datestring date-time

An ISO 8601 string that represents a date and time.

estimated_delivery_datestring date-time

An ISO 8601 string that represents a date and time.

actual_delivery_datestring date-time

An ISO 8601 string that represents a date and time.

exception_descriptionstring

Exception description

Example response

{
  "tracking_number": "1Z932R800392060079",
  "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  "status_code": "DE",
  "carrier_code": "dhl_express",
  "status_description": "Delivered",
  "status_detail_description": "Your parcel has been successfully delivered.",
  "carrier_status_code": "1",
  "carrier_detail_code": "OT",
  "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March",
  "ship_date": "2018-09-23T15:00:00.000Z",
  "estimated_delivery_date": "2018-09-23T15:00:00.000Z",
  "actual_delivery_date": "2018-09-23T15:00:00.000Z",
  "events": [
    {
      "occurred_at": "2018-09-23T15:00:00.000Z",
      "carrier_occurred_at": "2018-09-23T15:00:00.000Z",
      "description": "Delivered, In/At Mailbox",
      "city_locality": "AUSTIN",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "CA",
      "company_name": "Stamps.com",
      "carrier_detail_code": "OT",
      "status_code": "DE",
      "status_description": "In Transit",
      "status_detail_description": "Your shipment is on its way between the carrier hubs.",
      "carrier_status_code": "1",
      "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March",
      "proof_of_delivery_url": "https://tracking-service-prod.s3.amazonaws.com/proof-of-delivery/dummy_module/0000000001/bc6dd17969bd97f24262ca73ac6ff36062aafecba25ef16d4178264bf7c0e72c.png"
    }
  ]
}

Changes

  • e998dffc42beRevision changes
    • warning

      added the new bring_your_own_label_not_supported enum value to the // response property for the response status

    • warning

      added the new bring_your_own_label_not_supported enum value to the // response property for the response status

    • warning

      added the new bring_your_own_label_not_supported enum value to the // response property for the response status

    • warning

      added the new multiple_sales_orders enum value to the // response property for the response status

    • warning

      added the new multiple_sales_orders enum value to the // response property for the response status

    • warning

      added the new multiple_sales_orders enum value to the // response property for the response status

    • warning

      added the new sales_order_link_required enum value to the // response property for the response status

    • warning

      added the new sales_order_link_required enum value to the // response property for the response status

    • warning

      added the new sales_order_link_required enum value to the // response property for the response status

  • 020f57d6f5b8Revision changes
    • breaking

      the / response's property type changed from no type to string, and format from no format to date-time for status

    • breaking

      the / response's property type changed from no type to string for status

    • breaking

      the / response's property type changed from no type to string, and format from no format to date-time for status

    • breaking

      the /// response's property type changed from no type to string for status

    • breaking

      the / response's property type changed from no type to string, and format from no format to date-time for status

    • breaking

      the / response's property type changed from no type to string for status

    • breaking

      the / response's property type changed from no type to object for status

    • breaking

      the / response's property type changed from no type to object for status

    • breaking

      the / response's property type changed from no type to object for status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the /// response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      the / response's property pattern ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$ was added for the status

    • info

      the / response's property pattern ^[a-z0-9]+(_[a-z0-9]+)*$ was added for the status

    • info

      the / response's property pattern ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$ was added for the status

    • info

      the / response's property pattern ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$ was added for the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status