woocommerce_order_status_completed
Cómo ejecutar una acción al completar un pedido de WooCommerce sin duplicados y con control de errores.
- Revisado
- Compatibilidad
- WooCommerce 2.2+
- Lectura
- 2 min
- Autor
- Gabriel — infinit8
Este hook se lanza cuando un pedido entra en estado completed. Es útil para integraciones posteriores al pedido, pero el callback debe tolerar reintentos y registrar su resultado.
Qué significa completed
Completado no equivale siempre a pagado. En productos físicos suele alcanzarse tras la gestión del pedido; en productos virtuales puede ocurrir automáticamente. Diseña la regla según el flujo real de estados.
Ejecutar una tarea una sola vez
add_action(
'woocommerce_order_status_completed',
function (int $order_id, WC_Order $order): void {
if ('yes' === $order->get_meta('_i8_exported')) {
return;
}
// Ejecutar aquí una operación controlada.
$order->update_meta_data('_i8_exported', 'yes');
$order->save();
},
10,
2
);Marcar antes o después depende de la estrategia de reintento. En integraciones importantes utiliza una cola, claves idempotentes y registro de errores.
Procesamiento asíncrono
Si la operación llama a un ERP, genera documentos o tarda más de unos segundos, programa una tarea con Action Scheduler. El cambio de estado no debe quedar bloqueado por un tercero.
Pruebas necesarias
- Cambiar el pedido a completado dos veces.
- Simular un timeout del servicio externo.
- Reintentar una tarea fallida.
- Comprobar pedidos invitados y reembolsados.
Preguntas frecuentes
¿Recibe el objeto WC_Order?
Las versiones actuales pasan el ID y el objeto del pedido. Declara dos argumentos al registrar el callback.
¿Es lo mismo que payment_complete?
No. El pago completado y el estado completed representan momentos distintos del ciclo del pedido.
Referencias y revisión
Contenido contrastado con documentación oficial. Comprueba siempre el comportamiento en un entorno de pruebas antes de desplegar cambios.