---
title: Bookly-Square Appointment Sync via Custom API Bridge
type: article
created: '2026-04-05'
updated: '2026-04-05'
source_docs:
- raw/2025-11-06-lmb-touch-base-99674004.md
tags:
- integrations
- bookly
- square
- api
- wordpress
- woocommerce
- custom-script
layer: 2
client_source: null
industry_context: null
transferable: true
---

# 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 [[wiki/clients/lamarie/_index|LaMarie]] 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

---

## Related Context

This bridge is one component of a broader split-payment checkout architecture on the LaMarie project. See [[wiki/knowledge/integrations/woocommerce-bookly-split-payments|WooCommerce + Bookly Split Payment via functions.php]] for the companion pattern that handles charging only the product at checkout while deferring service payment.

---

## References

- [[wiki/clients/lamarie/_index|LaMarie Client Overview]]
- [[wiki/meetings/2025-11-06-lmb-touch-base|LMB Touch Base — LaMarie Checkout & Bookly-Square Integration]] (source meeting)
- Square Appointments API docs: `POST /v2/bookings`