After coupon is awarded (legacy flow) (uspw_after_coupon_won)

Hook: uspw_after_coupon_won

Overview

The uspw_after_coupon_won action allows developers to execute custom logic immediately after a user wins a prize and their data is saved to the database.

This is the primary hook integration point for connecting Ultimate Spin Wheel to external systems like CRMs, SMS gateways, or custom analytics platforms.

---

🔧 Technical Details

• Type: Action
• Location: includes/core/class-spin-wheel.php
• Trigger: Fires during the AJAX process when a spin is validated and completed.

Parameters

Parameter	Type	Description
$campaign_id	int	The ID of the spin wheel campaign interaction.
$data	array	A comprehensive array containing user info, prize details, and metadata.

The $data Array Structure

The $data array contains the following keys:

[
    'email'          => '[email protected]', // User's email
    'phone'          => '+123456789',       // User's phone (if enabled)
    'name'           => 'John Doe',         // User's name (if enabled)
    'campaign_id'    => 123,                // Campaign ID
    'coupon_code'    => 'SAVE20',           // The default code
    'coupon_title'   => '20% Off',          // The label
    'message'        => 'You won a prize!', // Custom Win/Lose Message
    'status'         => 'won',              // or 'lost'
    'segment_index'  => 3,                  // Index of winning segment
    'optin'          => 1                   // 1 if opted in, 0 if not
]

---

💻 Code Examples

Add these snippets to your theme’s functions.php file or a custom plugin.

Example 1: Basic Logging (Debugging)

This example simply writes the winner’s email to your debug.log file.

add_action( 'uspw_after_coupon_won', 'my_custom_spin_logger', 10, 2 );

function my_custom_spin_logger( $campaign_id, $data ) {
    $email = isset( $data['email'] ) ? $data['email'] : 'No Email';
    $prize = isset( $data['coupon_title'] ) ? $data['coupon_title'] : 'Unknown Prize';

    error_log( "SPIN WINNER: Campaign #$campaign_id - User $email won $prize" );
}

Example 2: Sending Data to a Webhook (Zapier/Make)

This example sends the lead data to an external URL. This is useful if you want to connect to a service that isn’t natively supported by the plugin.

add_action( 'uspw_after_coupon_won', 'send_spin_to_webhook', 10, 2 );

function send_spin_to_webhook( $campaign_id, $data ) {
    // 1. Define your webhook URL (e.g., from Zapier)
    $webhook_url = 'https://hooks.zapier.com/hooks/catch/123456/abcdef/';

    // 2. Prepare the payload
    $payload = [
        'event'    => 'spin_win',
        'campaign' => $campaign_id,
        'email'    => $data['email'],
        'name'     => $data['name'] ?? '',
        'phone'    => $data['phone'] ?? '',
        'prize'    => $data['coupon_title'] ?? '',
        'code'     => $data['coupon_code'] ?? '',
        'date'     => date( 'Y-m-d H:i:s' )
    ];

    // 3. Send the request
    wp_remote_post( $webhook_url, [
        'body'    => json_encode( $payload ),
        'headers' => [ 'Content-Type' => 'application/json' ],
        'blocking' => false, // Don't slow down the user's spin animation
    ]);
}

Example 3: Assigning a User Role

If your users are logged in, you might want to give them a special “VIP” role when they win.

add_action( 'uspw_after_coupon_won', 'promote_winner_role', 10, 2 );

function promote_winner_role( $campaign_id, $data ) {
    // Only apply for specific campaign #5
    if ( $campaign_id !== 5 ) return;

    $user = get_user_by( 'email', $data['email'] );

    if ( $user ) {
        $user->add_role( 'vip_customer' );
    }
}

Example 4: Sending SMS Notification (SMS)

This example sends an SMS to the winner using the SMS API. Make sure to enable the phone field in your campaign settings.

add_action( 'uspw_after_coupon_won', 'send_sms_spin_winner', 10, 2 );

function send_sms_spin_winner( $campaign_id, $data ) {
    
    // 1. Check if phone number exists
    $phone_raw = isset( $data['phone'] ) ? $data['phone'] : '';
    if ( empty( $phone_raw ) ) return;

    // 2. Format phone number (Remove +, spaces, dashes)
    $phone = preg_replace( '/[^0-9]/', '', $phone_raw );
    
    // 3. Prepare Message
    $coupon_code  = isset( $data['coupon_code'] ) ? $data['coupon_code'] : 'NO_CODE';
    $coupon_label = isset( $data['coupon_title'] ) ? $data['coupon_title'] : 'a prize';
    
    // Get custom message and handle placeholders like {{discount_label}}
    $custom_msg = isset( $data['message'] ) ? strip_tags( $data['message'] ) : '';
    $custom_msg = str_replace( '{{discount_label}}', $coupon_label, $custom_msg );
    
    // If custom message exists, use it. Otherwise default.
    $message = ! empty( $custom_msg ) 
        ? "Congratulations! $custom_msg Code: $coupon_code"
        : "Congratulations! You won $coupon_label. Code: $coupon_code";

    // 4. Send API Request
    $api_url = 'https://panel......com/api';
    $params  = [
        'user'     => 'YOUR_USERNAME', // Replace with your username
        'password' => 'YOUR_PASSWORD', // Replace with your password
        'to'       => $phone,
        'text'     => $message,
    ];

    // Build query manually to ensure clean URL
    $request_url = $api_url . '?' . http_build_query( $params );
    
    // 5. Execute Request
    $response = wp_remote_get( $request_url, [
        'blocking'  => false, // Non-blocking so user doesn't wait
        'sslverify' => false, // Fix for some server SSL issues
        'timeout'   => 15
    ] );
    
    // Optional: Log errors if debugging
    if ( is_wp_error( $response ) && WP_DEBUG ) {
        error_log( 'SMS API ERROR: ' . $response->get_error_message() );
    }
}

---

⚠️ Important Notes

1. Non-Blocking: Try to keep your code fast. If you do heavy processing (like calling a slow external API with blocking => true), the user’s wheel might hang while spinning.
2. Error Handling: Always check if keys exist in $data using isset() or the null coalescing operator ??, as users might skip optional fields like Name or Phone.

Need Help?

Code not firing? 👉 Contact Our Developer Support