Track a Package

HTTP Request

GET /v1/tracking/{identifier}?packageIdentifierType=TrackingNumber&carrier={carrier}

Summary

Shipment labels that are printed using the PB Shipping APIs are automatically tracked. This operation retrieves package status for a label.

Considerations

  1. For all carriers and services, the Tracking API works only with Production labels. To test tracking in the Sandbox environment, use a Production label. Do not use a label created in the Sandbox environment.

  2. The value taken by the carrier query parameter is case-sensitive.

  3. Set the carrier query parameter to one of the following, depending on the carrier and service:

    Set carrier to: For these carriers or services:
    USPS PB Expedited, PB Presort, and PMOD, except as noted in the next row.
    IMB First-Class Mail letters and flats that use IMb labels. Note that USPS does not guarantee reporting of tracking events for First-Class Mail. Most First-Class Mail items receive only one tracking event.
    FDR or NEWGISTICS PB Standard. The Tracking API will return tracking events for both PB Standard and USPS.
    PBI Cross-Border Delivery Service (CBDS). In addition to international tracking events, the Tracking API will also return domestic tracking events if the first-mile shipping is through Pitney Bowes, USPS, PB Standard, FedEx, or UPS.
    FedEx FedEx
    UPS

    UPS (United Parcel Service)

    Note

    UPS labels must be printed through the PB Shipping APIs to be tracked using this API call.

  4. USPS performs daily scheduled maintenance on tracking services, generally between midnight and 3 AM ET. During this time shippers might experience intermittent timeout errors if requesting USPS tracking status. We recommend that shippers not schedule jobs to obtain USPS tracking during this time period.

  5. PB Presort Only: The following considerations apply only to PB Presort:

    • The API tracks the PB Presort parcel only while the parcel is in the USPS mailstream.
    • Tracking events show up only after PB Presort uploads the Shipping Services File to USPS. Tracking information can take a while to appear.
    • If the PB Presort label used an IMb, enter only the first 20 digits of the tracking number in the trackingNumber path parameter.
  6. In addition to this API, Pitney Bowes provides the following tracking sites:

    • For services other than CBDS, buyers can track parcels through https://pitneybowes.shipment.co/track, where the buyer can enter a tracking number:

      ../_images/pitneybowes.shipment.co_track.png

      To provide the buyer a direct link to a parcel’s tracking information, append the parcel’s tracking number to the URL, as shown here, where <trackingNumber> is the parcel’s tracking number:

      https://pitneybowes.shipment.co/track/<trackingNumber>
      
    • CBDS Only: Buyers can track parcels through https://tracking.pb.com/. To provide a direct link to the parcel’s tracking information, append the parcel’s tracking number to the URL, as shown here, where <trackingNumber> is the parcel’s tracking number:

      https://tracking.pb.com/<trackingNumber>
      

Request URLs

Important: The Tracking API works only with Production labels. To test tracking in Sandbox, use a Production label.

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/tracking/{identifier}?packageIdentifierType=TrackingNumber&carrier={carrier}
Production: https://api.pitneybowes.com/shippingservices/v1/tracking/{identifier}?packageIdentifierType=TrackingNumber&carrier={carrier}

Path Parameter

Name Description
identifier

Required. The identifier for the shipment. Currently, the Tracking API requires that the identifier be the shipment’s tracking number.

For PB Presort mailpieces that use IMb labels, enter only the first 20 digits of the tracking number.

Query Parameters

Name Description
carrier

Required. The carrier, service, or label type. The value is case-sensitive. The valid values are:

  • USPS: U.S. Postal Service
  • IMB: IMb label
  • FDR: PB Standard
  • NEWGISTICS: PB Standard
  • PBI: Cross-Border Delivery Service (CBDS)
  • FedEx: FedEx
  • UPS: United Parcel Service. The UPS label must have been printed through the Shipping APIs.
packageIdentifierType

Required. Indicates the type of identifier used to reference the shipment. Currently, the Tracking API requires that shipments be identified by their tracking numbers. The valid value for this parameter is:

  • TrackingNumber

Request Header

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.

Response Elements

Name Data Type Description
packageCount Integer The number of packages tracked.
reattemptDate String If the package was not delivered the first time, this field indicates the date at the destination that the delivery was re-attempted, specified in the YYYY-MM-DD format.
reattemptTime String If the package was not delivered the first time, this field indicates the local time at the destination that delivery was re-attempted, specified in the HH:MM:SS format.
signedBy String Name of the person who signed for the package.
senderAddress Address Object This object is not used and returns null values.
requestedIdentifier String Coming Soon. This field is coming in a future release and will display the type of identifier passed in the path parameter.
clientId String Coming Soon. This field is coming in a future release.
trackingNumber String The tracking number for the shipment.
referenceNumber String Coming Soon. This field is coming in a future release and will display the value passed by the carrier as referenceNumber.
smartLabelBarcode String Coming Soon. This field is coming in a future release and will display the value for the SmartLabel® barcode for PB Standard Services.
carrier String

The carrier or label type. Possible values:

serviceName String The carrier’s name for the mail class.
serviceCode String The carrier’s code for the mail class.
estimatedDeliveryDate String The estimated date at the destination that the package will be delivered, specified in the YYYY-MM-DD format.
estimatedDeliveryTime String The estimated local time at the destination that the package will be delivered, specified in the HH:MM:SS format.
estimatedDeliveryTimeOffset String Coming Soon. This field is coming in a future release and will display the UTC offset between the local time of the estimated delivery and the time in UTC/GMT. The offset will be specified in the ±hh:mm format.
weight Number Weight of the package delivered.
weightUOM String

Unit of measure for the package’s weight. Possible values:

  • LBS: pounds
  • KGS: kilograms
dimension Object

Coming Soon. This field is coming in a future release and will display the package dimensions. The object will take the following fields, all of which take String values:

length
width
height
unitOfMeasurement

deliveryDate String The date at the destination when the package was delivered, specified in the YYYY-MM-DD format.
deliveryTime String The local time at the destination when the package was delivered, specified in the HH:MM:SS format.
deliveryTimeOffset String Coming Soon. This field is coming in a future release and will display the UTC offset between the local time of the delivery and the time in UTC/GMT. The offset will be specified in the ±hh:mm format.
deliveryProofUrl String Coming Soon. This field is coming in a future release and will display the URL to access either a picture of the delivered package or a picture of the signature confirmation.
shipDate String The date at the origin when the package was shipped, specified in the YYYY-MM-DD format.
shipTime String Coming Soon. This field is coming in a future release and will display the time at the origin when the package was shipped, specified in the hh:mm:ss format.
shipTimeOffset String Coming Soon. This field is coming in a future release and will display the UTC offset between the local time for the ship time and the time in UTC/GMT. The offset will be specified in the ±hh:mm format.
destinationAddress Address Object This object is not used and returns null values.
deliveryLocation String The location where the package was delivered.
deliveryLocationDescription String Description of where the package was delivered.
scanDetailsList Array[Scan Details Object] The events that have occurred for the parcel. The objects in this array contain scan information from the barcode on the shipment label.
currentStatus Array[Scan Details Object] Coming Soon. This field is coming in a future release and will display the current status of the parcel obtained from the barcode on the shipment label.
status String

The most recent package status. This value is also returned in the most recent packageStatus field in the scanDetailsList array. The possible values are:

  • Acceptance
  • Delivered
  • DeliveryAttempt
  • Exception
  • InTransit
  • Manifest
  • OutForDelivery
  • PickedUp
  • PickupMissed
  • ReadyForPickup
  • ReturnToSender

Coming Soon: This value is also returned in the currentStatus.packageStatus field.

updatedDate String The local date when the tracking status was posted, specified in the YYYY-MM-DD format.
updatedTime String The local time when the tracking status was posted, specified in the HH:MM:SS format.
lastPackageStatusLocation String The last location of the tracked package.

Address Object in Tracking Response

The address object contains some or all of the following fields:

Name Data Type Description
name String First and last name.
address1
address2
address3
Strings Street address or P.O. Box.
city String City or town.
stateOrProvince String State or province.
country String Two-character country code from the ISO country list.
postalCode String Postal or ZIP code.

Scan Details Object in Tracking Response

The Scan Details Object is used by the scanDetailsList array and the currentStatus object.

Name Data Type Description
l1Description String Coming Soon. This field is coming in a future release and will display the event description for buyers.
l2Description String Coming Soon. This field is coming in a future release and will display the event description for sellers.
eventDate String The date posted by the carrier for the event. Format: YYYY-MM-DD
eventTime String The time posted by the carrier for the event. Format: HH:MM:SS
eventTimeOffset String Coming Soon. This field is coming in a future release and will display the UTC offset between the local time of the event and the time in UTC/GMT. The offset will be specified in the ±hh:mm format.
trackingUrl String Coming Soon. This field is coming in a future release and will apply to CBDS. For CBDS, the field will display the final-mile carrier’s URL for tracking the package.
latitude String Coming Soon. This field is coming in a future release.
longitude String Coming Soon. This field is coming in a future release.
locationUnit String Coming Soon. This field is coming in a future release.
packageStatus String

The package status for this event. The possible values are:

  • Acceptance
  • Delivered
  • DeliveryAttempt
  • Exception
  • InTransit
  • Manifest
  • OutForDelivery
  • PickedUp
  • PickupMissed
  • ReadyForPickup
  • ReturnToSender
scanDescription String The carrier-specific description of the event.
scanType String The carrier-specific code for the event.
eventCity String The city where the event occurred.
eventStateOrProvince String The state or province where the event occurred.
postalCode String The postal code where the event occurred.
country String The country where the event occurred.

Sample Requests and Responses

See the following examples:

USPS Sample Request and Response

USPS Sample Tracking Request
curl -X GET ../v1/tracking/9405509898641500000146?packageIdentifierType=TrackingNumber&carrier=USPS \
-H "Authorization: Bearer <oauth_token>"
USPS Sample Tracking Response
{
    "packageCount": 1,
    "carrier": "USPS",
    "trackingNumber": "9405509898641500000146",
    "status": "Acceptance",
    "updatedDate": "2019-10-08",
    "updatedTime": "08:26:00",
    "lastPackageStatusLocation": "NIAGARA FALLS,NY,14304",
    "shipDate": "2019-10-02 23:30:42",
    "estimatedDeliveryDate": "2019-10-10",
    "estimatedDeliveryTime": "00:00:00",
    "deliveryDate": null,
    "deliveryTime": null,
    "deliveryLocation": null,
    "deliveryLocationDescription": null,
    "signedBy": null,
    "serviceCode": "055",
    "serviceName": "Priority Mail",
    "weight": 0,
    "weightUOM": "KGS",
    "reattemptDate": null,
    "reattemptTime": null,
    "destinationAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "senderAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "scanDetailsList": [ {
        "eventDate": "2019-10-08",
        "eventTime": "08:26:00",
        "eventCity": "NIAGARA FALLS",
        "eventStateOrProvince": "NY",
        "postalCode": "14304",
        "country": null,
        "scanType": "03",
        "scanDescription": "USPS in possession of item",
        "packageStatus": "Acceptance"
    }, { ... }, ... ]
}

PB Standard Sample Request and Response

PB Standard Sample Tracking Request
curl -X GET ../v1/tracking/42020832926188270533936567018?packageIdentifierType=TrackingNumber&carrier=NEWGISTICS \
-H "Authorization: Bearer <oauth_token>"
PB Standard Sample Tracking Response
{
    "packageCount": 1,
    "carrier": "NEWGISTICS",
    "trackingNumber": "42020832926188270533936567018",
    "status": "Delivered",
    "updatedDate": "2019-09-14",
    "updatedTime": "11:53:00",
    "lastPackageStatusLocation": "OLNEY,MD,20832",
    "shipDate": null,
    "estimatedDeliveryDate": null,
    "estimatedDeliveryTime": null,
    "deliveryDate": "2019-09-14",
    "deliveryTime": "11:53:00",
    "deliveryLocation": "OLNEY",
    "deliveryLocationDescription": "Delivered",
    "signedBy": null,
    "serviceCode": null,
    "serviceName": null,
    "weight": 3.546,
    "weightUOM": "KGS",
    "reattemptDate": null,
    "reattemptTime": null,
    "destinationAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "senderAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "scanDetailsList": [ {
        "eventDate": "2019-09-14",
        "eventTime": "11:53:00",
        "eventCity": "OLNEY",
        "eventStateOrProvince": "MD",
        "postalCode": "20832",
        "country": null,
        "scanType": "DEL",
        "scanDescription": "Delivered",
        "packageStatus": "Delivered"
    }, { ... }, ... ]
}

CBDS Sample Request and Response

CBDS Sample Tracking Request
https://api-sandbox.pitneybowes.com/shippingservices/v1/tracking/PBXCB000000003456789?packageIdentifierType=TrackingNumber&carrier=PBI \
-H "Authorization: Bearer <oauth_token>"
CBDS Sample Tracking Response
{
    "packageCount": 1,
    "carrier": "PBI",
    "trackingNumber": "PBXCB000000003456789",
    "status": "Delivered",
    "updatedDate": "2019-10-03",
    "updatedTime": "19:25:07",
    "lastPackageStatusLocation": "EDMONTON,AB,T6R3H7",
    "shipDate": null,
    "estimatedDeliveryDate": null,
    "estimatedDeliveryTime": null,
    "deliveryDate": "2019-10-03",
    "deliveryTime": "19:25:07",
    "deliveryLocation": "EDMONTON",
    "deliveryLocationDescription": "Delivered - FRONT PORCH",
    "signedBy": null,
    "serviceCode": null,
    "serviceName": "Pitney Bowes Expedited Parcel Service",
    "weight": 3,
    "weightUOM": "LBS",
    "reattemptDate": null,
    "reattemptTime": null,
    "destinationAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "senderAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "scanDetailsList": [ {
        "eventDate": "2019-10-03",
        "eventTime": "19:25:07",
        "eventCity": "EDMONTON",
        "eventStateOrProvince": "AB",
        "postalCode": "T6R3H7",
        "country": "CA",
        "scanType": "DLD",
        "scanDescription": "Delivered - FRONT PORCH",
        "packageStatus": "Delivered"
    }, { ... }, ... ]
}

FedEx Sample Request and Response

FedEx Sample Tracking Request
curl -X GET ../v1/tracking/771234567890?packageIdentifierType=TrackingNumber&carrier=FedEx \
-H "Authorization: Bearer <oauth_token>"
FedEx Sample Tracking Response
{
    "packageCount": 1,
    "carrier": "FedEx",
    "trackingNumber": "771234567890",
    "status": "Delivered",
    "updatedDate": "2020-01-10",
    "updatedTime": "15:06:00",
    "lastPackageStatusLocation": "ADVANCE,NC,27006",
    "shipDate": null,
    "estimatedDeliveryDate": null,
    "estimatedDeliveryTime": null,
    "deliveryDate": "2020-01-10",
    "deliveryTime": "15:06:00",
    "deliveryLocation": "ADVANCE",
    "deliveryLocationDescription": "Delivered - Left at front door. Package delivered to recipient address - release authorized",
    "signedBy": null,
    "serviceCode": null,
    "serviceName": "FedEx 2Day",
    "weight": 0,
    "weightUOM": "KGS",
    "reattemptDate": null,
    "reattemptTime": null,
    "destinationAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "senderAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "scanDetailsList": [ {
        "eventDate": "2020-01-10",
        "eventTime": "15:06:00",
        "eventCity": "ADVANCE",
        "eventStateOrProvince": "NC",
        "postalCode": "27006",
        "country": "US",
        "scanType": "DL",
        "scanDescription": "Delivered - Left at front door. Package delivered to recipient address - release authorized",
        "packageStatus": "Delivered"
    }, { ... }, ... ]
}

UPS Sample Request and Response

Note

UPS labels must be printed through the PB Shipping APIs to be tracked through this API call.

UPS Sample Tracking Request
curl -X GET ../v1/tracking/1Z0927XA0340576884?packageIdentifierType=TrackingNumber&carrier=UPS \
-H "Authorization: Bearer <oauth_token>"
UPS Sample Tracking Response
{
    "packageCount": 1,
    "carrier": "UPS",
    "trackingNumber": "1Z0927XA0340576884",
    "status": "Delivered",
    "updatedDate": "2019-04-11",
    "updatedTime": "13:24:51",
    "shipDate": null,
    "estimatedDeliveryDate": "2019-04-11",
    "estimatedDeliveryTime": "00:00:00",
    "deliveryDate": "2019-04-11",
    "deliveryTime": "13:24:51",
    "deliveryLocation": "ORANGE",
    "deliveryLocationDescription": "Delivered",
    "signedBy": null,
    "weight": 2.3,
    "weightUOM": null,
    "reattemptDate": null,
    "reattemptTime": null,
    "destinationAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "senderAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": null,
        "stateOrProvince": null,
        "postalCode": null,
        "country": null
    },
    "scanDetailsList": [ {
        "eventDate": "2019-04-11",
        "eventTime": "13:24:51",
        "eventCity": "ORANGE",
        "eventStateOrProvince": "CT",
        "postalCode": "06477",
        "country": "US",
        "scanType": "D",
        "scanDescription": "Delivered",
        "packageStatus": "Delivered"
    }, { ... }, ... ]
}

Error Codes

This API uses the PB-TRKPKG-ERR Errors error codes.

For a list of all PB Shipping APIs error codes, please see Error Codes.