wiki/knowledge/woocommerce/square-bookly-sync.md · 679 words · 2026-04-05

Square-Bookly Sync — Instantaneous API Integration

Overview

When running a booking system that spans both Square (used directly by staff or clients via the Square app) and a WordPress/Bookly front-end, the risk of double-bookings is a natural concern. The Square-Bookly integration resolves this through a real-time, bidirectional API sync — there is no polling delay or scheduled batch update. Changes on either side propagate immediately.

This pattern was confirmed during a technical review for the ^[1] project, where the team needed to ensure that bookings made through the Square app by staff would not conflict with simultaneous bookings made through the LMB website's Bookly widget.

How It Works

Bidirectional, Instantaneous Sync

The Square-Bookly connection operates via the Square API. When a booking is created or modified on either platform:

The originating platform writes the booking to its own data store.
The API call propagates the change to the other platform immediately.
If a conflict exists (e.g., two users attempting to book the same slot at nearly the same time), Square's backend throws an error to the second request.

There is no meaningful delay between a booking on one platform and its reflection on the other. An earlier assumption of a ~5-minute sync lag was ruled out by the developer (Isahaque Mahmud) during the La Marie Beauty technical call.

Admin-Side Calendar Updates

The sync is not limited to customer-facing bookings. If an admin updates the calendar directly within the Square dashboard (e.g., blocking time, rescheduling), that change is also pushed to Bookly automatically. This means staff can manage their schedule from Square without creating stale availability windows on the website.

Conflict Resolution

True simultaneous conflicts (two users completing a booking at the exact same millisecond) are handled by Square's backend, which will reject one of the two requests. This is the standard behavior for any API-backed booking system and does not require custom handling at the Bookly or WooCommerce layer.

Architecture Context

The full stack for this integration is:

Customer (website) → Bookly → WooCommerce → Square API
Staff (mobile/desktop) → Square App → Square API → Bookly

The Square API is the authoritative source of truth for availability. Bookly reads from and writes to Square via API key, which must be provisioned by the developer (not by the client's Square account holder).

Implementation Notes

API Key: A Square API key must be created and configured for the Bookly/WooCommerce/Square integration. This is a developer task (see ^[2]).
No custom sync code required: The instantaneous sync is a native capability of the Square-Bookly integration when properly configured. No custom polling or webhook code is needed for availability sync specifically.
Custom PHP is still required elsewhere: The sync itself is handled by the integration, but the payment logic (card-on-file for services, full charge for products) requires custom PHP. See ^[3].

Limitations

Capability	Supported
Real-time availability sync (Square → Bookly)	✅ Yes
Real-time availability sync (Bookly → Square)	✅ Yes
Admin calendar updates synced to Bookly	✅ Yes
Conflict resolution for simultaneous bookings	✅ Handled by Square backend
Custom sync delay configuration	❌ Not applicable (always instant)
Syncing payment status between platforms	❌ Requires custom PHP

Evidence

Confirmed by developer Isahaque Mahmud on the La Marie Beauty technical implementation call (April 2026). The team had previously assumed a potential 5-minute delay; this was corrected during the call.

"It will sync instantly. There is no delay." — Isahaque Mahmud

"If the calendar is updated for Square on the admin dashboard in Square, it's automatically updated in Bookly as well." — confirmed by Isahaque Mahmud

^[4]
^[5]
^[3]
^[6]