Configure order statuses
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
- Navigate to the Commerce configuration application.
- Select New order status.
- 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.
- Select Save.
- 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.
- Create an email.
- Set the Email purpose to Order status change.
- 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.
- 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.
- 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:
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.
- Navigate to the Notifications application.
- Select the Commerce order default notification and edit the email content.
- You can use content placeholders to include information about the order.
- Save the changes.
Enable notifications for order statuses
Now you need to enable the notification for individual order statuses:
- Navigate to the Commerce configuration application.
- Select an order status for which you want the system to send notifications.
- If you wish to enable internal notifications:
- Select the Notify users when the order reaches this status checkbox.
- 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.
- If you wish to enable customer notifications:
- Select the Notify the customer when the order reaches this status checkbox.
- Select an email with the Order status change purpose from an email channel.
- 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.
// 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);
}