Tracking
Every order has a status field which will tell you how far along the order is in the delivery pipeline. The status of an order can be one of the values listed below.
| Status | Description |
|---|---|
ready | The order was created successfully. This order will be printed on the date specified in its sendDate property. By default, sendDate is set to the next day however this can be overwritten and specified for a later date. |
printing | The order has been given to a printer and will be processed within our SLA (2 business days). |
processed_for_delivery | The order has been handed off to the local postal service. |
completed | The order has most likely been delivered. With this status, it is not guaranteed that the order has been delivered as this is an approximation. |
cancelled | The order has been cancelled and it will never be sent out. |
Check out our guides for how to view the tracking status of an order on the dashboard and via the API.
Tracking Number
Soon after an order has been processed, a trackingNumber property is added to the order. You can use this tracking number to track your order via USPS tracking. If you do not see this tracking number on your order within several days of your order being processed, please reach out to our support team at [email protected].
Intelligent-Mail Tracking
Live orders destined for the US will have an imbStatus field added to them once they are processed at a USPS facility. There can sometimes be a delay in this data which can reach as high as 5 calendar days. See below for the possible imbStatus values.
IMB refers Intelligent Mail Barcode which is used to track mailings.
| Status | Description |
|---|---|
entered_mail_stream | The order has entered a USPS facility. |
out_for_delivery | The order has been processed at its final USPS facility and will be delivered within a day. |
returned_to_sender | The order has been returned to the sender. |
Check out our guides for how to view the IMB status of an order on the dashboard and via the API.
Note: This feature is only available for live orders destined for the US.
Certified and Registered Mail
For Letters and Cheques, you have the ability to send certified/registered mail including certified mail with return receipts. These options will be applied as an extra service on orders. If an order is certified or registered mail it will be shown in the extraService field on the order. See below for a list of possible extra service values.
| Value | Description |
|---|---|
certified | Send the order as certified mail |
certified_return_receipt | Send the order as certified mail with a return receipt |
registered | Send the order as registered mail |
Note: This is currently only available for US mailings and additional charges will apply for these mailings.
Check out our guides for how to create and verify if an order is certified/registered mail on the dashboard and via the API.
Using Webhooks to Handle Status Updates
Webhooks can be used to notify your application when events occur in PostGrid. These webhooks for example, can be used to send you a notification when an order has been processed for delivery. Listed below are the possible event types you can listen for on a webhook.
| Name | Description |
|---|---|
letter.created | Triggered when a letter is created |
letter.updated | Triggered when a letter is updated |
postcard.created | Triggered when a postcard is created |
postcard.updated | Triggered when a postcard is updated |
cheque.created | Triggered when a cheque is created |
cheque.updated | Triggered when a cheque is updated |
self_mailer.created | Triggered when a self mailer is created |
self_mailer.updated | Triggered when a self mailer is updated |
return_envelope_order.created | Triggered when a return envelope order is created |
return_envelope_order.updated | Triggered when a return envelope order is updated |
If you wanted to listen for when an order's status has updated, you could listen for the updated events on orders. For example, you could listen for the letter.updated, postcard.updated, and cheque.updated events to receive a notification when any of these collaterals have been updated. If you are only concerned about letters, you would only need listen for the letter.updated event. You can listen to as many or as little events as you need.
Check out our guides for how to set up webhooks to listen for order changes on the dashboard and via the API. For more information on how PostGrid handles webhooks, checkout our webhook guide.