Docs
Filters Reference

Filters Reference

WordPress filters to modify SquareSync data and behavior.

Filters let you modify data before it's processed by SquareSync. Use these hooks to customize sync behavior, transform data, and integrate with other systems.

Order Filters

squarewoosync_prepare_order_data

Modify order data before sending to the Square API.

Location: includes/REST/OrdersController.php

ParameterTypeDescription
$order_dataarraySquare order data structure
$wc_orderWC_OrderWooCommerce order object
add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    $order_data['order']['metadata']['store_id'] = get_current_blog_id();
    $order_data['order']['metadata']['source'] = 'woocommerce';
    return $order_data;
}, 10, 2);

squarewoosync_order_location_id

Override the Square location for specific orders.

Location: includes/REST/OrdersController.php

ParameterTypeDescription
$location_idstringSquare location ID
$orderWC_OrderWooCommerce order
add_filter('squarewoosync_order_location_id', function($location_id, $order) {
    $shipping_zone = $order->get_shipping_state();
    if ($shipping_zone === 'CA') {
        return 'CALIFORNIA_LOCATION_ID';
    }
    return $location_id;
}, 10, 2);

squarewoosync_webhook_order_import_enabled

Control whether specific Square orders should be imported via webhook.

Location: includes/Jobs/WebhookProcessJob.php

ParameterTypeDescription
$should_importboolWhether to import this order
$orderIdstringSquare order ID
$orderLocationstringSquare location ID
$dataarrayWebhook payload data
add_filter('squarewoosync_webhook_order_import_enabled', function($should_import, $orderId, $orderLocation, $data) {
    // Skip orders from specific location
    if ($orderLocation === 'LOCATION_TO_SKIP') {
        return false;
    }
    return $should_import;
}, 10, 4);

squarewoosync_before_process_square_order

Modify Square order data before processing for import.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$squareOrderarraySquare order data
$orderIdstringSquare order ID
add_filter('squarewoosync_before_process_square_order', function($squareOrder, $orderId) {
    // Add custom processing logic
    return $squareOrder;
}, 10, 2);

squarewoosync_square_order_data

Modify Square order data before creating WooCommerce order.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$squareOrderarraySquare order data
$email_settingsarrayEmail notification settings
add_filter('squarewoosync_square_order_data', function($squareOrder, $email_settings) {
    // Modify order data before WooCommerce order creation
    return $squareOrder;
}, 10, 2);

squarewoosync_order_customer_id

Override customer ID assigned to imported orders.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$customerIdintWordPress customer ID
$squareOrderarraySquare order data
$orderWC_OrderWooCommerce order
add_filter('squarewoosync_order_customer_id', function($customerId, $squareOrder, $order) {
    // Assign specific customer based on Square data
    return $customerId;
}, 10, 3);

squarewoosync_order_line_items

Modify line items before adding to imported order.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$lineItemsarrayLine items array
$orderWC_OrderWooCommerce order
$squareOrderarraySquare order data
add_filter('squarewoosync_order_line_items', function($lineItems, $order, $squareOrder) {
    // Modify line items during import
    return $lineItems;
}, 10, 3);

squarewoosync_order_taxes

Modify tax data before applying to imported order.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$taxesarrayTax data array
$orderWC_OrderWooCommerce order
$squareOrderarraySquare order data
add_filter('squarewoosync_order_taxes', function($taxes, $order, $squareOrder) {
    // Modify taxes during import
    return $taxes;
}, 10, 3);

squarewoosync_order_discounts

Modify discount data before applying to imported order.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$discountsarrayDiscounts array
$orderWC_OrderWooCommerce order
$squareOrderarraySquare order data
add_filter('squarewoosync_order_discounts', function($discounts, $order, $squareOrder) {
    // Modify discounts during import
    return $discounts;
}, 10, 3);

squarewoosync_order_status_mapping

Custom status mapping for imported orders.

Location: includes/Woo/CreateOrder.php

ParameterTypeDescription
$newOrderStatusstringWooCommerce order status
$squareOrderStatestringSquare order state
$orderWC_OrderWooCommerce order
$squareOrderarraySquare order data
add_filter('squarewoosync_order_status_mapping', function($newOrderStatus, $squareOrderState, $order, $squareOrder) {
    // Custom status mapping
    if ($squareOrderState === 'OPEN') {
        return 'on-hold';
    }
    return $newOrderStatus;
}, 10, 4);

sws_discount_priority

Set the priority for discount calculations.

Location: includes/Discount/DiscountApplicator.php

ParameterTypeDescription
$priorityintCalculation priority (default: 99)
add_filter('sws_discount_priority', function($priority) {
    return 50; // Run earlier in the calculation chain
});

Product Filters

squarewoosync_skip_variation_sync

Control whether specific variations should sync.

Location: includes/Woo/SyncProduct.php

ParameterTypeDescription
$skipboolWhether to skip this variation
$variation_idintVariation product ID
$variationWC_ProductVariation object
add_filter('squarewoosync_skip_variation_sync', function($skip, $variation_id, $variation) {
    if ($variation && !$variation->is_in_stock()) {
        return true; // Skip this variation
    }
    return $skip;
}, 10, 3);

squarewoosync_skip_square_product_import

Skip importing specific products from Square.

Location: includes/Jobs/WebhookProcessJob.php, includes/Square/SquareImport.php

ParameterTypeDescription
$skipboolWhether to skip (default: false)
$productarraySquare product data
add_filter('squarewoosync_skip_square_product_import', function($skip, $product) {
    // Skip products with specific naming pattern
    if (strpos($product['item_data']['name'], '[INTERNAL]') !== false) {
        return true;
    }
    return $skip;
}, 10, 2);

squarewoosync_defer_thumbnail_generation

Control thumbnail generation during product import.

Location: includes/Woo/CreateProduct.php

ParameterTypeDescription
$deferboolWhether to defer (default: true)
add_filter('squarewoosync_defer_thumbnail_generation', function($defer) {
    return false; // Generate thumbnails immediately
});

Customer Filters

squarewoosync_create_square_customer_payload

Modify customer data before creating a Square customer.

Location: includes/Customer/Customers.php

ParameterTypeDescription
$payloadarrayCustomer data payload
$user_idintWordPress user ID
$settingsarrayPlugin settings
add_filter('squarewoosync_create_square_customer_payload', function($payload, $user_id) {
    $payload['note'] = 'VIP Customer';
    return $payload;
}, 10, 2);

squarewoosync_square_customer_payload

Modify customer payload during sync operations.

Location: includes/Customer/Customers.php

ParameterTypeDescription
$payloadarrayCustomer data payload
$customerWP_UserWordPress user object
$settingsarrayPlugin settings
add_filter('squarewoosync_square_customer_payload', function($payload, $customer, $settings) {
    // Add custom note during sync
    $payload['note'] = 'Synced from WooCommerce';
    return $payload;
}, 10, 3);

Queue & System Filters

sws_api_controllers

Register custom REST API controllers.

Location: includes/REST/Api.php

ParameterTypeDescription
$controllersarrayArray of controller classes
add_filter('sws_api_controllers', function($controllers) {
    $controllers[] = 'My_Custom_Controller';
    return $controllers;
});

sws_redis_config

Configure Redis connection for queue processing.

Location: includes/Queue/QueueConnectionResolver.php

ParameterTypeDescription
$configarrayRedis configuration
add_filter('sws_redis_config', function($config) {
    $config['host'] = 'redis.example.com';
    $config['port'] = 6380;
    return $config;
});

sws_is_local_development

Override local development detection for queue configuration.

Location: includes/Queue/QueueConnectionResolver.php

ParameterTypeDescription
$is_localboolWhether environment is local
add_filter('sws_is_local_development', function($is_local) {
    return false; // Force production queue behavior
});

sws_allowed_job_classes

Restrict or extend allowed job classes for queue security.

Location: includes/Queue/QueueConnectionResolver.php

ParameterTypeDescription
$allowed_jobsarrayArray of allowed job class names
add_filter('sws_allowed_job_classes', function($allowed_jobs) {
    $allowed_jobs[] = 'My_Custom_Job';
    return $allowed_jobs;
});

Best Practices

Always Return Values

Filters must return the modified (or unmodified) data:

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Make modifications
    $order_data['order']['metadata']['custom'] = 'value';
 
    // Must return the data!
    return $order_data;
}, 10, 2);

Validate Data

Always check data types before modifying:

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    if (!$wc_order instanceof WC_Order) {
        return $order_data;
    }
    // Safe to proceed
    return $order_data;
}, 10, 2);

Handle Errors Gracefully

Wrap modifications in try-catch blocks:

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    try {
        // Your modifications
    } catch (Exception $e) {
        error_log('SquareSync filter error: ' . $e->getMessage());
    }
    return $order_data;
}, 10, 2);