如何在WooCommerce免费商品订单后更新用户角色

你的判断没错，问题主要出在两个关键点：

• 原代码用的woocommerce_order_status_processing钩子，免费订单通常不会触发这个状态（processing状态依赖支付完成的触发逻辑）
• paying_customer是专门标记付费用户的元数据，免费订单完全不需要设置这一项，而且这行代码对角色添加没有实际作用，属于冗余操作

下面是针对免费商品场景优化后的实现方案：

核心优化方向 #

• 更换触发钩子：改用woocommerce_order_status_completed，不管订单是付费还是免费，只要订单完成就会触发
• 移除无用的paying_customer元数据设置
• 使用WooCommerce官方推荐的最新方法（避免依赖已弃用的属性，提升代码兼容性）
• 添加重复操作防护：检查用户是否已拥有目标角色，避免重复执行角色变更逻辑

完整优化代码 #

function change_role_on_free_product_purchase( $order_id ) {
    // 获取订单对象（兼容新版WooCommerce的实例化方式）
    $order = wc_get_order( $order_id );
    if ( ! $order ) return;

    // 获取下单用户ID
    $user_id = $order->get_user_id();
    if ( $user_id <= 0 ) return; // 游客下单直接跳过

    // 遍历订单内的商品
    foreach ( $order->get_items() as $item ) {
        $product_id = $item->get_product_id();
        
        // 匹配目标商品ID
        if ( $product_id === 13874904 ) {
            $user = new WP_User( $user_id );
            
            // 检查用户是否已有目标角色，避免重复操作
            if ( ! $user->has_role( 'special_subscriber' ) ) {
                $user->remove_role( 'subscriber' );
                $user->add_role( 'special_subscriber' );
            }
            break; // 找到目标商品后停止遍历，提升执行效率
        }
    }
}
// 绑定到订单完成钩子，免费订单也能正常触发
add_action( 'woocommerce_order_status_completed', 'change_role_on_free_product_purchase' );

额外补充说明 #

1. 如果希望用户提交订单后立即触发（无需等待订单完成），可以把钩子换成woocommerce_thankyou，但要添加订单状态判断防止重复执行：

add_action( 'woocommerce_thankyou', 'change_role_on_free_product_purchase' );

然后在函数开头增加：

// 仅处理已完成或处理中的订单，避免重复触发
if ( ! in_array( $order->get_status(), array( 'completed', 'processing' ) ) ) return;

2. 确保免费商品设置正确：在WooCommerce商品编辑页将价格设为0，若无需实物发货，勾选“虚拟”或“下载”选项，这样订单会自动进入completed状态。

内容的提问来源于stack exchange，提问作者RichRBX