---
title: Order statuses
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

> **License:** 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](https://docs.kentico.com/documentation/business-users/manage-commerce-stores.md) 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](#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](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/user-management.md) (staff)

### Create customer notification emails

Customer order notifications are based on [emails](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md) in [email channels](https://docs.kentico.com/documentation/developers-and-admins/digital-marketing-setup/email-channel-management.md).

> **Tip:** **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](https://docs.kentico.com/documentation/developers-and-admins/configuration/email-configuration.md) 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](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md).
   - 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](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md#personalize-emails-with-dynamic-text) to add information about the related order.
   ![Customer commerce order notification](https://docs.kentico.com/docsassets/documentation/configure-order-statuses/order_notification_customer.png "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](https://docs.kentico.com/documentation/business-users/digital-marketing/emails/create-emails-in-email-builder.md).

3. **Publish** the email.
   - See [Email lifecycle](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md#email-lifecycle) to learn more.

### Set internal notification content

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

> **Note:** **Prerequisite**
>
> Make sure that the [service domain for notifications](https://docs.kentico.com/documentation/developers-and-admins/configuration/notifications.md#configure-domains-for-notifications) is set up in your project. For projects deployed in the Xperience by Kentico [SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/saas.md), the [service domain](https://docs.kentico.com/documentation/developers-and-admins/digital-marketing-setup/email-channel-management.md#email-channels-in-the-saas-environment) is configured automatically.

1. Navigate to the **Notifications** application.
2. Select the **Commerce order** default notification and [edit the email content](https://docs.kentico.com/documentation/developers-and-admins/configuration/notifications.md#edit-default-notifications).

   - You can use [content placeholders](https://docs.kentico.com/documentation/developers-and-admins/configuration/notifications.md#notification-content-placeholders) to include information about the order.

   ![Internal commerce order notification](https://docs.kentico.com/docsassets/documentation/configure-order-statuses/order_notification.png "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](https://docs.kentico.com/documentation/business-users/manage-commerce-stores.md#change-order-status) 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](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md) 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](https://docs.kentico.com/documentation/business-users/manage-commerce-stores.md#change-order-status) 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](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process.md#create-orders-from-shopping-carts).

```csharp title="Send notifications on order creation" highlight="26"
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);
        }
    }
}
```