Order statuses

Order statuses represent stages in the lifecycle of orders created by your store's customers (New, Payment received, Shipped, Delivered, etc.).

Create order statuses

1. Navigate to the Commerce configuration application.
2. Select New order status.
3. Fill in the required fields.
   • Order status name – the display name of the status.
   • Notify users / the customer when the order reaches this status – specifies whether the system sends email notifications when an order is moved to this status (or when the order is created for the first order status). Notifications can be sent internally to selected users, or externally to the customer who created the order. See Configure notifications for order statuses.
4. Select Save.
5. Drag the order status to the appropriate position within your desired order lifecycle.

Configure notifications for order statuses

You can set up two types of notifications about order status changes:

• Customer – sent to the customer who created the order
• Internal – sent to selected users (staff)

Create customer notification emails

Customer order notifications are based on emails in email channels.

You can create any number of customer notification emails and use a different one for every order status.

1. Create an email.

   • Set the Email purpose to Order status change.

2. Prepare the email's content:

   • You can fill in the email's subject, preview text and other content fields in the Content view mode. Use dynamic text placeholders to add information about the related order.
   
   • If using an Email Builder template, you can compose the email's content using configurable components in the Email Builder view mode. For detailed information, see Create emails in Email Builder.

3. Publish the email.

   • See Email lifecycle to learn more.

Set internal notification content

The system uses a single notification template for internal order notifications. To define the content:

1. Navigate to the Notifications application.

2. Select the Commerce order default notification and edit the email content.

   • You can use content placeholders to include information about the order.
   

3. Save the changes.

Enable notifications for order statuses

Now you need to enable the notification for individual order statuses:

1. Navigate to the Commerce configuration application.
2. Select an order status for which you want the system to send notifications.
3. If you wish to enable internal notifications:
   1. Select the Notify users when the order reaches this status checkbox.
   2. Select Recipients – users who you want to receive the notification whenever an order is moved to this status.
      • Only users who have access to the Orders application can be selected.
      • If a user is selected and later loses the access to the Orders application, they will still receive order notifications, but will not be able to view the orders.
4. If you wish to enable customer notifications:
   1. Select the Notify the customer when the order reaches this status checkbox.
   2. Select an email with the Order status change purpose from an email channel.
5. Save the changes.

Send notifications for new orders

Order notifications (both for customers and internal) are automatically sent when moving existing orders between order statuses. If you want the system to send notifications when a new order is created, you need to call the SendNotification method of the IOrderNotificationService service when creating the order.

using System.Threading;
using System.Threading.Tasks;

using CMS.Commerce;

using Microsoft.Extensions.Logging;

// Gets an instance of IOrderNotificationService using dependency injection
public class OrderComponent(IOrderNotificationService orderNotificationService, ILogger<OrderComponent> logger)
{
    public async Task CreateOrder(CancellationToken cancellationToken)
    {
        // Creates a new order object
        var order = new OrderInfo()
        {
            // Create and populate the order object
            // ...
        };

        // Create and populate the order address (OrderAddressInfo) and order items (OrderItemInfo)
        // ...

        try
        {
            // Sends notifications about the created order (both for customers and internal)
            await orderNotificationService.SendNotification(order.OrderID, cancellationToken);
        }
        catch (OrderNotificationSendException ex)
        {
            // We strongly recommend using a logger service (e.g., ILogger) to detect errors that could occur when sending order notifications
            logger.LogError(ex, "Failed to send notification for order ID {OrderID}", order.OrderID);
        }
    }
}