Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 39 ยท Orders and Checkout

Order Statuses and the Order Lifecycle

Understand WooCommerce order statuses, the transition hooks, when stock is reduced, what payment_complete does and how to add a custom status safely.

Every WooCommerce order is always in exactly one status, and almost everything interesting happens when that status changes: stock is reduced, emails are sent, downloads are unlocked, your integration is notified. If you understand the statuses and the hooks that fire on a change, you can attach your own behavior at the right moment instead of guessing or polling.

This lesson covers the built-in statuses, the order in which transition hooks fire, how stock reduction is wired, what payment_complete() does, and how to add a custom status. The business side of the lifecycle (what a status means for fulfillment and refunds) is in The Order Lifecycle; here we stay with the WooCommerce implementation. Real WooCommerce code is read-only; the runnable examples are plain PHP stand-ins.

The built-in statuses

Status Meaning
pending Order received, waiting for payment. No stock is held for long: unpaid orders are cancelled after the "hold stock" time.
processing Payment received (or not needed); the shop must now fulfill the order.
on-hold Waiting for something outside the system, typically a bank transfer to arrive.
completed Fulfilled. For virtual downloadable orders this is where payment ends up directly.
cancelled Cancelled by the shop or the customer.
refunded Fully refunded. Partial refunds do not change the status.
failed Payment failed or was declined.

There are also internal states you rarely handle yourself, such as checkout-draft (used by the block checkout while it prepares an order) and trash. In code, the status is a slug without prefix (processing). Internally it is still stored as wc-processing, which matters only when you register statuses or write raw queries (see Orders and High-Performance Order Storage).

stateDiagram-v2
  [*] --> pending
  pending --> processing: payment received
  pending --> on_hold: awaiting transfer
  pending --> failed: payment failed
  on_hold --> processing: transfer arrives
  processing --> completed: shipped
  processing --> refunded: full refund
  pending --> cancelled: timeout or cancel
  failed --> pending: customer retries

Typical paths. WooCommerce itself does not forbid other jumps; the arrows show what usually happens.

That last sentence is important: WooCommerce does not enforce a state machine. An admin (or your code) can move an order from completed back to pending. If your business needs rules, you must add them yourself, as the second example below shows.

Changing the status

There are two ways, and the difference is a classic trap:

PHP
<?php
// 1. Set and save separately. Hooks fire when the order is saved.
$order->set_status( 'completed' );
$order->save();

// 2. One call that also adds a note: set_status() + note + save().
$order->update_status( 'completed', 'Shipped with tracking 1Z999. ' );

// Wrong: nothing happens, the change is never saved.
$order->set_status( 'completed' );

set_status() only changes the object in memory, just like any other CRUD setter (CRUD Classes and Data Stores). Hooks run when the change is saved. Calling update_status() with a note is the simplest way for plugins, because the note records why the change happened.

The transition hooks

When a saved order has a changed status, WooCommerce fires these actions, all with the order ID and the WC_Order object (the generic one also receives the old and new status):

Hook When to use it
woocommerce_order_status_{to} "Whenever an order becomes processing" (for example woocommerce_order_status_processing).
woocommerce_order_status_{from}_to_{to} A specific transition, such as on-hold to processing.
woocommerce_order_status_changed One callback for every change; parameters are ID, old status, new status, order.
PHP
<?php
add_action( 'woocommerce_order_status_completed', function ( int $order_id, WC_Order $order ): void {
    if ( $order->get_meta( '_acme_erp_synced' ) ) {
        return; // hooks can run more than once for an order; stay idempotent
    }
    // enqueue the sync in the background instead of calling the ERP here
    as_enqueue_async_action( 'acme_sync_order', array( 'order_id' => $order_id ), 'acme' );
    $order->update_meta_data( '_acme_erp_synced', '1' );
    $order->save();
}, 10, 2 );

Two habits keep you safe. First, make callbacks idempotent (see Idempotency): a status can be set again by an admin, a webhook can arrive twice, and a callback should not double-ship. Second, do slow work (HTTP calls to other systems) in a background job, not inside the hook, because the hook runs inside the checkout request or the admin's click (Background Processing With Action Scheduler).

Take care with loops: if a callback changes the status again, it triggers the hooks again. Always guard with a condition that is false after your own change.

Stock and statuses

Stock levels are reduced by a core function that is hooked to several status changes: payment completion and the transitions to processing, on-hold and completed. It marks the order (internally, as "stock already reduced") so that later transitions do not reduce the same items twice. The opposite function, which returns the stock, is hooked to cancelled and pending.

This explains behavior that confuses new developers: an order that goes processing then completed reduces stock once; a cancelled order puts the units back; a bank transfer order in on-hold already reserves stock. If you add a custom status, think about whether it should count as "stock reserved" and hook the functions accordingly. For the general stock theory, read Inventory Reservations.

payment_complete()

Gateways call $order->payment_complete( $transaction_id ) when money has arrived (Building a Payment Gateway). In short, it:

  1. Does nothing unless the order is in a status that can still be paid (for example pending, on-hold, failed or cancelled).
  2. Stores the transaction ID and the paid date.
  3. Chooses the new status: processing, or completed when the order contains only virtual and downloadable items. A filter, woocommerce_payment_complete_order_status, lets you change that decision.
  4. Fires the woocommerce_payment_complete action and reduces stock.

So a gateway never needs to set processing itself. Letting payment_complete() choose keeps your gateway in line with how the merchant's other products behave.

Custom statuses

To add a status such as "Shipped" you register it as a post status (WooCommerce still uses this mechanism, also with HPOS) and add it to the list of order statuses. Use the wc- prefix for the registered name:

PHP
<?php
add_action( 'init', function (): void {
    register_post_status( 'wc-shipped', array(
        'label'                     => 'Shipped',
        'public'                    => true,
        'exclude_from_search'       => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        /* translators: %s: number of orders */
        'label_count'               => _n_noop( 'Shipped <span class="count">(%s)</span>', 'Shipped <span class="count">(%s)</span>', 'acme' ),
    ) );
} );

add_filter( 'wc_order_statuses', function ( array $statuses ): array {
    $statuses['wc-shipped'] = 'Shipped';
    return $statuses;
} );

After that, the status shows in the admin dropdown and you can use $order->update_status( 'shipped' ). Remember the extras that a status does not get for free: no email is sent (see Custom Transactional Emails), reports and "paid" lists do not know it (filter woocommerce_order_is_paid_statuses and wc_order_is_editable_statuses if relevant), and bulk actions need to be added. Keep custom statuses few; a note or a meta flag is often enough.

Order notes

Every status change by the admin or update_status() adds a note, and you can add your own with $order->add_order_note( 'Label printed', false ). The second argument controls whether the note is a customer note (visible to the customer and emailed) or a private note. Use private notes for audit trails (which system changed what, with which transaction ID) and never put secrets in them: notes are visible to every shop manager.

A status machine with hooks and stock

This stand-in reproduces the pattern: a transition fires the three kinds of hooks, a stock listener reduces once and restores on cancel, and a flag makes the callbacks idempotent. Watch the event log and the stock numbers.

PHP Transition hooks and stock reduction, once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The real hook names are woocommerce_order_status_processing and so on; the shortened names and the hook-bus class are the stand-in. The idempotent "already reduced" flag is a real WooCommerce idea.

A guard, payment_complete and a custom status

Because core allows any jump, a plugin that needs rules must add them. This second stand-in shows a policy table with a custom shipped status, the payment_complete() decision, and what happens when a forbidden jump is attempted.

PHP payment_complete choice and a transition policy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Real and stand-in: the payable statuses and the "virtual and downloadable goes straight to completed" decision follow WooCommerce. The policy table is an example of a rule you would enforce yourself, for instance by reverting a change inside woocommerce_order_status_changed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the bug in this code? $order->set_status( 'completed' );

    Setters change the object only. Hooks fire and the new status is stored when the order is saved, which update_status() does for you.
  2. 2. Which hook runs for every status change and receives the old and the new status?

    woocommerce_order_status_changed passes the order ID, the old status, the new status and the order. The other hooks are tied to a specific status or event.
  3. 3. A virtual, downloadable-only order is paid. What status does payment_complete() normally give it?

    Orders that need no shipping go straight to completed, unless the woocommerce_payment_complete_order_status filter changes the choice. Other orders become processing.
  4. 4. Why should a status callback that talks to an external ERP system usually enqueue a background job?

    Slow third-party calls inside a hook make checkout slow or fail it entirely. A queued job can retry, and the callback stays fast and idempotent.
  5. 5. Does WooCommerce itself stop an admin from moving an order from completed back to pending?

    Core has no enforced state machine. Plugins that need one add a policy and revert or block forbidden changes.

Summary

  • Orders have one status at a time: pending, processing, on-hold, completed, cancelled, refunded or failed, stored with a wc- prefix and used without it in code.
  • set_status() changes memory only; save() or update_status() persists it and fires woocommerce_order_status_{to}, woocommerce_order_status_{from}_to_{to} and woocommerce_order_status_changed.
  • Make callbacks idempotent and push slow work into background jobs.
  • Stock is reduced once when an order becomes paid or reserved and restored on cancel or pending; a flag prevents double counting.
  • payment_complete() picks processing or completed for you; gateways should call it rather than set a status.
  • Custom statuses need registration, a wc_order_statuses entry and your own handling of emails, reports and stock; WooCommerce enforces no transition rules.

Next: Classic Checkout Fields and Validation