Tracking

HTTP Request

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

Summary

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

Things to Consider

This section contains the following:

General Considerations

  • The Tracking API works only with production parcels. To test tracking in the Sandbox environment, use a production label. Do not use a label created in the Sandbox environment.

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.
  • Coming soon to the Sandbox environment: 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

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.

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
  • UPS - Available only in Sandbox
  • IMB - Coming soon to Sandbox - tracks an IMb 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
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. The response populates the fields with null values, as shown in the response samples 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 and Responses

See the following examples:

  • USPS
  • UPS (Available only in Sandbox)

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

Available only in Sandbox

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

UPS Sample Response

Available only in Sandbox

{
    "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 Complete Shipping APIs error codes, see Error Codes.