Order status lifecycle

Understanding the order lifecycle saves a lot of head-scratching — especially around customer e-mails and invoicing integrations, which often assume the standard WooCommerce flow. With this plugin the flow looks like this:

The lifecycle

1. Processing — the customer has paid (or placed a cash-on-delivery order). This status is the trigger: the plugin sends the order to the Messenger API.
2. Messenger — the order was successfully handed over to Messenger. This is the plugin’s own custom status. Since version 2.7.0 it counts as a paid status, so revenue reports and integrations that check $order->is_paid() treat it correctly.
3. Completed — set automatically when Messenger reports the shipment as delivered (via the tracking webhook). Not before.
4. Failed — set when sending to the Messenger API fails, or when Messenger reports the shipment as permanently undeliverable.

Statuses in between (courier assigned, picked up, delivery attempt failed…) don’t change the order status — they are added as order notes, so the whole journey is visible on the order detail.

The tracking webhook is what moves the status

Steps 3 and 4 only happen if Messenger has your tracking webhook registered — the URL shown at the top of the plugin settings (/wp-json/kbnt-messenger/v1/trackingstates/). Without it, orders stay in the Messenger status forever. See Before you start.

What this means for customer e-mails

• WooCommerce sends no e-mail for the custom Messenger status — the customer isn’t notified when the parcel is handed to the courier.
• The “Completed order” e-mail goes out only after delivery — so putting a tracking link in that template makes little sense; the parcel is already in the customer’s hands.
• Messenger notifies the recipient on its own: on the delivery day they send an SMS with a time window and the courier’s phone number (using the phone the plugin passes along). Since version 2.7.0 the plugin also passes the customer’s e-mail address to Messenger.

If you still want the tracking link in an e-mail, see the FAQ for a ready-made snippet.

What this means for invoicing and other integrations

Anything that reacts to Completed fires after delivery — often days after payment. For invoicing plugins (Toret Fakturoid and similar), I recommend binding invoice creation to the Processing status instead. Integrations that check whether the order is paid work correctly from version 2.7.0 onward, since the Messenger status is registered among the paid statuses. More in the FAQ.

Where the tracking data lives

After a successful handover, the plugin shows the Messenger ID and a tracking link on the order detail in the admin, and stores them in order meta:

Meta key	Content
_kbnt_messenger_order_id	Messenger’s shipment ID
_kbnt_messenger_tracking_code	tracking code
_kbnt_messenger_tracking_url	tracking URL

These are handy for snippets and custom integrations — see Developer filters and actions.