Bookly does not natively sync appointments to the Square calendar system. When a customer books a service through Bookly and pays via Square, the payment processes successfully but no corresponding appointment is created in Square. Closing this gap requires a custom script that bridges Bookly's appointment data to the Square Appointments API.
This pattern was identified during the [1] project, where a test transaction confirmed the payment reached Square ($26 charged, status: completed) but the associated Nov 19 appointment was absent from the Square calendar.
| Layer | Behavior |
|---|---|
| WooCommerce + Bookly | Captures booking details and processes payment via Square gateway |
| Square Payments | Receives and records the payment transaction correctly |
| Square Appointments | Not notified — appointment is never created |
Bookly's Square payment integration handles transactions only. It has no built-in hook into the Square Appointments API, which is a separate product within the Square platform.
A custom WordPress script (likely added to functions.php or a dedicated plugin file) listens for Bookly appointment confirmation events and makes an authenticated call to the Square Appointments API to create the corresponding appointment.
Customer completes Bookly checkout
↓
WooCommerce order created, Square payment charged
↓
Custom bridge script fires on Bookly appointment confirmation hook
↓
Script calls Square Appointments API with service, staff, datetime, and customer data
↓
Appointment appears in Square calendar
POST /v2/bookings endpoint (Square's native booking creation call).A Square developer account is required to generate API keys. Square restricts developer account creation to the merchant account owner — team members cannot create one independently.
Established pattern for this project:
- The agency principal (Chris) holds developer access and creates the API key.
- The key is stored in shared client credentials (e.g., shared logins vault).
- The developer (Isahaque) uses the key to authenticate the bridge script during build and testing.
⚠️ Before creating or modifying API keys in a client's Square developer account, notify the client (e.g., email to Kimberly) explaining the purpose. Include a flow diagram and any supporting screenshots to avoid surprise or concern about unauthorized access.
This bridge is one component of a broader split-payment checkout architecture on the LaMarie project. See [2] for the companion pattern that handles charging only the product at checkout while deferring service payment.
POST /v2/bookings