Goal
Know the order statuses, what happens on each transition and where to plug in your logic.
Key concepts
- Statuses:
pending,on-hold,processing,completed,cancelled,refunded,failed,checkout-draft processing— paid, waiting to be shipped;on-hold— waiting for payment confirmation (bank transfer)- Hooks:
woocommerce_order_status_{to},woocommerce_order_status_{from}_to_{to},woocommerce_order_status_changed $order->payment_complete( $transaction_id )— the right way to mark payment: status, date, stock- Stock is reduced on payment or on the move to processing/on-hold; restored on cancellation
- Heavy work (ERP, CRM) goes to a queue, not into a status hook
Diagram
stateDiagram-v2
[*] --> checkout_draft: block checkout
checkout_draft --> pending: order created
pending --> processing: payment_complete()
pending --> on_hold: waiting for transfer
pending --> failed: payment declined
on_hold --> processing: payment confirmed
processing --> completed: shipped
processing --> cancelled
completed --> refunded: refund
failed --> pending: retry payment
Code
Send a paid order to the ERP through a queue:
<?php
add_action( 'woocommerce_order_status_processing', static function ( int $order_id ) {
as_enqueue_async_action( 'my_erp_push_order', [ 'order_id' => $order_id ], 'erp', true );
} );
add_action( 'my_erp_push_order', static function ( int $order_id ) {
$order = wc_get_order( $order_id );
if ( ! $order || $order->get_meta( '_erp_id' ) ) {
return; // already sent
}
$erp_id = My_Erp_Client::push( $order ); // throws → Action Scheduler marks it failed
$order->update_meta_data( '_erp_id', $erp_id );
$order->add_order_note( sprintf( 'ERP: %s', $erp_id ) );
$order->save();
} );
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Stock is reduced twice | A manual wc_reduce_stock_levels() + payment_complete() | Rely on payment_complete(); WooCommerce marks that stock was already reduced |
| Checkout "hangs" for 10 seconds | An ERP request in a status hook | Action Scheduler |
| The order reaches the ERP twice | The hook fired again | Check _erp_id before sending (idempotency) |
Weak and strong answer
Question: How do you integrate a new order with a CRM?
Weak answer. Send a request to the CRM in the
woocommerce_thankyouhook.
Strong answer.
woocommerce_thankyouis the render of the thank-you page: it may never be shown, or it may be reloaded twice. I take a data event —woocommerce_order_status_processingorpayment_complete— and queue a job in Action Scheduler. The job is idempotent, with retries and a log. That way checkout doesn't depend on the CRM's speed.
Why the second is stronger: The candidate tells a UI event from a data event and moves the integration out of the request.
Practice
Draw the order lifecycle for card payment and for bank transfer. For every transition write down the hook and what stock and emails do at that moment. In the terminal move order 1287 to processing, find the ERP job in the queue, run it and check the order notes.
Interview Questions
processing — payment received, the order has to be packed and shipped. completed — fulfilled. For virtual and downloadable products WooCommerce sets completed right after payment.
It sets the status (processing or completed), saves the transaction ID and the payment date, reduces stock if it wasn't reduced yet and fires the woocommerce_payment_complete hook.
woocommerce_payment_complete or woocommerce_order_status_processing, not the thank-you page. Heavy actions go through Action Scheduler.