Configure order statuses

Advanced license required

Features described on this page require the Xperience by Kentico Advanced license tier.

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.

Dedicated commerce email channel

If possible, we recommend setting up a separate dedicated email channel for your commerce-related emails. This allows you to:

  • Use a different sending domain than your other email communication. This protects your commerce email sender’s reputation from being affected by other emails (e.g., marketing newsletters).
  • Set up a separate email client for sending commerce-related emails. This ensures that order notifications are not delayed by other email operations, for example when a newsletter is being sent to a very large number of recipients.

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.
      Customer commerce order notification
    • 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.

Set internal notification content

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

Prerequisite

Make sure that the service domain for notifications is set up in your project. For projects deployed in the Xperience by Kentico SaaS environment, the service domain is configured automatically.

  1. Navigate to the Notifications application.
  2. Select the Commerce order default notification and edit the email content. Internal commerce order notification
  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.

C#
Send notifications on order creation

// An instance of IOrderNotificationService can be retrieved using dependency injection
private readonly IOrderNotificationService orderNotificationService;

// 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);
}