Refunds & Failed Competitions

When a competition reaches its scheduled end date without selling the configured Minimum tickets, it is classified as a failed competition. Quantum Competitions includes an automated batch-refund engine to protect customer trust and comply with consumer protection regulations.

---

What Triggers a Failed Competition?

A competition enters the failed state when:

1. Minimum Tickets Not Reached: The scheduled end date arrives, and total tickets sold is lower than the Min tickets setting.
2. No Extension Available: If Auto-extend is configured, the failure state only occurs once all extension attempts have been exhausted without meeting the minimum.

When this occurs:

• The competition status changes to Failed.
• The store administrator receives the Competition Failed email.
• Customers receive the Competition Failed (Customer) email notifying them that the draw did not take place.

---

1-Click Batch Refund System

Quantum Competitions includes a built-in batch refund engine inside the WordPress admin product screen. You do not need to open each WooCommerce order individually to process refunds.

How to Process Batch Refunds

1. Go to Competitions > All Competitions and open the failed competition.
2. In the competition status panel, a notice will indicate:
   Competition failed because there was not enough participants.
3. Click the Refund button.
4. A live progress container will appear:
   • Status display: Shows the current order ID being processed.
   • Percentage bar: Updates smoothly from 0% to 100% as each transaction is resolved.
   • Live log: Displays detailed status codes for each refunded order.

[Refund Progress] ------------------------> 100%
✓ Order #1042: Refunded £15.00 via Stripe API
✓ Order #1045: Refunded £5.00 via PayPal API
✓ Order #1049: Refunded £20.00 via Stripe API
Completed: 3 orders refunded successfully.

---

Payment Gateway Compatibility

Supported Automatic Gateways

If your payment gateway supports WooCommerce API refunds (e.g., WooCommerce Stripe Gateway, PayPal Payments, Authorize.net, Mollie):

• The refund is automatically transmitted directly to the customer’s payment provider.
• Funds are returned to their card or bank account.
• A WC_Order_Refund record is generated and attached to the order.

Gateways Without API Refund Support

If a customer paid using an offline method (e.g. Bank Transfer / BACS, Cash on Delivery) or a gateway that does not implement the WooCommerce refund API:

• The plugin creates the formal WooCommerce refund record.
• An admin alert is displayed: Payment gateway does not support refunds.
• An order note is logged indicating manual merchant disbursement is required.

---

Partial vs. Full Order Refunds

Customers frequently purchase tickets for multiple competitions in a single cart order. The refund engine handles mixed carts intelligently:

• Single Competition Order: If the order contained only tickets for the failed competition, the order is fully refunded and its status transitions to Refunded.
• Mixed Basket Order: If the order contained tickets for other active competitions or regular WooCommerce products, only the line total and applicable tax for the failed competition are refunded. The order remains active or changes to partially refunded.

---

Developer Hooks

Developers can hook into the refund lifecycle to log events to an external ERP, send SMS notifications, or issue store credit via wallet plugins:

/**
 * Hook fired when an individual order is refunded during competition batch processing.
 *
 * @param int $order_id  The WooCommerce order ID.
 * @param int $refund_id The WC_Order_Refund ID.
 */
add_action( 'qcw_order_refunded', function( $order_id, $refund_id ) {
    // Custom logging or customer notification logic
}, 10, 2 );

/**
 * Filter the order status applied when an order is fully refunded.
 * Default is 'refunded'.
 */
add_filter( 'qcw_order_fully_refunded_status', function( $status, $order_id, $refund_id ) {
    return 'refunded';
}, 10, 3 );