Bookly-to-Square API Sync Speed & Double-Booking Prevention

Overview

When Bookly handles appointment scheduling and Square serves as the staff calendar source of truth, there is an inherent sync delay between the two systems. This delay creates a window during which two clients could book the same appointment slot — one through the WooCommerce/Bookly flow and one directly through Square's native booking interface. Minimizing this window is critical for any architecture that runs parallel booking channels.

This issue surfaced during the ^[1] project, where the confirmed stack is WooCommerce (checkout) + Bookly (scheduling UI) + Square (staff calendar source of truth), with Zapier removed.

The Problem

The default Bookly-to-Square API sync interval is approximately 15 minutes. During this window:

• A slot booked via WooCommerce/Bookly is not yet reflected in Square.
• A client (or staff member) booking directly through Square's native app could claim the same slot.
• The result is a double-booking with no automated conflict resolution.

This is not a purely theoretical edge case — La Marie Beauty retains clients who book directly through the Square app, making the parallel-channel conflict a real operational risk.

Investigation Required

The following questions need to be resolved by the implementing engineer (Ishak, in the La Marie Beauty context):

1. Is the 15-minute delay a hard default or configurable? Determine whether Bookly's Square integration polls on a fixed schedule or can be triggered by webhook events.
2. Can webhook-based sync be configured? If Bookly supports outbound webhooks or event-driven API calls on appointment creation, the sync could be reduced to near real-time (~1 minute or less).
3. What is Square's API rate limit tolerance? More frequent sync calls must stay within Square's API rate limits to avoid throttling.

"I would be curious if it is like on a default timer of 15 minutes or if we do have the ability to customize like the webhook events. And that's how we can get like, I mean, it doesn't have to be like instantaneous, like, you know, within two seconds. But even something like a minute is perhaps better." — Kimberly Gehrmann, La Marie Beauty call 2025-11-11

Recommended Approach

• Target sync latency: ~1 minute or less.
• Preferred mechanism: Event-driven webhook or API call triggered on Bookly appointment creation, rather than a polling interval.
• Fallback: If near-real-time sync is not achievable natively, evaluate a lightweight custom hook that fires a Square API call immediately upon Bookly booking confirmation.
• Do not rely on Zapier — it has been removed from this architecture and reintroducing it adds fragility and latency.

Mitigation if Sync Cannot Be Reduced

If the sync delay cannot be reduced below an acceptable threshold, consider these compensating controls:

• Slot locking: Hold the slot in Bookly immediately on booking initiation (before payment completes) to reduce the conflict window on the Bookly side.
• Conflict detection on checkout: Query Square availability at the moment of WooCommerce checkout submission and abort if the slot is no longer free.
• Staff training: Advise La Marie Beauty staff not to manually block or book slots in Square during peak web-booking hours until sync is confirmed reliable.

Architecture Context

WooCommerce (checkout) ──► Bookly (scheduling) ──► Square (calendar source of truth)
                                                         ▲
                                              Square native app bookings

Square remains the authoritative calendar. Bookly reads availability from Square and must write confirmed appointments back to Square promptly. The sync direction is Bookly → Square, not bidirectional in the problematic sense — but Square's native booking channel creates the competing write path.

See also:
- ^[2]
- ^[3]
- ^[4]