Tracking

HTTP Request

GET /v1/tracking/{trackingNumber}?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

USPS Considerations

  • 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.
  • IMb tracking: To track a letter or flat that uses an IMb label, set the carrier query parameter to IMB when issuing this API call. IMB must be all caps.

Newgistics Consideration

  • To track the Newgistics shipment, set the carrier query parameter to NEWGISTICS. The API returns both Newgistics and USPS tracking events for the shipment.

PB Presort Considerations

  • For a PB Presort shipment, this API tracks the parcel only while the parcel is in the USPS mailstream. Set the carrier query parameter to USPS.
  • When tracking mail that uses an IMb label, use only the first 20 digits of the tracking number for the trackingNumber path parameter.

PB Cross-Border Considerations

  • To track a PB Cross-Border shipment, set the carrier query parameter to PBI.
  • In addition to international tracking events, the API returns domestic tracking events if the first-mile shipping is through Pitney Bowes, USPS, Newgistics, FedEx, or UPS.
  • Parcels can also be tracked through the URL https://tracking.pb.com/<trackingNumber> by replacing <trackingNumber> with the parcel tracking number

UPS Considerations

  • UPS labels printed through the PB Shipping APIs can be tracked using this API call.
  • To track a UPS shipment, set the carrier query parameter to UPS.

Request URIs

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/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier={carrier}
Production: https://api.pitneybowes.com/shippingservices/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier={carrier}

Path Parameter

Name Description
trackingNumber

Required. The tracking number for the shipment.

For PB Presort mailpieces that use IMb labels, see the PB Presort Considerations.

Query Parameters

Name Description
carrier

Required. Valid values:

  • USPS: U.S. Postal Service label
  • IMB: IMb label
  • NEWGISTICS: Newgistics label
  • PBI: PB Cross-Border shipment
  • UPS: United Parcel Service label
packageIdentifierType

Required. Valid value:

  • TrackingNumber

Request Header

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Response Elements

Name Data Type Description
packageCount String The number of packages tracked by this number.
carrier String

Carrier name. Possible values:

  • USPS: U.S. Postal Service label
  • IMB: IMb label
  • NEWGISTICS: Newgistics label
  • PBI: PB Cross-Border shipment
  • UPS: United Parcel Service label
trackingNumber String The tracking number for the shipment.
referenceNumber String Reference Number for the shipment.
status String

Most recent Package Status.

Possible values are:

  • In Transit
  • Delivered
  • Manifest
updatedDate String Date in YYYY-MM-DD format indicating when the tracking status was posted.
updatedTime String Time in HH:MM:SS format indicating when the tracking status was posted.
lastPackageStatusLocation String  
shipDate String Date in YYYY-MM-DD format indicating when the package was shipped.
estimatedDeliveryDate String Date in YYYY-MM-DD format indicating when the package will be delivered.
estimatedDeliveryTime String Time in HH:MM:SS format indicating when the package will be delivered.
deliveryDate String Date in YYYY-MM-DD format indicating when the package was delivered.
deliveryTime String Time in HH:MM:SS format indicating when the package was delivered.
deliveryLocation String Delivery location.
deliveryLocationDescription String Description of where the package was delivered.
signedBy String Name of the person who signed for the package.
serviceCode String  
serviceName String The carrier service.
weight String Weight of the package delivered.
weightUOM String Unit of measure for the package’s weight. This will be LBS for pounds and KGS for Kilograms.
reattemptDate String If the package was not delivered the first time, this field will indicate the date in YYYY-MM-DD format that the package was re-attempted to be delivered.
reattemptTime String If the package was not delivered the first time, this field will indicate the time in HH:MM:SS format that the package was re-attempted to be delivered.
destinationAddress Object. See Address Object below. The destination address. These fields are populated by null values.
senderAddress Object. See Address Object below. Sender Address. These fields are populated by null values.
scanDetailsList Array[Object] Scan information from the barcode on the shipment label.
    eventDate String The event date received from the carrier. Format: YYYY-MM-DD
    eventTime String The event time received from the carrier. Format: HH:MM:SS
    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.
    scanType String The carrier-specific type of scan event.
    ScanDescription String

The carrier-specific description of the scan event.

Note: For Newgistics, if this field has a value of:

Picked Up by Shipping Partner, USPS Awaiting Item

Then the package has been picked up by Newgistics but has not yet entered the USPS mailstream.

    packageStatus String The carrier-specific package status.

Address Object Returned in the Tracking Response

The Address Object appears in the destinationAddress and senderAddress fields in the response. The object contains the following elements populated with null values, as shown in the response examples below.

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
postalCode String Postal or ZIP code
country String Two-character country code from the ISO country list

Sample Requests

See the following examples:

USPS Sample Tracking Request

curl -X GET ../v1/tracking/9405509898641500000146?packageIdentifierType=TrackingNumber&carrier=USPS \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"

USPS Sample 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"
    }, { ... }, ... ]
}

Newgistics Sample Tracking Request

curl -X GET ../v1/tracking/42020832926188270533936567018?packageIdentifierType=TrackingNumber&carrier=NEWGISTICS \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"

Newgistics Sample 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"
    }, { ... }, ... ]
}

PB Cross-Border Sample Tracking Request

https://api-sandbox.pitneybowes.com/shippingservices/v1/tracking/PBXCB000000003456789?packageIdentifierType=TrackingNumber&carrier=PBI \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"

PB Cross-Border Sample 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"
    }, { ... }, ... ]
}

UPS Sample Tracking Request

curl -X GET ../v1/tracking/1Z0927XA0340576884?packageIdentifierType=TrackingNumber&carrier=UPS \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"

UPS Sample 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

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