Get detailed tracking information about orders sent via certified/registered mail.
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.
How to monitor your orders via the dashboard
PostGrid will automatically surface the latest carrier tracking status on the order details page:
Note how it shows "In Transit" as well as the last message received by the carrier. You can also expand the "Raw Data" section and click the copy button next to the value of the carrierTracking field and paste it into a JSON formatter (e.g. https://jsonformatter.org) to see the detailed interim tracking updates provided by our carrier.