Setting up notifications about order status changes in 1C-Bitrix

Order Status Change Notification Configuration for 1C-Bitrix

A customer places an order and waits. The next touchpoint is the status change notification. If the email arrives late or contains errors, it damages trust. 1C-Bitrix sends notifications through the mail event mechanism, which requires deliberate configuration for each specific business.

Mail Event Mechanism

The notification system is built on three layers:

1. Mail event type — a description with a set of macros (SALE_STATUS_CHANGED)
2. Template — an HTML email with macros, bound to a site and language
3. Send call — CEvent::Send() in the event handler

When a status changes with the "Notify customer" flag set, Bitrix automatically sends SALE_STATUS_CHANGED. The flag is cleared when full control over the notification logic is required.

Standard Macros

#ORDER_ID#           — order number
#ORDER_DATE#         — order date
#ORDER_STATUS#       — name of the new status
#ORDER_PRICE#        — order amount
#ORDER_TRACK_NUMBER# — tracking number
#BUYER_EMAIL#        — customer email
#BUYER_NAME#         — customer name

Custom Handler with Extended Data

AddEventHandler('sale', 'OnSaleStatusOrderChange', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    $newStatus = $order->getField('STATUS_ID');

    $notifyStatuses = ['F', 'PROCESSING', 'DELIVERING', 'D', 'CANCEL'];
    if (!in_array($newStatus, $notifyStatuses)) return;

    $propCollection = $order->getPropertyCollection();
    $buyerEmail = $propCollection->getUserEmail();
    if (!$buyerEmail) return;

    $trackNumber = '';
    foreach ($order->getShipmentCollection() as $shipment) {
        if (!$shipment->isSystem() && $shipment->getField('TRACKING_NUMBER')) {
            $trackNumber = $shipment->getField('TRACKING_NUMBER');
            break;
        }
    }

    \CEvent::Send('SALE_STATUS_CHANGED', SITE_ID, [
        'ORDER_ID'     => $order->getId(),
        'ORDER_DATE'   => $order->getDateInsert()->format('d.m.Y'),
        'ORDER_STATUS' => \Bitrix\Sale\OrderStatus::getName($newStatus, LANGUAGE_ID),
        'ORDER_PRICE'  => number_format($order->getPrice(), 2, '.', ' '),
        'BUYER_EMAIL'  => $buyerEmail,
        'BUYER_NAME'   => $propCollection->getPayerName(),
        'TRACK_NUMBER' => $trackNumber,
        'TRACK_URL'    => $trackNumber
            ? 'https://track.pochta.ru/tracking#' . $trackNumber
            : '',
    ]);
});

Separate Templates per Status

A single template for all statuses is a poor solution: an "Order Completed" email should look different from "Order Cancelled". Create separate event types:

\CEventType::Add([
    'EVENT_NAME'  => 'SALE_STATUS_DELIVERING',
    'LID'         => 's1',
    'NAME'        => 'Order dispatched for delivery',
    'FIELDS'      => [
        ['ID' => 'ORDER_ID',      'NAME' => 'Order number'],
        ['ID' => 'TRACK_NUMBER',  'NAME' => 'Tracking number'],
        ['ID' => 'TRACK_URL',     'NAME' => 'Tracking link'],
        ['ID' => 'DELIVERY_NAME', 'NAME' => 'Delivery service'],
        ['ID' => 'BUYER_EMAIL',   'NAME' => 'Customer email'],
        ['ID' => 'BUYER_NAME',    'NAME' => 'Customer name'],
    ],
]);

Each status gets its own HTML template: a tracking link for "In Delivery", a reason and instructions for "Cancelled".

SMS Notifications

AddEventHandler('sale', 'OnSaleStatusOrderChange', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    if ($order->getField('STATUS_ID') !== 'DELIVERING') return;

    $phone = preg_replace('/\D/', '', $order->getPropertyCollection()->getPhone());
    if (!$phone) return;

    $text = "Order #{$order->getId()} has been dispatched for delivery.";
    $trackNumber = getOrderTrackNumber($order);
    if ($trackNumber) $text .= " Track: {$trackNumber}";

    sendSms($phone, $text); // your SMS gateway integration
});

Manager Notifications for Problem Statuses

if ($newStatus === 'RETURN_INIT') {
    $managerEmail = getOrderManagerEmail($order);
    if ($managerEmail) {
        \CEvent::Send('SALE_RETURN_INITIATED', SITE_ID, [
            'ORDER_ID'      => $order->getId(),
            'MANAGER_EMAIL' => $managerEmail,
            'BUYER_NAME'    => $propCollection->getPayerName(),
            'BUYER_PHONE'   => $propCollection->getPhone(),
            'ORDER_PRICE'   => number_format($order->getPrice(), 2, '.', ' '),
        ]);
    }
}

Timeline

Setting up standard notifications for 3–5 statuses with custom templates — 4–8 hours. Separate templates, SMS, manager notifications, full testing — 1–2 business days.