本文介绍如何在 WooCommerce 中为自定义订单状态（如 change）配置自动恢复库存功能，使其行为类似 cancelled 状态：当订单状态变更为 change 时，自动将订单内所有商品（含变体）的库存数量增加对应订购量。
本文介绍如何在 woocommerce 中为自定义订单状态（如 `change`）配置自动恢复库存功能，使其行为类似 `cancelled` 状态：当订单状态变更为 `change` 时，自动将订单内所有商品（含变体）的库存数量增加对应订购量。
在 WooCommerce 开发中，常需扩展订单生命周期以支持特殊业务场景，例如客户退换货流程中的“换货单”（change order）。此类订单通常不取消原单，而是标记为 change 状态，并需将已扣减的库存重新返还——这与 cancelled 状态的库存处理逻辑一致，但 WooCommerce 默认仅对 cancelled、failed 和 refunded 等内置状态触发库存回滚。
要实现这一目标，核心在于监听订单状态变更事件，并在目标状态匹配时调用 WooCommerce 内置的库存恢复函数 wc_increase_stock_levels()。该函数会遍历订单中所有订单项（包括简单产品、变体、订阅等），安全地累加库存，同时兼容库存同步、低库存提醒及库存日志记录等机制。
✅ 实现步骤如下：
-
确保已注册自定义订单状态 wc-change
在添加状态钩子前，请确认你已通过 register_post_status 和 woocommerce_order_statuses 正确注册了 wc-change 状态（注意：WooCommerce 要求自定义状态必须以 wc- 前缀开头）。示例注册代码（建议放入主题 functions.php 或插件中）：
// 注册自定义订单状态 'change'
add_action('init', 'register_wc_change_order_status');
function register_wc_change_order_status() {
register_post_status('wc-change', array(
'label' => _x('Change', 'Order status', 'textdomain'),
'public' => true,
'exclude_from_search' => false,
'show_in_admin_all_list' => true,
'show_in_admin_status_list' => true,
'label_count' => _n_noop('Change <span class="count">(%s)</span>', 'Change <span class="count">(%s)</span>', 'textdomain')
));
}
add_filter('woocommerce_order_statuses', 'add_wc_change_to_order_statuses');
function add_wc_change_to_order_statuses($order_statuses) {
$new_order_statuses = array();
foreach ($order_statuses as $key => $status) {
$new_order_statuses[$key] = $status;
if ('wc-processing' === $key) {
$new_order_statuses['wc-change'] = _x('Change', 'Order status', 'textdomain');
}
}
return $new_order_statuses;
}-
监听状态变更并触发库存恢复
使用 woocommerce_order_status_changed 动作钩子（该钩子在订单状态实际更新后触发，且传入完整 $order 对象），判断新状态是否为 change，并调用 wc_increase_stock_levels()：
add_action('woocommerce_order_status_changed', 'handle_change_order_stock_recovery', 10, 4);
function handle_change_order_stock_recovery($order_id, $old_status, $new_status, $order) {
// 注意：$new_status 是无前缀的状态标识符（如 'change'），非 'wc-change'
if ('change' === $new_status) {
// WooCommerce 内置函数，安全恢复所有订单项库存（含变体、库存管理启用的产品）
wc_increase_stock_levels($order);
// 【可选】记录日志便于调试
if (defined('WP_DEBUG') && WP_DEBUG) {
error_log("Order #{$order_id} status changed to 'change': stock restored.");
}
}
}⚠️ 关键注意事项：
- wc_increase_stock_levels() 仅对 启用库存管理（manage_stock == 'yes'） 的产品生效；未启用库存管理的商品不会被修改。
- 该函数会自动处理变体产品的 stock_quantity（父级不参与库存计算），并尊重 backorders 设置。
- 不建议在 woocommerce_order_status_{old}_to_{new} 这类动态钩子中操作库存，因其执行时机早于数据库持久化，可能导致竞态问题；woocommerce_order_status_changed 是最可靠的选择。
- 若需支持部分换货（即仅恢复部分商品库存），则需自行遍历 $order->get_items() 并调用 wc_update_product_stock()，但本方案默认采用全量恢复，符合典型换货场景。
? 验证效果：
以示例数据为例：
- 商品 A102-L（变体 ID: 123）初始库存为 12；
- 订单含 1 件该变体，状态变为 processing 后库存减至 11；
- 当手动将订单状态更改为 Change（后台下拉选择），保存后库存立即恢复为 12；
- 同理，A108-M（变体 ID: 456）从 13 恢复至 15。
可在「WordPress 后台 → WooCommerce → 产品 → 编辑变体」页面实时查看库存字段变化，或通过数据库查询 wp_postmeta 表中 _stock 键值确认。
? 总结：
通过组合使用 register_post_status + woocommerce_order_statuses + woocommerce_order_status_changed 钩子，开发者可零侵入地扩展 WooCommerce 库存逻辑。本方案复用官方函数 wc_increase_stock_levels()，既保证健壮性与兼容性，又避免重复造轮子。适用于换货、撤回订单、质检退回等多种需“反向扣减库存”的业务场景。
