> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/commerce/order-transition-notifications.md).

# Order Transition Notifications

When an order's status changes, Commerce automatically triggers a set of notifications — email, SMS, and push notification — depending on the transition. This document describes which notifications are sent for each transition, the conditions that must be met, and any dynamic settings that control the behavior.

**Related:**

* [E-mail Templates](/technical-guides/commerce/e-mail-templates.md) — email template structure and customization
* [Extension Notification Flows](https://apidocs.akinon.com/flows/extension-notification-flows) — push notification event reference for frontend integrations

***

## → Preparing (`450`)

**Condition:** Previous status is not `preparing`, new status is `preparing`.

| Channel           | Template / Event               |
| ----------------- | ------------------------------ |
| Email             | `emails/orders/preparing.html` |
| SMS               | `sms/orders/preparing.html`    |
| Push Notification | `order_preparing`              |

{% hint style="info" %}
The email is **disabled by default**. It can be enabled by setting `emails/orders/preparing` to `false` in the `DISABLED_EMAIL_TEMPLATES` dynamic setting.
{% endhint %}

***

## → Shipped (`500`)

**Condition:** Previous status is `approved` or `preparing`, new status is `shipped`, and the order has a tracking number. Requires `SEND_SHIPPING_NOTIFICATIONS_PARTIALLY = false`.

| Channel           | Template / Event           |
| ----------------- | -------------------------- |
| Email             | `emails/orders/cargo.html` |
| SMS               | `sms/orders/cargo.html`    |
| Push Notification | `order_shipped_cargo`      |

{% hint style="info" %}
When `SEND_SHIPPING_NOTIFICATIONS_PARTIALLY` is `true`, notifications are sent per order item instead. See [Order Item Transitions](#order-item-transitions).
{% endhint %}

***

## → Ready for Pickup (`520`)

**Condition:** Previous status is `shipped`, `shipped_and_informed`, or `preparing`, new status is `ready_for_pickup`.

| Channel           | Template / Event                            |
| ----------------- | ------------------------------------------- |
| Email             | `emails/orders/order-ready-for-pickup.html` |
| SMS               | `sms/orders/ready-for-pick-up.html`         |
| Push Notification | `order_ready_for_pick_up`                   |

***

## → Delivered (`550`)

**Condition:** Previous status is `approved`, `preparing`, `shipped`, `shipped_and_informed`, or `attempted_delivery`, new status is `delivered`. Requires `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY = false`.

| Channel           | Template / Event                     |
| ----------------- | ------------------------------------ |
| Email             | `emails/orders/order-delivered.html` |
| SMS               | `sms/orders/order-delivered.html`    |
| Push Notification | `order_delivered`                    |

{% hint style="info" %}
When `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY` is `true`, notifications are sent per order item instead. See [Order Item Transitions](#order-item-transitions).
{% endhint %}

***

## → Refunded (`600`)

**Condition:** Previous status is `approved`, `preparing`, or `delivered`, new status is `refunded`. Requires `SEND_REFUND_RESULT_NOTIFICATIONS = true` (disabled by default).

| Channel           | Template / Event                |
| ----------------- | ------------------------------- |
| SMS               | `sms/orders/refund-result.html` |
| Push Notification | `order_refund_result`           |

***

## E-archive Invoice Available

**Condition:** Order's `e_archive_url` field transitions from empty to set. Requires `SEND_INVOICE_AVAILABLE_NOTIFICATIONS = true` (enabled by default).

| Channel           | Template / Event                          |
| ----------------- | ----------------------------------------- |
| SMS               | `sms/orders/e-archive-url-available.html` |
| Push Notification | `order_e_archive_url_available`           |

***

## Push Notification on Status Change

In addition to the transition-specific notifications above, a push notification is sent for the following transitions via the configured push notification gateway:

| Transition                                                               |
| ------------------------------------------------------------------------ |
| `approved` → `preparing`                                                 |
| `approved` or `preparing` → `shipped`                                    |
| `shipped`, `shipped_and_informed`, or `attempted_delivery` → `delivered` |
| Any status → `cancellation_waiting`                                      |
| `cancellation_waiting` → `cancelled`                                     |
| `delivered` → `refunded`                                                 |

***

## Order Item Transitions

### Order Item → Shipped (`500`)

**Condition:** `SEND_SHIPPING_NOTIFICATIONS_PARTIALLY = true`, new status is `shipped`, and the item has a tracking number.

| Channel           | Template / Event                   |
| ----------------- | ---------------------------------- |
| Email             | `emails/orders/partial-cargo.html` |
| SMS               | `sms/orders/partial-cargo.html`    |
| Push Notification | `order_shipped_partial_cargo`      |

### Order Item → Delivered (`550`)

**Condition:** `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY = true`, new status is `delivered`.

| Channel           | Template / Event                             |
| ----------------- | -------------------------------------------- |
| Email             | `emails/orders/partial-delivered-cargo.html` |
| Push Notification | `order_delivered_partial`                    |

### Order Item → Ready for Pickup (`520`)

**Condition:** Previous status is `approved` or `preparing`, new status is `ready_for_pickup`, and the shipping address is a retail store.

| Channel | Template / Event                            |
| ------- | ------------------------------------------- |
| Email   | `emails/orders/order-ready-for-pickup.html` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/technical-guides/commerce/order-transition-notifications.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.