Description #

The squarewoosync_prepare_order_data filter allows you to modify Square order data before it’s sent to the Square API when creating orders from WooCommerce.

Location #

includes/REST/OrdersController.php:539

Parameters #

$order_data (array) #

The prepared Square order data array that will be sent to the Square API. This follows the Square Orders API structure.

$order (WC_Order) #

The WooCommerce order object being synchronized to Square.

When This Filter Runs #

This filter is triggered when:

• A WooCommerce order is placed through checkout
• An order status changes to a configured sync status
• An order is manually synced to Square via admin actions
• The Square payment gateway processes an order

Order Data Structure #

The $order_data array typically contains:

[
    'order' => [
        'location_id' => string,        // Square location ID
        'customer_id' => string,        // Square customer ID
        'metadata' => [                 // Custom metadata
            'woo_order_id' => string
        ],
        'state' => string,              // OPEN, COMPLETED, CANCELED, etc.
        'ticket_name' => string,        // Display name
        'reference_id' => string,       // Reference identifier
        'source' => [
            'name' => string            // Order source
        ],
        'line_items' => [...],          // Array of line items
        'taxes' => [...],               // Array of taxes
        'discounts' => [...],           // Array of discounts
        'fulfillments' => [...]         // Fulfillment details
    ]
]

Please reference https://developer.squareup.com/reference/square/orders-api/create-order for Square order object and available keys. 

Usage Examples #

Add Custom Metadata #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Add custom metadata fields
    $order_data['order']['metadata']['store_id'] = get_current_blog_id();
    $order_data['order']['metadata']['customer_type'] = get_user_meta($wc_order->get_customer_id(), 'customer_type', true);
    $order_data['order']['metadata']['order_source'] = 'website';

    return $order_data;
}, 10, 2);

Modify Line Items #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Add notes to each line item
    foreach ($order_data['order']['line_items'] as &$line_item) {
        // Add special instructions from order item meta
        foreach ($wc_order->get_items() as $wc_item) {
            if ($wc_item->get_name() === $line_item['name']) {
                $special_instructions = $wc_item->get_meta('_special_instructions');
                if ($special_instructions) {
                    $line_item['note'] = $special_instructions;
                }
            }
        }
    }

    return $order_data;
}, 10, 2);

Add Custom Reference ID #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Create a custom reference ID format
    $order_data['order']['reference_id'] = sprintf(
        '%s-%s-%d',
        get_bloginfo('name'),
        date('Ymd'),
        $wc_order->get_id()
    );

    return $order_data;
}, 10, 2);

Add Custom Discounts #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Add a loyalty discount if customer is VIP
    if (get_user_meta($wc_order->get_customer_id(), 'vip_customer', true)) {
        $order_data['order']['discounts'][] = [
            'name' => 'VIP Customer Discount',
            'percentage' => '10',
            'scope' => 'ORDER'
        ];
    }

    return $order_data;
}, 10, 2);

Modify Fulfillment Details #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Add pickup details if it's a pickup order
    $shipping_method = $wc_order->get_shipping_method();

    if (strpos($shipping_method, 'pickup') !== false) {
        $order_data['order']['fulfillments'][] = [
            'type' => 'PICKUP',
            'state' => 'PROPOSED',
            'pickup_details' => [
                'recipient' => [
                    'display_name' => $wc_order->get_formatted_billing_full_name(),
                    'phone_number' => $wc_order->get_billing_phone(),
                    'email' => $wc_order->get_billing_email()
                ],
                'schedule_type' => 'SCHEDULED',
                'pickup_at' => date('c', strtotime('+2 hours'))
            ]
        ];
    }

    return $order_data;
}, 10, 2);

Add Source Information #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Track order source for analytics
    $source = 'Web';

    // Check if order was placed from mobile
    if (wp_is_mobile()) {
        $source = 'Mobile Web';
    }

    // Check if order came from specific campaign
    if ($utm_source = $wc_order->get_meta('_utm_source')) {
        $source .= ' - ' . $utm_source;
    }

    $order_data['order']['source']['name'] = $source;

    return $order_data;
}, 10, 2);

Conditional Order State #

add_filter('squarewoosync_prepare_order_data', function($order_data, $wc_order) {
    // Set order state based on payment method
    if ($wc_order->get_payment_method() === 'cod') {
        $order_data['order']['state'] = 'DRAFT';
    } elseif ($wc_order->is_paid()) {
        $order_data['order']['state'] = 'COMPLETED';
    }

    return $order_data;
}, 10, 2);

Important Notes #

1. Validation: Square API will validate the data structure. Ensure any modifications comply with Square’s API requirements.
2. Required Fields: Don’t remove required fields like location_id or line_items as this will cause the API call to fail.
3. Currency: Square uses the smallest currency unit (cents). Ensure monetary values are properly formatted.
4. Error Handling: Invalid modifications will cause the Square API call to fail. Check the plugin’s logs for error details.
5. Performance: This filter runs during checkout, so avoid heavy operations that could slow down the order process.

Related Hooks #

• squarewoosync_square_order_created – Action fired after successful Square order creation
• woocommerce_checkout_order_processed – WooCommerce hook that triggers the sync
• woocommerce_order_status_changed – Triggers sync on status change

See Also #

• Square Orders API Documentation
• WC_Order Class Reference