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.

Things to Consider

USPS Considerations

The following considerations apply to USPS® shipments:

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

    For example:

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

Newgistics Consideration

The following consideration applies to Newgistics® shipments:

  • For a Newgistics shipment, this API tracks the parcel only while the parcel is in the USPS mailstream. Set the carrier query parameter to USPS.

    Note: To receive notifications for Newgistics transit triggers, see Create a Newgistics Shipment.

PB Presort Consideration

The following consideration applies to PB Presort shipments:

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

PB Cross-Border Considerations

The following considerations apply to PB Cross-Border shipments:

  • The API can be used to track an international parcel even if first-mile label is not printed through the PB Shipping APIs.
  • For an international parcel where Pitney Bowes is not responsible for the first mile, the domestic tracking is provided if the first-mile shipping is through USPS, Newgistics, FedEx, or UPS.
  • Parcels can also be tracked through https://tracking.pb.com/<trackingNumber> by replacing <trackingNumber> with the parcel tracking number

UPS Consideration

The following consideration applies to UPS® shipments:

  • UPS labels printed through the PB Shipping APIs can be tracked using this API call.

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.

Query Parameters

Name Description
carrier

Required. Valid values:

  • USPS - U.S. Postal Service label
  • IMB - IMb label
  • UPS - United Parcel Service label
  • PBI - PB Cross-Border shipment
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
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.
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.
weight String Weight of the package delivered.
weightOUM 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 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": "Manifest",
    "updatedDate": "2018-01-19",
    "updatedTime": "17:48:00",
    "shipDate": "2018-01-19",
    "estimatedDeliveryDate": null,
    "estimatedDeliveryTime": null,
    "deliveryDate": null,
    "deliveryTime": null,
    "deliveryLocation": null,
    "deliveryLocationDescription": null,
    "signedBy": null,
    "weight": 0,
    "weightOUM": 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": "2018-01-19",
        "eventTime": "17:48:00",
        "eventCity": "SHELTON",
        "eventStateOrProvince": "CT",
        "postalCode": "06484",
        "country": null,
        "scanType": "GX",
        "scanDescription": "Shipping Label Created",
        "packageStatus": "Manifest"
    }, { ... }, ... ]
}

UPS Sample 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,
    "weightOUM": 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.