> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: External Calendar Integration ## Article: External Calendar Integration ## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills/external-calendar-integration.md ## Article Content: # Technical Step-by-Step Instructions: Connecting External Calendars (Google, Microsoft, Apple) to Wix Bookings (Real-World, API-First) ## Description Below are the recommended steps to successfully connect and sync external calendars (Google Calendar, Microsoft Outlook, Apple Calendar) with Wix Bookings, with real-world troubleshooting and fixes for common API issues. This recipe covers the complete OAuth flow, sync configuration, and verification procedures. --- ## Prerequisites ### Required Features and Apps Before connecting external calendars, ensure the following requirements are met: 1. **Wix Bookings** - Core app must be installed and configured 2. **Premium Plan** - External calendar integration requires premium features enabled 3. **Active Staff or Business Schedule** - Target schedule must exist for connection ### Premium Feature Validation **CRITICAL**: External calendar integration is a **premium feature**. If not enabled, you'll receive a 403 error with `"PREMIUM_FEATURE_NOT_ENABLED"` code. **Verification Steps:** 1. Attempt to list providers - should return Google, Microsoft, Apple 2. If 403 error occurs, upgrade plan or enable premium features 3. Contact Wix support if premium features aren't accessible after upgrade ### App Installation Process If you encounter app-related errors, install the required apps using the Apps Installer API. **For detailed app installation procedures, refer to:** - [Apps Installer API Documentation](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md) - Business setup recipes for comprehensive app installation workflows ## Overview Wix External Calendar integration allows bidirectional sync between Wix schedules and external calendar providers. The system supports: - **Google Calendar** - OAuth authentication, primary calendar sync - **Microsoft Outlook/365** - OAuth authentication, specific calendar selection - **Apple Calendar** - Credential authentication, dedicated calendar creation ### CRITICAL API DISCOVERY **❌ COMMON ENDPOINT MISTAKES**: - `/bookings/v2/external-calendar/providers` (missing 's' in calendars) - `/calendar/v3/external-calendars/` (wrong namespace) **✅ CORRECT ENDPOINTS**: - List Providers: `/bookings/v2/external-calendars/providers` - Connect OAuth: `/bookings/v2/external-calendars/connections:connectByOAuth` - List Connections: `/bookings/v2/external-calendars/connections` ### Key Discovery: Schedule Selection Strategy **Schedule Types Available:** - **Business Schedule**: Universal external ID `4e0579a5-491e-4e70-a872-d097eed6e520` - **Staff Schedules**: Individual staff member schedules with unique IDs **Recommendation:** - Use **Staff Schedules** for personal calendar sync (individual staff members) - Use **Business Schedule** for company-wide calendar integration - **Never connect the same external calendar to multiple schedules** - causes conflicts ### IMPORTANT NOTES * **Premium Feature Gate**: Always verify premium features are enabled before attempting connections * **OAuth Flow Complexity**: The OAuth process requires user interaction - cannot be fully automated * **Sync Configuration**: Default settings may not match your needs - always review `syncConfig` after connection * **Provider-Specific Behaviors**: Google only syncs primary calendar, Microsoft allows specific calendar selection * **Connection Ownership**: If schedule ownership changes, external calendar connection is automatically disconnected * **Real-Time Limitations**: External Calendar API doesn't provide webhooks or real-time event notifications * **Revision Numbers**: External calendar connections don't use revision numbers like other calendar entities --- ## Steps ### 1. Verify Premium Features and List Providers First, confirm external calendar features are available and identify supported providers. Use `listProviders` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-providers.md)): **Expected Response Structure:** - **Google Provider**: `name: "Google"`, `features.connectMethods: ["OAUTH"]` - **Microsoft Provider**: `name: "Outlook or Office 365"`, `features.connectMethods: ["OAUTH"]` - **Apple Provider**: `name: "Apple"`, `features.connectMethods: ["CREDENTIALS"]` Save the `providerId` for your desired provider and note the required `connectMethods`. ### 2. Query Available Schedules Identify which schedule to connect the external calendar to using `querySchedules` API ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/query-schedules.md)): **Schedule Selection Guide:** - **Staff Schedule**: Use for individual staff member calendar sync - **Business Schedule**: Use for company-wide availability sync - **Multiple Schedules**: Create separate connections for each schedule if needed Save the `scheduleId` for your chosen schedule. ### 3. Initiate OAuth Connection (Google/Microsoft) For OAuth providers (Google, Microsoft), create a connection using `connectByOAuth` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-o-auth.md)): **Required Parameters:** - `providerId`: From step 1 - `scheduleId`: From step 2 - `redirectUrl`: Where user returns after authorization (can be placeholder) **Response Contains:** - `oauthUrl`: URL to redirect user for authorization **User Authorization Flow:** 1. Direct user to the `oauthUrl` 2. User completes Google/Microsoft authorization 3. User is redirected to `redirectUrl` with `connectionId` parameter 4. Extract `connectionId` from redirect URL query parameters ### 4. Alternative: Connect by Credentials (Apple) For credential-based providers (Apple), use `connectByCredentials` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-credentials.md)): **Required Parameters:** - `providerId`: Apple provider ID - `scheduleId`: Target schedule ID - `email`: Apple ID email - `password`: Apple ID password **Important**: This method requires collecting sensitive credentials from users. ### 5. Verify Connection and Configure Sync After successful connection, verify the connection status and configure sync settings: **Check Connection:** Use `getConnection` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/get-connection.md)) with the `connectionId`. **Review Sync Configuration:** - **Connection Status**: Should show `"CONNECTED"` when successful - **Import Settings**: `syncConfig.listEventFromCalendars.enabled` controls importing external events to Wix - **Export Settings**: `syncConfig.syncToCalendar.enabled` controls exporting Wix events to external calendar **Update Sync Settings (if needed):** Use `updateSyncConfig` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/update-sync-config.md)) to modify import/export behavior. ### 6. Test Connection and List Events Verify the integration is working by listing external calendar events: Use `listEvents` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-events.md)) with date range filters: **Required Parameters:** - `from`: Start date (required) - `to`: End date (required) - `scheduleIds`: Optional filter by specific schedules This should return events from the connected external calendar. ### IMPORTANT NOTES * **OAuth Completion**: OAuth flow requires actual user interaction - cannot be automated * **Connection Persistence**: Connections remain active until manually disconnected or ownership changes * **Sync Timing**: Event synchronization is not real-time - may take several minutes * **Calendar Permissions**: External calendar must grant appropriate read/write permissions * **Multiple Connections**: Each schedule can connect to multiple external calendar providers * **Error Recovery**: Failed OAuth attempts can be retried with new `connectByOAuth` calls ### Troubleshooting Common Issues **"PREMIUM_FEATURE_NOT_ENABLED" Error (403):** - Verify site has premium plan enabled - Contact Wix support to enable external calendar features - Cannot proceed without premium feature access **"Not Found" Error (404) on Providers:** - Check endpoint URL has 's' in 'calendars': `/external-calendars/providers` - Verify Wix Bookings app is installed - Ensure using correct API version (v2) **OAuth Authorization Fails:** - Check `redirectUrl` is accessible and properly formatted - Verify user has appropriate permissions for external calendar - Try incognito/private browsing to avoid cached authorization issues - Check external calendar provider status (Google/Microsoft outages) **OAuth Internal Server Errors:** - **"Internal Server Error" during Google OAuth**: Common issue that can occur after account selection - **Immediate retry strategy**: Try the same OAuth flow again - temporary server issues often resolve - **Alternative schedule approach**: If business schedule fails, try connecting to a staff schedule instead (or vice versa) - **Browser troubleshooting**: Clear cookies/cache for the calendar provider's domain, or use incognito/private mode - **Different redirect URL**: Try using a different `redirectUrl` parameter (e.g., `https://www.wix.com` instead of custom URLs) - **Account-specific issues**: Try a different Google/Microsoft account if available for testing - **Timing-based retry**: Wait 5-10 minutes between failed attempts - OAuth rate limiting may be involved **OAuth Flow Recovery Steps:** 1. **First attempt fails** → Retry immediately with same parameters 2. **Second attempt fails** → Try alternative schedule type (business ↔ staff) 3. **Third attempt fails** → Clear browser data and use incognito mode 4. **Fourth attempt fails** → Try different redirect URL parameter 5. **All attempts fail** → Switch to different calendar provider (Google → Microsoft → Apple) **Connection Shows "DISCONNECTED" Status:** - Schedule ownership may have changed - External calendar permissions may have been revoked - User may have disconnected from external calendar provider side - Recreate connection with fresh OAuth flow **Events Not Syncing:** - Check `syncConfig` settings match intended behavior - Verify date range filters in `listEvents` calls - Allow 5-10 minutes for sync to complete - Check external calendar permissions and sharing settings **Multiple Calendar Connections Conflict:** - Avoid connecting same external calendar to multiple Wix schedules - Use specific calendar selection for Microsoft Outlook connections - Document which staff schedules connect to which external calendars **Apple Calendar Credential Issues:** - Verify Apple ID supports third-party app access - Check if two-factor authentication requires app-specific passwords - Test credentials in Apple Calendar app before API calls ### Provider-Specific Notes **Google Calendar:** - Only syncs with primary calendar - Requires Google account with calendar access - OAuth scope: `https://www.googleapis.com/auth/calendar` **Microsoft Outlook/365:** - Allows specific calendar selection - Supports both personal and business accounts - May require additional organizational permissions **Apple Calendar:** - Uses credential authentication (email/password) - Creates dedicated calendar for Wix events - May require app-specific password if 2FA enabled ## API Documentation References * [List Providers](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-providers.md) * [Connect By OAuth](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-o-auth.md) * [Connect By Credentials](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-credentials.md) * [Get Connection](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/get-connection.md) * [Update Sync Config](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/update-sync-config.md) * [List Events](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-events.md) * [Query Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/query-schedules.md) * [Apps Installer API](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md)