SquareSync for Woo
Docs
Actions Reference

Actions Reference

WordPress actions to respond to SquareSync events.

Actions let you respond to events without modifying data. Use these hooks to trigger custom functionality, log events, send notifications, and integrate with other systems.

Order Actions

squarewoosync_before_order_import

Fires before importing a Square order to WooCommerce.

Location: includes/Jobs/WebhookProcessJob.php

ParameterTypeDescription
$orderIdstringSquare order ID
$dataarrayWebhook payload
$parent_process_idstringParent process identifier
add_action('squarewoosync_before_order_import', function($orderId, $data, $parent_process_id) {
    // Perform pre-import actions
    error_log("Starting import of Square order: {$orderId}");
}, 10, 3);

squarewoosync_square_order_created

Fires after a Square order is created from a WooCommerce order.

Location: includes/Woo/SyncOrder.php

ParameterTypeDescription
$square_order_idstringCreated Square order ID
$wc_order_idintWooCommerce order ID
add_action('squarewoosync_square_order_created', function($square_order_id, $wc_order_id) {
    error_log("Order {$wc_order_id} synced to Square: {$square_order_id}");
}, 10, 2);

squarewoosync_square_order_imported

Fires after a WooCommerce order is created from a Square order.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$square_order_idstringSource Square order ID
$wc_order_idintCreated WooCommerce order ID
add_action('squarewoosync_square_order_imported', function($square_order_id, $wc_order_id) {
    // Post-import processing
    $order = wc_get_order($wc_order_id);
    $order->add_order_note('Imported from Square: ' . $square_order_id);
}, 10, 2);

sws_order_import_completed

Fires when a batch order import job completes.

Location: includes/Jobs/OrderImportJob.php

ParameterTypeDescription
$progressarrayImport progress data
add_action('sws_order_import_completed', function($progress) {
    $imported = $progress['imported'] ?? 0;
    $failed = $progress['failed'] ?? 0;
    error_log("Order import completed: {$imported} imported, {$failed} failed");
});

Product Actions

squarewoosync_product_created

Fires after a WooCommerce product is created from Square.

Location: includes/Woo/CreateProduct.php

ParameterTypeDescription
$product_idintCreated WooCommerce product ID
$square_item_idstringSource Square item ID
$square_dataarrayRaw Square item data
add_action('squarewoosync_product_created', function($product_id, $square_item_id, $square_data) {
    update_post_meta($product_id, '_square_item_id', $square_item_id);
    update_post_meta($product_id, '_imported_from_square', true);
}, 10, 3);

Payment Actions

squarewoosync_payment_completed

Fires when a Square payment is completed successfully.

Location: includes/Payments/WC_SquareSync_Gateway.php

ParameterTypeDescription
$order_idintWooCommerce order ID
$payment_idstringSquare payment ID
$payment_dataarrayFull payment details
add_action('squarewoosync_payment_completed', function($order_id, $payment_id, $payment_data) {
    // Access full payment data
    $amount = $payment_data['amount_money']['amount'] ?? 0;
 
    // Send custom notification
    wp_mail(
        'sales@example.com',
        'New Square Payment',
        "Order #{$order_id} paid via Square: {$payment_id} - Amount: {$amount}"
    );
}, 10, 3);

Best Practices

Priority Management

Use appropriate priority values to control execution order:

// Run early (before other plugins)
add_action('squarewoosync_square_order_created', 'my_function', 5, 2);
 
// Run at default priority
add_action('squarewoosync_square_order_created', 'my_function', 10, 2);
 
// Run late (after other plugins)
add_action('squarewoosync_square_order_created', 'my_function', 99, 2);

Error Handling

Actions should handle errors gracefully to avoid breaking the sync process:

add_action('squarewoosync_product_created', function($product_id, $square_item_id, $square_data) {
    try {
        // Your custom logic
        do_something_with_product($product_id);
    } catch (Exception $e) {
        error_log('SquareSync action error: ' . $e->getMessage());
        // Don't re-throw - let the sync continue
    }
}, 10, 3);

Performance Considerations

Avoid heavy operations in hooks that run during checkout or frequent syncs:

// Bad: Expensive operation during payment
add_action('squarewoosync_payment_completed', function($order_id, $payment_id, $payment_data) {
    $all_orders = get_posts(['post_type' => 'shop_order', 'numberposts' => -1]); // Slow!
}, 10, 3);
 
// Good: Defer expensive operations
add_action('squarewoosync_payment_completed', function($order_id, $payment_id, $payment_data) {
    // Schedule for later processing
    wp_schedule_single_event(time() + 60, 'my_deferred_processing', [$order_id]);
}, 10, 3);

Logging

Use WordPress logging for debugging:

add_action('squarewoosync_square_order_created', function($square_order_id, $wc_order_id) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log(sprintf(
            '[SquareSync] Order %d synced to Square as %s',
            $wc_order_id,
            $square_order_id
        ));
    }
}, 10, 2);

Testing

Test your customizations thoroughly:

  1. Use Sandbox mode first — Test with Square's sandbox environment
  2. Test with various order types — Simple, variable, subscription
  3. Check error logs — Monitor for issues
  4. Verify data in Square — Confirm customizations apply correctly
  5. Test edge cases — Empty values, missing data, errors

Common Use Cases

Send Slack Notification on Import

add_action('squarewoosync_square_order_imported', function($square_order_id, $wc_order_id) {
    $order = wc_get_order($wc_order_id);
    $total = $order->get_total();
 
    wp_remote_post('https://hooks.slack.com/services/YOUR/WEBHOOK/URL', [
        'body' => json_encode([
            'text' => "New Square order imported: #{$wc_order_id} - \${$total}"
        ]),
        'headers' => ['Content-Type' => 'application/json']
    ]);
}, 10, 2);

Sync to External CRM

add_action('squarewoosync_payment_completed', function($order_id, $payment_id, $payment_data) {
    $order = wc_get_order($order_id);
 
    // Send to CRM
    wp_remote_post('https://api.crm.example.com/orders', [
        'body' => json_encode([
            'order_id' => $order_id,
            'email' => $order->get_billing_email(),
            'total' => $order->get_total(),
            'payment_id' => $payment_id
        ]),
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . CRM_API_KEY
        ]
    ]);
}, 10, 3);

Custom Product Post-Processing

add_action('squarewoosync_product_created', function($product_id, $square_item_id, $square_data) {
    // Set custom category based on Square data
    $square_category = $square_data['item_data']['category_id'] ?? '';
 
    if ($square_category === 'CATEGORY_ABC') {
        wp_set_object_terms($product_id, 'special-items', 'product_cat');
    }
 
    // Add to featured if marked in Square
    if (!empty($square_data['item_data']['is_featured'])) {
        update_post_meta($product_id, '_featured', 'yes');
    }
}, 10, 3);
Filters ReferencePerformance Settings