Bookedit × Airship — Integration & Onboarding Guide

This page is the live source of truth. Every change here ships with the next deploy of the Airship dashboard.

1. What this integration does

Bookedit syncs booking customers from Booked.it into Airship UK as marketing contacts, per venue, in near real-time.

• One Booked.it booking → one Airship contact (deduped by email + venue Unit ID)
• Multi-tenant: each venue has its own BookedIt Provider ID and Airship Unit ID
• Bookings with @booked.it placeholder emails are filtered out; everything else is forwarded

2. Architecture

 Booked.it API  ──fetch──▶  Bookedit (Lovable Cloud)  ──push──▶  Airship UK API
                                        ▲                                  │
                                        └──── monitoring webhook ◀─────────┘

• Scheduler runs every minute via pg_cron → automated-sync-scheduler
• Fetch from Booked.it: one venue per tick, rotated by unix_minute % venue_count (so each venue is hit every N minutes; well within the 15-minute SLA)
• Shared session: the BookedIt cookie is pre-warmed once per tick and reused across the rotation, avoiding the 15-second login throttle
• Push to Airship: sync-to-airship runs every tick, picking up newly-fetched bookings and any prior failures (up to 5 retries per booking)
• Health pings: the IntegrationOps monitoring webhook is notified on each successful or failed sync

3. Authentication

• BookedIt: shared API key + session cookie, refreshed on demand by _shared/booked-it-session.ts
• Airship: per-venue credentials scoped to the venue's Airship Unit ID
• No end-user OAuth — credentials live in Lovable Cloud secrets and the integrations table

4. Onboarding a venue

1. Open the dashboard and click Add Integration
2. Enter the venue name and its BookedIt Provider ID
3. Pick the matching Airship Unit from the dropdown (loaded live from Airship UK)
4. Click Test Connection — both BookedIt and Airship credentials are validated
5. Save. The venue joins the scheduler rotation on the next tick

The venue's first sync may take a few minutes depending on its position in the rotation. Use Sync Now on the venue detail page if you want to force an immediate pull.

5. Data flow & rules

• Deterministic UUIDs: every booking row uses a UUID derived from provider_id + order_id, so re-fetching the same booking is idempotent
• BigInt safe: large BookedIt IDs are serialized with jsonStringifyWithBigInts before any JSON.stringify call
• Sync tracking: last_synced_to_airship is the canonical field — never airship_synced_at
• Email filter: any address ending in @booked.it is dropped before push (placeholder data); all other emails are forwarded as-is
• Status rule: integrations.status is owned by sync-to-airship based on the unique-customer rule, not by transient BookedIt fetch errors

6. Sync cadence & retries

• Scheduler tick: every minute
• Per-venue fetch cadence: every N minutes where N = number of active venues
• Push to Airship: every tick (covers fresh bookings + retries)
• Max retries per booking: 5, after which the booking is marked failed and surfaced in the Failed Bookings section

7. Monitoring & health

• Green: recent successful syncs, unique customers flowing
• Amber: warnings (e.g., no new customers in expected window) — review on the venue detail page
• Red: persistent failures — check the Failed Bookings section and edge function logs
• last_sync and last_sync_status on the integration row reflect the most recent fetch attempt
• The IntegrationOps webhook receives a payload on every sync for cross-app dashboards

8. Historical import

Past bookings can be backfilled via the Import Historical Data page (/import). Upload a CSV and the importer reuses the same deterministic-UUID and email-filter logic, so it is safe to re-run.

9. Troubleshooting

Need to update this doc? Edit src/docs/onboarding.md in the repo. Changes ship with the next deploy.