Sync Orders Between Square and WooCommerce

The WooCommerce Square extension includes an opt-in bidirectional order fulfillment synchronization feature that allows merchants to seamlessly manage orders between their WooCommerce store and Square Dashboard. This feature is disabled by default and must be explicitly enabled in “Settings”.

What Order Fulfillment Sync Does

↑ Back to top

When enabled, the bidirectional order fulfilment sync provides:

• WooCommerce → Square: Orders created in WooCommerce automatically sync to Square with fulfillment details
• Square → WooCommerce: Order status updates from Square (such as marking an order “Completed”) sync back to WooCommerce
• Seamless Integration: Orders appear in both platforms with consistent order fulfillment statuses

Key Benefits

↑ Back to top

• Centralized Order Management: View and track orders across online and in-person sales in one place
• Automatic Status Updates: Fulfillment changes in Square automatically reflect in WooCommerce. 
• Fulfillment Visibility: See fulfilment options in the Square Dashboard for online orders
• Continuous Sync: Automatic polling (default: every 15minutes) keeps both platforms in sync
• Merchant Control: Disabled by default, order sync requires explicit opt-in before activation.

How It Works

↑ Back to top

Syncing Online orders created in WooCommerce

↑ Back to top

1. WooCommerce to Square Order Sync

↑ Back to top

When a customer places an order through your WooCommerce store using Square:

• Order automatically syncs to Square Dashboard
• Fulfillment details are included (pickup/shipment information)
• Order appears in Square with the “Fulfillment” button available
• Merchants can view and manage fulfillment directly in Square

2. Square to WooCommerce Order Sync

↑ Back to top

When an order is fulfilled in the Square Dashboard:

• Square order status changes to Completed
• WooCommerce automatically syncs this status change
• WooCommerce order status updates to Completed
• Direct link to Square Order ID is added to WooCommerce order notes

3. Preventing Infinite Order Sync Loops

↑ Back to top

The system prevents infinite sync loops by:

• Only syncing fulfillment updates from Square back to WooCommerce
• Not syncing WooCommerce order updates back to Square

Setup and Configuration

↑ Back to top

Enabling Order Synchronization

↑ Back to top

1. Go to WooCommerce → Settings → Square
2. Navigate to the Configure Sync Settings section
3. Check the “Enable bidirectional order fulfillment sync” checkbox
4. Click “Apply Changes” to save

Configuration Options

↑ Back to top

• Default State: Disabled (must be enabled in “Settings”)
• Sync Interval: 15 minutes (configurable via filters)
• Payment Methods: Works with all Square payment methods
• Order Types: All WooCommerce orders processed through Square

Technical Details

↑ Back to top

Sync Process

↑ Back to top

1. Order Creation: WooCommerce order syncs to Square with fulfillment data
2. Polling System: Square orders are checked every 15 minutes for updates (default sync interval)
3. Status Detection: Only “Completed” and “Cancelled” orders trigger sync
4. Update Sync: WooCommerce order status updates automatically

API Integration

↑ Back to top

• Uses Square’s Orders API for reliable state management
• Leverages Action Scheduler for background processing
• Implements proper error handling and logging

Performance Considerations for High-Volume Stores

↑ Back to top

Understanding the 1,000 Order Limit

↑ Back to top

The order fulfillment sync implementation has a limit of 1,000 orders per action run. For stores getting thousands of orders in a few minutes, this can lead to missed syncs if orders are updated between polling cycles.

Recommended Configuration for Stores with High Order Volumes

↑ Back to top

If you process 1,000+ orders daily or have a high-volume store, consider reducing the polling interval to ensure no orders are missed:

Reduce to 5-minute intervals

add_filter( 'wc_square_order_polling_interval_seconds', function( $interval ) {
    // Change from 15 minutes to 5 minutes
    return 5;
} );

Monitoring and Optimization

↑ Back to top

• Monitor Action Scheduler: Check /wp-admin/admin.php?page=wc-status&tab=action-scheduler for pending sync events
• Review Logs: Monitor WooCommerce logs for sync results
• Adjust Based on Performance: Start with 5-minute intervals and adjust based on server performance
• Consider Server Resources: More frequent polling increases server load

Advanced Configuration

↑ Back to top

Overriding Sync Behavior

↑ Back to top

Customize sync behavior with WordPress filters:

add_filter( 'wc_square_order_fulfillment_sync_enabled', function( $enabled ) {
    // Custom logic to determine if sync should be enabled
    return $enabled;
} );

Limitations and Considerations

↑ Back to top

Current Limitations:

• Refund Handling: Refund scenarios created at Square are not synced
• Order Creation: Only syncs existing WooCommerce orders to Square
• Status Types: Only “Completed” and “Cancelled” statuses trigger sync

Troubleshooting

↑ Back to top

Check the Troubleshooting page for troubleshooting issues with order sync.

Frequently Asked Questions

↑ Back to top

Check the FAQ section for order sync.