NOTE: This feature is currently in beta and the schema of the responses discussed here is subject to change.

Whenever you send an order (letter, check, etc) with extra services such as Certified Mail, PostGrid eventually assigns a tracking number to it. This is visible in the dashboard/API response via a trackingNumberfield. Once the trackingNumber is connected, PostGrid surfaces updates from the carrier regarding the detailed tracking status of the order. We update this tracking information on an hourly basis, and you can use this to get the exact status of the order's delivery (as provided to us by the carrier).

If you're a dashboard user and you want to see how you can use this feature, you can skip to the "How to monitor your orders via the dashboard" section below.

This is not available by default. You can contact [email protected] to enable this feature for your organization.

Carrier Tracking Schema

The carrier tracking status and updates are surfaced via a carrierTracking field in the API. This is the schema of that field:

Name	Type	Description
status	string	See "Carrier Tracking Status" below.
statusDetail	string	See "Carrier Tracking Status Detail" below.
estDeliveryDate	string or null	An ISO-8601 timestamp indicating the date on which this order may delivery (if available).
signedBy	string or null	The name of the person who signed for the package (if available).
carrier	string	The name of the carrier for this order.
trackingUpdates	Carrier Tracking Update array	See below for a schema of a "Carrier Tracking Update".

Carrier Tracking Update Schema

In addition to surfacing the current carrier status, we surface all the updates we have received from the carrier. This is the schema of these updates:

Name	Type	Description
message	string	A message describing the status at the point of this update. This is provided directly by the carrier and is human-readable.
status	string	See "Carrier Tracking Status" below.
createdAt	string	An ISO-8601 timestamp indicating when this update occurred.
source	string	The carrier who provided this update.
trackingLocation	object or null	An object containing an optional `city`, `provinceOrState`, `countryCode` and `postalOrZip` field indicating where the order has reached at the time of this update.

Carrier Tracking Status

The status field can have the following values:

Value	Description
`unknown`	The carrier did not provide us with an appropriate status for this order. Contact the carrier.
`pre_transit`	The order is on its way to the carrier.
`in_transit`	The order is on the way to its destination.
`out_for_delivery`	The order has left its last facility and will be delivered soon.
`available_for_pickup`	The order is available for pickup at the carrier's facility.
`delivered`	The order has been delivered.
`return_to_sender`	The order was not delivered and is on its way back to the sender.
`failure`	The delivery of this order has failed. Contact the carrier.
`cancelled`	The order's delivery was cancelled.
`error`	An unknown error has occurred while shipping the order. Contact the carrier.

Carrier Tracking Status Detail

The statusDetail field provides a more detailed status of the order from the perspective of the carrier. Here are the values it can have:

Value	Description
`address_correction`	The destination address of this order was corrected.
`arrived_at_destination`	The order has arrived at its destination.
`arrived_at_facility`	The order has arrived at the carrier's facility.
`arrived_at_pickup_location`	The order has arrived at the carrier's pickup location.
`awaiting_information`	The delivery of the order is pending further info.
`cancelled`	The delivery of this order has been cancelled.
`damaged`	This order was damaged in transit.
`delayed`	The delivery of this order has been delayed.
`delivery_exception`	Delivery of the order is temporarily delayed due to unavoidable circumstances.
`departed_facility`	The order has departed the carrier's facility.
`depared_origin_facility`	The order has departed its origin facility.
`expired`	The tracking of this shipment has expired.
`failure`	The order failed to be delivered.
`held`	The order is being held by the carrier.
`in_transit`	The order is on its way to the destination.
`label_created`	A shipping label has been created for this order.
`lost`	The order was lost by the carrier. Contact the carrier to follow up.
`missorted`	The order was sent to the wrong facility and will be rerouted.
`out_for_delivery`	The order has left its final facility and is going to be delivered soon.
`received_at_destination_facility`	The order has been received at the facility closest to its destination.
`received_at_origin_facility`	The order has been received at its origin facility.
`refused`	The consignee of the order refused to receive it. Contact the recipient and resend your order.
`return`	The order has been returned.
`status_update`	Refer to the main `status` field.
`transferred_to_destination_carrier`	The order has been handed off to a carrier near the destination.
`transit_exception`	An unanticipated delay has occurred in the delivery of your order.
`unknown`	Contact the carrier.
`weather_delay`	The delivery of your order has been delayed due to weather concerns.

How to monitor your orders via the API

The carrierTracking field is not available until orders are assigned a tracking number and an update from the carrier is received. As such, the best way to monitor your orders is to look at the PostGrid-provided status until the carrierTracking field is populated in responses from the API. The regular status provides the most up-to-date information about your order until it has been handed off to the carrier. You can look at Tracking Your Orders for more information about the regular tracking we provide.

Once your order has received carrier tracking data, you can look at the carrierTracking.status to get a summary of the status of your order. Note that you can either poll our order GET endpoints or wait for a relevant *.updated webhook event (where * is any of letter,postcard,cheque, or self_mailer) to be notified of when the carrier tracking status is added/updated.

In addition, once the carrier notifies us the order has been delivered (i.e. carrierTracking.status is one of the terminal values such as delivered), PostGrid automatically updates the regular (PostGrid-managed) status field to completed.