Order States and Statuses

Ãœbercart has implemented a two tiered approach to managing an order's workflow. This includes the definition and use of order states and order statuses. These may be understood as follows:

  • Order state - This is the general state of an order, its major step in the order workflow. It is essentially a category for order statuses with a small amount of meta data that applies to each of its corresponding statuses.
  • Order status - This is the actual status of an order within the order state. These may be customized per store. Administrators may also create custom order statuses to further refine the order workflow.

Order states are defined in modules while order statuses are stored in the database and may be created on the fly by store administrators. The general workflow of an order in a default Ubercart installation goes like this:

  1. When a customer moves from the checkout form to the review order page, a new order is created with their information in the default status for the in_checkout state. (By default, this is "In checkout.")
  2. When a customer completes checkout, the order gets moved from the default in_checkout status to the default status for the post_checkout state. (By default, this is "Pending.")
  3. The rest happens manually by order administrators, but the other two default statuses are "Processing" and "Completed." Processing is actually just another status in the post_checkout state while Completed is the default status for the completed state.

Why the duplication and bother with states vs. statuses? Well, this system allows the order statuses to be configurable by store administrators but also dependable in the code. Module developers must be assured that a status exists for a certain order state, but store owners can still have the freedom to rename, add, or reorder more order statuses.

When a module needs to move an order from one state to the next, it should use the function uc_order_state_default() to move the order to the default status for that state. Because store owners might change the way they want orders to progress, you shouldn't set the order's status directly.

The helper functions for the state/status system may be found here: