Bookly-Square Appointment Sync via Custom API Bridge

Overview

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.

The Problem

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.

Solution: Custom API Bridge Script

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.

High-Level Flow

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

Key Integration Points

Bookly hook: Listen for the post-booking confirmation event to extract appointment details (service, staff member, date/time, customer info).
Square Appointments API: POST /v2/bookings endpoint (Square's native booking creation call).
Authentication: Requires a Square API key scoped to the target merchant account.

Access & Credentials

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.

Implementation Checklist

[ ] Agency principal creates a new Square API key in the client's developer account
[ ] API key added to shared credentials store
[ ] Developer documents required API scopes and endpoint details
[ ] Custom bridge script built and deployed to WordPress environment
[ ] End-to-end test: complete a Bookly booking → verify appointment appears in Square calendar
[ ] Client notified of API key creation and integration approach before go-live

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.

References

^[3]
^[4] (source meeting)
Square Appointments API docs: POST /v2/bookings