Tracking

HTTP Request

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

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

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

  2. For a Newgistics shipment, this API tracks the parcel only while the parcel is in the USPS mailstream.

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

  3. Letters and flats that use IMbs are not trackable through the Tracking API at this time.

  4. The Tracking API works only with Production parcels. To test tracking in the Sandbox environment, use a live USPS label. Do not use a label created in the Sandbox environment.

Request URIs

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

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

Path Parameters

Name Data Type Description
trackingNumber String Required. The tracking number for the shipment.

Query Parameters

Name Data Type Description
carrier String

Required. Valid value:

  • USPS
packageIdentifierType String

Required. Valid value:

  • TrackingNumber

Request Header

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

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 Date Date in YYYY-MM-DD format indicating when the tracking status was posted.
updatedTime Time Time in HH:MM:SS format indicating when the tracking status was posted.
shipDate Date Date in YYYY-MM-DD format indicating when the package was shipped.
estimatedDeliveryDate Date Date in YYYY-MM-DD format indicating when the package will be delivered.
estimatedDeiverytTime Time Time in HH:MM:SS format indicating when the package will be delivered.
deliveryDate Date Date in YYYY-MM-DD format indicating when the package was delivered.
deliveryTime Time 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 Time 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 Elements The destination address.
senderAddress Object, see Address Elements Sender Address.
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 Elements

Name Data Type Description
name String First and last name.
address1
address2
address3
Strings The lines in the 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 Request

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

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": "DECATUR",
        "stateOrProvince": "IN",
        "postalCode": 46733,
        "country": null
    },
    "senderAddress": {
        "name": null,
        "address1": null,
        "address2": null,
        "address3": null,
        "city": "SHELTON",
        "stateOrProvince": "CT",
        "postalCode": "06484",
        "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"
    }, ... ]
}

Error Codes

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