Customer notifications: what each one does and when it sends
Every automatic email and SMS TCMS can send your customers, what triggers each one, and who receives it.
TCMS can email or SMS your customers automatically as an order moves. This article lists every customer notification, explains exactly what triggers it, who can receive it, and which fields you can use in the message.
Where to find the settings: Dispatcher portal, then Manage > Customers > Notifications.
If you cannot see the Notifications menu item, customer notifications are not switched on for your account. Contact Yojee support.
How the settings page works
The page has two tables, SMS and Email. Both list the same events. You switch each one on or off independently, so you can send an email but not an SMS for the same event.
Each row has up to three recipient columns.
- Sender. The customer the order belongs to. For order creation notifications this is the user who placed the order.
- Pickup Person. The contact recorded on the pickup leg of the order (pickup contact name, email and phone).
- Dropoff Person. The contact recorded on the dropoff leg of the order.
Three things to know about recipients.
- A notification only sends if that contact has the right detail on the order. No email address on the dropoff contact means no dropoff email, even with the box ticked.
- If an order has several items with different pickup or dropoff contacts, each contact is notified.
- The Pickup Person and Dropoff Person columns are optional features. If you cannot see them, they are not enabled for your account.
Editing the message. The pencil icon on a row opens the template editor, where you can change the wording and insert merge fields. Template editing requires white-labelling on your account, and email template editing is a separate permission again. If the pencil is missing, ask Yojee support to enable it.
Quick reference
| Notification | Fires when | Sender | Pickup Person | Dropoff Person | SMS | |
|---|---|---|---|---|---|---|
| Order Accepted (Single Order) | An order is created and is complete enough to dispatch | Yes | Yes | Yes | Yes | Yes |
| Order Accepted (Batch) | Each valid order inside a batch upload, and each order a partner accepts by transfer | Yes | Yes | Yes | Yes | Yes |
| Batch Order Created | Once per batch upload | Yes | No | No | Yes | Yes |
| Order Cancelled | A whole order is cancelled | Yes | Yes | Yes | Yes | Yes |
| Order Item Cancelled | A single item on an order is cancelled | Yes | Yes | Yes | Yes | Yes |
| Driver Accepted Task Group | A driver accepts the job, or a driver is assigned with auto-accept on | Yes | Yes | Yes | Yes | Yes |
| Driver Reassigned | A different driver accepts a job that was already assigned to someone else | Yes | Yes | Yes | Yes | Yes |
| Pickup Completed | A pickup task is completed | Yes | Yes | Yes | Yes | Yes |
| Dropoff Completed | A dropoff task is completed | Yes | Yes | Yes | Yes | Yes |
| Dropoff Failed | A task is reported as failed | Yes | Yes | Yes | Yes | Yes |
| Order Completed | The last outstanding task on the order is completed | Yes | Yes | Yes | Yes | Yes |
Account notifications (Sender Created, Dispatcher Created, Worker Approved, Partner Invitation Request) work differently. See Account notifications below.
Notification by notification
Order Accepted (Single Order)
What it is. Confirms to the customer that their order is in the system.
Triggered when an order is created and lands in Accepted status. That covers an order raised in the dispatcher portal, an order placed by a customer in the sender portal, and an order received through the order API.
Important. An order that is created but not yet complete, for example one missing required details and sitting in Created status, does not send this notification. It sends nothing until the order becomes Accepted.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{waybill_url}.
Order Accepted (Batch)
What it is. The same confirmation, for orders that arrive as part of a batch.
Triggered when either of these happens:
- a batch or multi-order upload completes, once per valid order in the batch
- a partner company accepts an order you transferred to them, and a new order is created on their side
Important. Batch uploads use this event, not Order Accepted (Single Order). If you send batches and only have the single-order row ticked, your customers will not be notified. Tick both.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{waybill_url}.
Batch Order Created
What it is. One summary message for a whole batch, rather than one per order.
Triggered when a batch upload completes. Sends once per batch, not once per order.
Can be sent to Sender only. This event has no Pickup Person or Dropoff Person option, because a batch has no single pickup or dropoff contact.
Channels. Email and SMS. The SMS row only appears if batch IDs are enabled on your account.
Merge fields. Core set, plus %{batch_id} and %{waybill_url}. Order-level fields such as %{order_number} and %{tracking_url} are not available here, because the message covers many orders.
Order Cancelled
What it is. Tells the customer the order will not proceed.
Triggered when any of these happens:
- someone cancels the order in the dispatcher portal or through the API
- a customer cancels their own order in the sender portal, where that permission is enabled
- the last remaining items on an order are cancelled, so the order itself becomes cancelled
- an order you transferred to a partner is withdrawn
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set and order reference set.
Order Item Cancelled
What it is. Tells the customer that one item has been cancelled while the rest of the order continues.
Triggered when an individual item is cancelled, whether by a dispatcher, by the customer in the sender portal, or as part of a transfer withdrawal. One message per cancelled item.
Important. Cancelling a whole order also cancels its items, so a full cancellation can produce both an Order Cancelled message and an Order Item Cancelled message per item. If that is too noisy, pick one of the two rows rather than both.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{tracking_number}, %{order_item_tracking_number}, %{item_container_number}, %{external_customer_id}, %{external_customer_id2}, %{external_customer_id3}.
Driver Accepted Task Group
What it is. Tells the customer a driver is now allocated, with the expected time window.
Triggered when either of these happens:
- a driver accepts the job in the driver app
- a dispatcher assigns a driver on an account where auto-accept is switched on, so no driver action is needed
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{driver_name}, %{eta}, %{from_time}, %{to_time}, %{type}, %{address_display}, %{vehicle_plate_number}, %{pickup_contact_name}, %{dropoff_contact_name}, %{tracking_number}, %{global_tracking_number}, %{item_container_number}, %{external_customer_id}, %{external_customer_id2}, %{external_customer_id3}.
Driver Reassigned
What it is. Tells the customer the driver has changed, with the new time window.
Triggered when a job that was already assigned to one driver is accepted by a different driver.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{driver_name}, %{from_time}, %{to_time}, %{tracking_number}, %{global_tracking_number}, %{item_container_number}, %{external_customer_id}, %{external_customer_id2}, %{external_customer_id3}.
Pickup Completed
What it is. Confirms the goods have been collected, with the time and address.
Triggered when a pickup task is completed. That can be a driver completing it in the driver app, a dispatcher completing it in the portal, or the system completing it automatically.
Important. Where several pickups are completed at once, they are grouped into a single notification run rather than one message per task.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{completion_time}, %{address_display}, %{type}, %{driver_name}, %{vehicle_plate_number}, %{pickup_contact_name}, %{recipient_name}, %{from_time}, %{to_time}, %{tracking_number}, %{order_item_tracking_number}, %{global_tracking_number}, %{item_container_number}, %{attempt_notes}, %{waybill_url}, %{external_customer_id}, %{external_customer_id2}, %{external_customer_id3}.
Dropoff Completed
What it is. Confirms the goods have been delivered, with the time and address.
Triggered when a dropoff task is completed by a driver, by a dispatcher, or through a bulk complete action in the portal.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{completion_time}, %{address_display}, %{type}, %{driver_name}, %{vehicle_plate_number}, %{dropoff_contact_name}, %{recipient_name}, %{from_time}, %{to_time}, %{tracking_number}, %{global_tracking_number}, %{item_container_number}, %{attempt_notes}, %{waybill_url}, %{external_customer_id}, %{external_customer_id2}, %{external_customer_id3}.
Dropoff Failed
What it is. Tells the customer an attempt was unsuccessful.
Triggered when a task is reported as failed, either by the driver in the app or by a dispatcher marking it failed.
Important. Despite the name, this event also covers failed pickups, not only failed deliveries. If you switch it on, expect it to fire on unsuccessful collection attempts as well. Use %{type} in the template so the message says which one it was, and %{attempt_notes} to include the reason recorded by the driver.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Same set as Dropoff Completed.
Order Completed
What it is. The final confirmation that the whole order is done, and the point at which proof of delivery can be shared.
Triggered when the last outstanding task on an order is completed. That includes the driver or dispatcher completing the final task, a bulk complete, and cancelling the remaining items so that nothing is left outstanding.
Can be sent to Sender, Pickup Person, Dropoff Person.
Channels. Email and SMS.
Merge fields. Core set, order reference set, plus %{completion_time}, %{recipient_name} and %{pod_url} (the proof of delivery link).
Account notifications
These four are also listed on the Notifications page, but they behave differently. They go to a user account rather than to an order contact, so the Sender, Pickup Person and Dropoff Person columns do not apply to them. They are email only.
| Notification | Goes to | Sent when |
|---|---|---|
| Sender Created | The new customer user | A customer account is created, either by your team or by the customer registering. Only sends if the account is set up to send login credentials. |
| Dispatcher Created | The new dispatcher user | A dispatcher or admin user is added to your company. Always sends. |
| Worker Approved | The driver | A driver account is created or approved. |
| Partner Invitation Request | The invited partner | You send or resend a partner invitation. |
Merge fields for Partner Invitation Request: %{company_name} and %{invitation_url} only.
Merge fields
Merge fields are placeholders that are replaced with real values when the message sends. Write them exactly as shown, including the percent sign and braces, for example %{order_number}.
The template editor shows the exact list available for the notification you are editing. Use that list as the source of truth. The tables below explain what each field contains.
Core set, available on every order notification
| Field | Contains |
|---|---|
%{name} |
The name of the person receiving the message |
%{company_name} |
Your company name |
%{sender_name} |
The customer's contact name |
%{sender_email} |
The customer's email address |
%{sender_phone} |
The customer's phone number |
%{sender_type} |
Individual or Corporate |
%{original_sender_org_name} |
The originating organisation's name |
%{original_sender_org_phone} |
The originating organisation's phone |
%{original_sender_org_address} |
The originating organisation's address |
Order reference set
Available on every order notification except Batch Order Created.
| Field | Contains |
|---|---|
%{order_number} |
The Yojee order number |
%{tracking_url} |
The track and trace link for the order |
%{external_order_id} |
Your own reference for the order |
%{container_no} |
Container number |
%{waybill} |
Waybill number |
%{custom_field_1} to %{custom_field_4} |
Your four configurable order fields |
Other fields, where available
| Field | Contains |
|---|---|
%{tracking_number} |
The item tracking number |
%{order_item_tracking_number} |
The item tracking number, item-level events |
%{global_tracking_number} |
The global tracking number |
%{item_container_number} |
The container number on the item |
%{external_customer_id}, 2, 3 |
Your own customer references |
%{driver_name} |
The driver's name |
%{vehicle_plate_number} |
The vehicle registration |
%{type} |
Pick Up or Drop Off |
%{address_display} |
The address where the task happened |
%{completion_time} |
When the task was completed |
%{from_time} and %{to_time} |
Start and end of the booked time window |
%{eta} |
Estimated time of arrival |
%{pickup_contact_name} |
Pickup contact name |
%{dropoff_contact_name} |
Dropoff contact name |
%{recipient_name} |
Name of the person who received the goods |
%{attempt_notes} |
Notes recorded against a failed attempt |
%{pod_url} |
Link to the proof of delivery |
%{waybill_url} |
Link to the waybill or label |
%{batch_id} |
Batch reference, Batch Order Created only |
A note on the driver field. In the template editor this field is shown as %{driver_name}. Older documentation may refer to it as %{worker_name}. They are the same field.
Optional extras on SMS
Two extra lines can be appended to an SMS automatically, where the order carries the relevant data.
- Delivery PIN. Tells the customer the PIN to quote to the driver. The wording can be customised for your account.
- Cash on delivery. Tells the customer the amount to have ready for the driver. The wording is fixed.
Troubleshooting
A notification did not arrive. Work through these in order.
- Check the box is ticked for the right recipient column, in the right table (SMS and Email are separate).
- Check the contact detail exists on the order. Email needs an email address on that contact, SMS needs a phone number.
- Check the order reached the status that triggers the event. An order still in Created status has not triggered Order Accepted yet.
- If it was a batch upload, check the Order Accepted (Batch) row, not the single-order row.
- Check the customer's spam or junk folder. Notifications are sent from a Yojee system address.
- If none of that explains it, contact Yojee support with the order number and the notification you expected.
Customers are getting too many messages. The usual causes are:
- both Order Cancelled and Order Item Cancelled switched on, which doubles up on a full cancellation
- the same person listed as sender, pickup contact and dropoff contact, so all three columns match them
- several items on one order carrying different contacts
Replies to notifications. Notifications are sent from a system address. If you want replies to reach your team, ask Yojee support about setting a reply-to address for your account.