Track a Package

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

  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. In addition to this API, a parcel can be tracked through https://pitneybowes.shipment.co/track where a buyer can enter a tracking number, as shown here:

    ../_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 above URL, as shown here:

    https://pitneybowes.shipment.co/track/<trackingNumber>

  3. See also the additional considerations specific to your carrier: USPS, PB Standard, Presort, CBDS, FedEx, UPS

USPS Considerations

The following additional considerations apply to USPS:

  • 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.
  • To track a letter or flat that uses an IMb label, set the carrier query parameter to IMB. The value is case-sensitive. Note that USPS does not guarantee reporting of tracking events for First-Class Mail. Most First-Class Mail items receive only one tracking event.

PB Standard Considerations

The following additional considerations apply to PB Standard:

  • The API returns both PB Standard and USPS tracking events for the shipment.
  • Set the carrier query parameter to either FDR or NEWGISTICS. Both values indicate PB Standard as the carrier. The values are case-sensitive.

PB Presort Considerations

The following additional considerations apply to PB Presort:

  • The API tracks the parcel only while the parcel is in the USPS mailstream. Set the carrier query parameter to USPS. The value is case-sensitive.
  • When tracking mail that uses an IMb label, use only the first 20 digits of the tracking number for the trackingNumber path parameter. Note that USPS does not guarantee reporting of tracking events for First-Class Mail. Most First-Class Mail items receive only one tracking event.

Cross-Border (CBDS) Considerations

The following additional considerations apply to CBDS:

  • Set the carrier query parameter to PBI. The value is case-sensitive.
  • In addition to international tracking events, the API returns domestic tracking events if first-mile shipping is through Pitney Bowes, USPS, PB Standard, FedEx, or UPS.
  • Parcels can also be tracked through https://tracking.pb.com/. (Do not use https://pitneybowes.shipment.co/track.) To provide a direct link to the parcel’s tracking information, append the parcel’s tracking number to https://tracking.pb.com/, as shown here: https://tracking.pb.com/<trackingNumber>

FedEx Considerations

The following additional considerations apply to FedEx:

  • Set the carrier query parameter to FedEx. The value is case-sensitive.

UPS Considerations

The following additional considerations apply to UPS:

  • Set the carrier query parameter to UPS. The value is case-sensitive.
  • UPS labels must be printed through the PB Shipping APIs to 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.

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

Query Parameters

Name Description
carrier

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

packageIdentifierType

Required. Indicates the shipment is identified by its tracking number. The valid value is:

  • 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

The carrier, service or label type. Possible values:

trackingNumber String The tracking number for the shipment.
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
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.
shipDate String The date at the origin that the package was shipped, specified in the YYYY-MM-DD format.
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.
deliveryDate String The actual date at the destination that the package was delivered, specified in the YYYY-MM-DD format.
deliveryTime String The actual local time at the destination that the package was delivered, specified in the HH:MM:SS format.
deliveryLocation String The location where the package was delivered.
deliveryLocationDescription String Description of where the package was delivered.
signedBy String Name of the person who signed for the package.
serviceCode String The code that corresponds to the mail class.
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 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.
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 code for the scan event. For USPS and PB Standard, see Carrier Scan Event Codes. For other carriers, see your carrier’s documentation.
    scanDescription String

The carrier-specific description of the scan event. For USPS and PB Standard, see Carrier Scan Event Codes. For other carriers, see your carrier’s documentation.

Note: For PB Standard, if this field has a value of Picked Up by Shipping Partner, USPS Awaiting Item, then the package has been picked up by PB Standard but has not yet entered the USPS mailstream.

    packageStatus String The package status. The possible values are specific to the carrier or service.

Response Elements: Address Object

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

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

PB Standard Sample Tracking Request
curl -X GET ../v1/tracking/42020832926188270533936567018?packageIdentifierType=TrackingNumber&carrier=NEWGISTICS \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"
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

CBDS 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"
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

FedEx Sample Tracking Request
curl -X GET ../v1/tracking/771234567890?packageIdentifierType=TrackingNumber&carrier=FedEx \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"
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

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

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