Aucip Book Calendar Sync documentation

Google Calendar and Outlook sync for Aucip Book

• Overview and requirements
• Setup
• How it works
• Licence and FAQ

Overview and requirements

Aucip Book Calendar Sync 1.0.12 is an add-on for Aucip Book. It does nothing on its own: Requires Aucip Book 1.1.5 or newer.

It connects each staff member's Google Calendar or Microsoft Outlook (Microsoft 365 / Outlook.com, via Microsoft Graph) calendar to Aucip Book in both directions:

• Busy time blocks slots. Busy events in the staff member's calendar remove them from the booking slots.
• Bookings go to the calendar. Each booking is written to that calendar when it is created, rescheduled or cancelled.

Calendars sync every 5 minutes. To close that gap, each booked slot is also re-checked live against the staff member's calendar when the order is placed.

Requirements

Outbound connections

Only oauth2.googleapis.com, www.googleapis.com, login.microsoftonline.com, graph.microsoft.com, and aucip.com for the licence and updates.

Setup

1. Install and activate aucip-book-calendar-sync-1.0.12.zip (Plugins → Add New → Upload Plugin). Requires Aucip Book 1.1.5 or newer, already active.
2. Open Bookings → Settings → Calendar sync and copy the Redirect URI (https://your-site/wp-json/aucip-cal-sync/v1/oauth).

Google Calendar

1. In Google Cloud Console, create or pick a project and enable the Google Calendar API.
2. Configure the OAuth consent screen : app name, support email, authorised domain. User type External for Gmail staff, Internal for Workspace-only teams. Add the scopes openid, email, .../auth/calendar.calendarlist.readonly and .../auth/calendar.events.
3. While the app is in "Testing", add each staff member as a Test user , or publish the app. Google may ask for verification because calendar scopes are sensitive.
4. Create an OAuth client ID of type Web application and add the Redirect URI under Authorised redirect URIs.
5. Paste the Client ID and Client secret under Providers → Google Calendar and click Save settings.

Microsoft Outlook (Graph)

1. In Microsoft Entra, App registrations → New registration. Account types: any organisational directory and personal Microsoft accounts (tenant common), or "this directory only" with your tenant ID. Redirect URI: platform Web , paste the Redirect URI.
2. Certificates & secrets → New client secret. Copy the Value at once and note its expiry.
3. API permissions → Microsoft Graph → Delegated: offline_access, openid, email, User.Read, Calendars.ReadWrite. Admin consent is optional.
4. Paste the Application (client) ID and secret under Providers → Microsoft Outlook , set the Tenant , and click Save settings.
5. When the secret expires, paste a new one. Connections show Sign-in expired until you do.

Connect staff

• Admins: Bookings → Staff → (person) , section Calendar sync at the bottom: Connect Google Calendar or Connect Microsoft Outlook , then sign in as that person.
• Booking Staff users connect their own calendar under Bookings → My calendar sync.
• After connecting, the main calendar is selected; you can pick another editable calendar. The first read starts at once and upcoming bookings are pushed.

How it works

Busy time (pull)

• Every 5 minutes (Action Scheduler) each connected calendar is read from yesterday up to Aucip Book's "maximum days ahead" (between 14 and 90 days). Busy intervals are cached; slot search, holds and reschedules read only this cache.
• Events marked Free are ignored, and so are the add-on's own booking events.
• All-day events: block only when marked Busy (default), always block, or ignore.
• If a calendar can no longer be read (403/404), its cached busy time is cleared and the status shows Needs attention.

Live re-check at checkout

• When an order is placed (classic and block checkout), each booked slot is checked against the staff member's calendar, bypassing the cache. If it was just taken, the order is refused before payment , the appointment is removed from the cart, and the customer is asked to choose another time.
• The whole cart shares one 4-second budget (filter aucip_cal_live_check_timeout, 1–10 s). No retries.
• If the calendar API is slow, unreachable or errors, the cached busy times are used. Each fallback is logged, shown as an admin notice, and emailed to the site admin (at most once per hour per staff member).
• Manual bookings made in the admin calendar are re-checked the same way; a conflict is shown in the booking dialog.
• Reschedules and moves: a customer reschedule or a booking dragged to a new time in the admin calendar is re-checked live as well. The booking's own calendar event is ignored, so moving it to an overlapping time isn't blocked by itself; a real conflict stops the move with "…so the appointment was not moved."
• Known limits: for Microsoft, only the account's default calendar is checked live (other calendars are covered by the 5-minute sync). During a provider outage the fallback uses busy times up to 5 minutes old (longer while syncs back off).

Bookings (push)

• Created, confirmed, rescheduled or cancelled bookings create, update or delete the calendar event in the background.
• A deleted event is recreated; a booking moved to another staff member moves to their calendar; changing the calendar moves upcoming events.
• Event title template: default {service} · {customer_name}. Customer email, phone, order number and notes are only added to the description if you enable that option (off by default).

Errors and status

• 401: token refreshed once and retried. invalid_grant or an undecryptable token: Sign-in expired , reconnect needed.
• 429, 5xx or network failure: backoff of 1, 2, 4 … minutes, capped at 1 hour and never sooner than Retry-After. Push jobs retry up to 6 times.
• Everything goes to the sync log , newest first (kept 14 days by default, 1–90).
• Sync now reads the calendar in the background; the status page reloads up to 3 times to show the result, then shows "Still running" and points to the sync log.

Private .ics feed

Each staff member gets a private feed (/?aucip_cal_ics=<staff>.<token>) covering the last 30 and next 180 days. It works without connecting an account. Make a new link rotates it.

Disconnect

Revokes the Google token (Microsoft has no revoke endpoint; tokens are deleted locally), deletes stored tokens and cached busy time, and can optionally remove upcoming booking events from the calendar. The .ics feed keeps working.

Security

OAuth tokens and client secrets are encrypted with libsodium (key AUCIP_CAL_SYNC_KEY in wp-config.php, or derived from WordPress salts). Sign-in uses single-use, user-bound state and PKCE (S256). Admin actions check nonces and capabilities.

Licence and FAQ

Licence

One licence = one end product. Free local installs (localhost/.test) plus up to 3 staging installs on staging subdomains per licence; staging doesn't count against your production domain. Staging means staging., dev., test., uat., preview.* or a tunnel such as ngrok (tunnel seats expire after 7 days unused). Each additional end product needs another licence. Installation is a paid add-on, sold separately.

Updates are free while your licence is valid. Support is 6 months and can be renewed. Code licence: GPLv2.

Launch offer: use coupon SYNCLAUNCH20 for 20% off, valid for 30 days after launch.

Daily check. Once a day the add-on sends a signed licence check to aucip.com containing only the key, product, domain, instance id and version. Never customer or booking data. Grace and lock. If the check fails (no key, expired or revoked, bad signature, network down), a 14-day grace period starts with a countdown notice. After that, the Calendar sync settings tab, staff section actions and updates lock; the licence form stays available. What keeps working. Pulls, pushes, slot blocking, booking pages and .ics feeds keep working. A valid activation or re-check unlocks everything at once.

FAQ

Does it work without Aucip Book? No. Requires Aucip Book 1.1.5 or newer. How fast does a new calendar event block a slot? Within 5 minutes through the sync, and at once at checkout through the live re-check. Push notifications are planned for 1.1. Do I need a Google or Microsoft developer account? You need your own OAuth client (free to create). Calls go straight from your site to Google/Microsoft. Can staff connect their own calendar? Yes: Booking Staff users use Bookings → My calendar sync. What if Google or Microsoft is down at checkout? Cached busy times are used, so bookings still work, and the admin is alerted. Can staff without Google/Outlook see their bookings? Yes, with the private .ics feed (Apple Calendar, Thunderbird, phones). What is deleted on uninstall? Only if "Delete connections, cache and log when the plugin is deleted" is on: the add-on's 3 tables, settings, booking meta, scheduled jobs and transients.

Tests (included in the zip)

• Unit: composer install && vendor/bin/phpunit (Google/Graph mocked). Coding standards: vendor/bin/phpcs.
• Integration (disposable test site only): wp eval-file wp-content/plugins/aucip-book-calendar-sync/tests/integration/fixes-103.php; prints PASS/FAIL and ends with ALL PASS.

Changelog

• 1.0.5 (12 Oct 2026): "Sync now" in demo mode or with placeholder tokens finishes at once (status In sync, a "Demo mode: calendar sync is simulated" notice, no calls to Google or Microsoft); the Syncing pill can no longer stay stuck: the status page reloads at most 3 times, then shows "Still running" with a hint to check the sync log.
• 1.0.4 (12 Oct 2026): customer reschedules and admin calendar moves are re-checked live too (with Aucip Book 1.1.1), ignoring the booking's own calendar event, so a move that overlaps its old time isn't blocked by itself; licence help text uses the standard wording; the licence panel lists exactly what the daily check sends; sync log newest first; event dot stays inline on phones; demo mode and placeholder tokens make no calls to Google or Microsoft.
• 1.0.3 (12 Oct 2026): one 4-second budget for the whole cart's live re-check; checkout failures no longer change sync status; admin notice and email on cache fallback; licence warning shown once on the tab; admin manual bookings re-checked live; Microsoft default-calendar limit documented.
• 1.0.2: live checkout re-check; requires Aucip Book 1.1.0; restyled to Aucip Book's admin; 44 px mobile tap targets; PKCE; DST all-day fix; customer details off by default.
• 1.0.1: busy times read once per staff member per request.
• 1.0.0: first release.

Aucip Book Calendar Sync · aucip.com