---
sidebar_label: 'Order lifecycle'
sidebar_position: 3
---

# Order lifecycle

An order in Future Ordering moves through a set of states from its creation to its finalization. <!-- todo: rewrite -->

The diagram below illustrates the flow of an order through its lifecycle.

```mermaid
stateDiagram-v2
    created : The order is created
    basket : The order accepts basket changes
    payment : The order is waiting for payment
    closed : The order is closed and is ready to be placed
    finalized : The order is finalized and does not accept any changes
    delivery : The order is waiting for delivery reservation
    state is_delivery <<choice>>

    created --> basket

    payment --> basket : The guest aborts the checkout process

    basket --> finalized : The guest aborts or abandons the order

    basket --> payment : The guest initiates checkout
    payment --> is_delivery : The guest successfully finishes the checkout process
    is_delivery --> closed
    is_delivery --> delivery : The order is a delivery order
    delivery --> closed : The delivery integration confirms the delivery

    closed --> finalized : The order placement is successful
    closed --> finalized : The order placement is unsuccessful or times out
```

### Created

When an order is first created, it moves immediately into the **basket** mode and is ready to accept items and discounts. No payment or checkout has occurred yet.

### Basket

In the basket mode, the guest can add, remove, and modify items. Discounts can be applied from loyalty integrations. See [Loyalty integrations](loyalty-integration/overview.md) for more information. This mode persists until the guest initiates checkout or abandons the order.

If the guest abandons or explicitly aborts the order while in this state, the order transitions directly to **finalized** without being placed.

### Payment in progress

When the guest initiates checkout, a payment session is started and the order transitions to the payment state. Basket changes are no longer accepted while a payment session is active.

If the guest aborts the checkout process before completing payment, the payment session is aborted and the order returns to the basket state, allowing further changes.

### Closed

Once the guest successfully completes checkout, payment is confirmed and the payments fully cover the order total, the order is closed. A closed order is ready to be placed in the Point of Sale (POS) system. No further basket changes are possible.

For delivery orders, the order must first pass through the **delivery** state, where the delivery integration confirms the reservation, before transitioning to closed.

### Placed in POS

Once the order is successfully placed in the POS, it should be marked as placed in Future Ordering. Whether placement succeeds or fails, the order will eventually transition to **finalized**. At this point, configured order workflows may trigger. See [Order workflows](./workflows.md) for more information.

If the POS integration cannot place the order, or if the placement session times out, the order is marked as failed and transitions to **finalized**.

### Finalized

Finalized is the terminal state. The order no longer accepts any changes. All orders, whether successfully placed or not, end in this state.

If an unexpected failure occurs at any point before finalisation (for example, an internal error), the order is moved directly to a failed state and then finalized. To retry, the order must be cloned.

## Workflows

After an order is placed in the POS, configured order workflows may trigger. See [Order workflows](./workflows.md) for more information.

## Order versioning

Every order carries a `versionId` field that acts as concurrency control. This is an integer value that increments each time the order is modified.

When updating an order, you can pass the current `versionId` as an `If-Match` header. The API rejects the request with a `412 Precondition Failed` response if the order has been modified since you last read the the order or an event, preventing unintentional overwrites.

You can also use the `versionId` to fetch a specific historical version of the order, which is useful for auditing state changes or replaying events.

## Order ownership

An order must be associated with a user before it can be placed. The `userId` property on the order identifies the user account that owns it. This can be one of three account types:

- A registered guest user account
- A temporary guest user
- A temporary device user, such as a kiosk user

User details can be retrieved from the API using the `userId` value. See [Users](../users/overview.md) for more information.

Order ownership can change during the order's lifetime. For example, when a guest signs in during checkout, or when a temporary user account is merged into a registered account, the `userId` on the order is updated to reflect the new owner. Future Ordering emits an `order.user_id_set` event each time ownership changes.