Skip to main content
↓ Download as Markdown

Order lifecycle

An order in Future Ordering moves through a set of states from its creation to its finalization.

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

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 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 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 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 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.