@wix/agent-skills 1.0.0

package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md

@@ -0,0 +1,278 @@
+---
+name: "End-to-End Booking Flow"
+description: Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+---
+
+# End-to-End Booking Flow (REST)
+
+Step-by-step flow for implementing a complete booking experience using REST APIs.
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+- For paid services: Wix Payments or eCommerce configured
+
+> **Note:** If you receive errors from Bookings APIs, the Wix Bookings app may not be installed on the site. Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install it if missing.
+
+## Required APIs
+
+- **Services API**: [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
+- **Time Slots V2 API**: [List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots)
+- **Bookings API**: [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking), [Confirm Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-booking)
+- **eCommerce API**: [Create Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout)
+
+---
+
+## Step 1: Query Available Services
+
+**Endpoint**: `POST https://www.wixapis.com/bookings/v2/services/query`
+
+```json
+{
+  "query": {
+    "filter": {
+      "type": "APPOINTMENT"
+    },
+    "paging": {
+      "limit": 20
+    }
+  }
+}
+```
+
+**Service Types**:
+
+- `APPOINTMENT` — One-on-one sessions with a staff member
+- `CLASS` — Group sessions at scheduled times
+- `COURSE` — Multi-session series (customers book the entire course)
+
+**Save from the response**:
+
+- `id` — service ID
+- `schedule.id` — schedule ID (needed for appointment bookings and course bookings)
+- `type` — determines the booking flow (slot vs schedule)
+- `staffMemberIds` — resource IDs of assigned staff (for appointments)
+
+---
+
+## Step 2: Check Availability
+
+**Endpoint**: `POST https://www.wixapis.com/_api/service-availability/v2/time-slots`
+
+> **Important**: The old Availability Calendar API (`/bookings/v2/availability/query`) is deprecated. Always use Time Slots V2.
+
+```json
+{
+  "serviceId": "<SERVICE_ID>",
+  "fromLocalDate": "2024-06-15T08:00:00",
+  "toLocalDate": "2024-06-16T18:00:00",
+  "timeZone": "America/New_York",
+  "bookable": true,
+  "includeResourceTypeIds": ["<RESOURCE_TYPE_ID>"]
+}
+```
+
+### Date format
+
+Dates **must** be in `YYYY-MM-DDThh:mm:ss` format (local datetime). Plain dates like `2024-06-15` will be rejected with a 400 error.
+
+### Parameters
+
+| Parameter                | Required | Description                                                             |
+| ------------------------ | -------- | ----------------------------------------------------------------------- |
+| `serviceId`              | Yes      | From Step 1                                                             |
+| `fromLocalDate`          | Yes      | Start of range in `YYYY-MM-DDThh:mm:ss` format                          |
+| `toLocalDate`            | Yes      | End of range in `YYYY-MM-DDThh:mm:ss` format                            |
+| `timeZone`               | Yes      | IANA timezone (e.g. `America/New_York`)                                 |
+| `bookable`               | No       | Set `true` to only get bookable slots                                   |
+| `includeResourceTypeIds` | No       | Array of resource type IDs — populates `availableResources` in response |
+
+### Save from each time slot
+
+- `serviceId`, `scheduleId` — needed for Create Booking
+- `localStartDate`, `localEndDate` — slot times
+- `availableResources[].resources[].id` — resource ID (only populated if `includeResourceTypeIds` was provided)
+- `location.locationType` — **warning**: returns `BUSINESS` but Create Booking requires `OWNER_BUSINESS` (see Step 3)
+
+### For Classes
+
+Use [List Event Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots) instead. Each class session has an `eventId` — save it for the booking.
+
+---
+
+## Step 3: Create the Booking
+
+**Endpoint**: `POST https://www.wixapis.com/_api/bookings-service/v2/bookings`
+
+### For Appointments (use `slot`)
+
+```json
+{
+  "booking": {
+    "bookedEntity": {
+      "slot": {
+        "serviceId": "<SERVICE_ID>",
+        "scheduleId": "<SCHEDULE_ID>",
+        "startDate": "2024-06-15T14:00:00",
+        "endDate": "2024-06-15T15:00:00",
+        "timezone": "America/New_York",
+        "resource": {
+          "id": "<RESOURCE_ID>"
+        },
+        "location": {
+          "locationType": "OWNER_BUSINESS"
+        }
+      }
+    },
+    "contactDetails": {
+      "firstName": "John",
+      "lastName": "Doe",
+      "email": "john@example.com"
+    },
+    "totalParticipants": 1
+  }
+}
+```
+
+All slot fields are **required** for appointments when no `eventId` is provided:
+
+| Field                   | Source | Notes                                                                                                                        |
+| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `serviceId`             | Step 1 | Service GUID                                                                                                                 |
+| `scheduleId`            | Step 2 | From the time slot response                                                                                                  |
+| `startDate` / `endDate` | Step 2 | `YYYY-MM-DDThh:mm:ss` format                                                                                                 |
+| `timezone`              | Step 2 | IANA tz format                                                                                                               |
+| `resource.id`           | Step 2 | From `availableResources` in time slot response                                                                              |
+| `location.locationType` | —      | Must be `OWNER_BUSINESS`, `OWNER_CUSTOM`, or `CUSTOM`. Time Slots returns `BUSINESS` but that value is **not accepted** here |
+
+### For Classes (use `slot` with `eventId`)
+
+```json
+{
+  "booking": {
+    "bookedEntity": {
+      "slot": {
+        "serviceId": "<SERVICE_ID>",
+        "eventId": "<EVENT_ID>"
+      }
+    },
+    "contactDetails": {
+      "firstName": "Jane",
+      "lastName": "Doe",
+      "email": "jane@example.com"
+    },
+    "totalParticipants": 1
+  }
+}
+```
+
+When you provide `eventId`, all other slot fields (`startDate`, `endDate`, `timezone`, `resource`, `location`) are **auto-derived** from the event. You only need `serviceId` + `eventId`.
+
+### For Courses (use `schedule`)
+
+```json
+{
+  "booking": {
+    "bookedEntity": {
+      "schedule": {
+        "scheduleId": "<SCHEDULE_ID>",
+        "serviceId": "<SERVICE_ID>",
+        "timezone": "America/New_York",
+        "location": {
+          "locationType": "OWNER_BUSINESS"
+        }
+      }
+    },
+    "contactDetails": {
+      "firstName": "Bob",
+      "lastName": "Test",
+      "email": "bob@example.com"
+    },
+    "totalParticipants": 1
+  }
+}
+```
+
+### Participants
+
+Specify exactly one of:
+
+- `totalParticipants` — for services with fixed pricing and no variants
+- `participantsChoices` — for services with [variants and options](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/introduction)
+
+### Result
+
+Booking is created with `status: CREATED`. This is **not yet visible** in the booking calendar. You must either:
+
+- **Confirm it** (Step 4, for offline/free payments), or
+- **Process payment** (Step 4, for online payments) — confirmation happens automatically after checkout
+
+---
+
+## Step 4: Confirm or Process Payment
+
+### For free or offline-payment bookings: Confirm directly
+
+**Endpoint**: `POST https://www.wixapis.com/_api/bookings-service/v2/bookings/<BOOKING_ID>/confirm`
+
+```json
+{
+  "revision": "<REVISION>",
+  "paymentStatus": "EXEMPT"
+}
+```
+
+Use the `id` and `revision` from the Create Booking response. Set `paymentStatus` to `EXEMPT` for free services or `NOT_PAID` for pay-at-location.
+
+**Result**: Booking status changes to `CONFIRMED` and is visible in the booking calendar.
+
+### For online payments: Create checkout
+
+**4a. Create Checkout**
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts`
+
+```json
+{
+  "lineItems": [
+    {
+      "catalogReference": {
+        "catalogItemId": "<BOOKING_ID>",
+        "appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"
+      },
+      "quantity": 1
+    }
+  ],
+  "channelType": "WEB"
+}
+```
+
+Use the booking ID as `catalogItemId` with the Wix Bookings app ID.
+
+**4b. Get Checkout URL**
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/getCheckoutUrl`
+
+Redirect the user to the returned `checkoutUrl`. After payment, the booking is automatically confirmed.
+
+**4c. Create Order (alternative, server-to-server)**
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+
+Creates an order directly without redirect.
+
+---
+
+## Service Type Summary
+
+| Service Type | `bookedEntity`                        | Availability API                           | Key Difference                                             |
+| ------------ | ------------------------------------- | ------------------------------------------ | ---------------------------------------------------------- |
+| APPOINTMENT  | `slot` (all fields required)          | Time Slots V2                              | Single session, specific time, needs resource + scheduleId |
+| CLASS        | `slot` (only `serviceId` + `eventId`) | Event Time Slots                           | Group session, auto-derives fields from event              |
+| COURSE       | `schedule`                            | Check capacity via Query Extended Bookings | Multi-session, books entire schedule                       |
+
+## See Also
+
+- [Flow: Single-Service Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/flow-single-service-booking)
+- [Create Booking Sample Flows](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/sample-flows)
+- [Time Slots V2 Sample Flows](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/sample-flows)

package/skills/wix-manage/references/bookings/external-calendar-integration.md

@@ -0,0 +1,258 @@
+---
+name: "External Calendar Integration"
+description: OAuth-based integration with Google Calendar, Microsoft Outlook, and Apple Calendar. Covers authentication flows, sync configuration, and bidirectional event management.
+---
+# 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/install-app)
+- 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)):
+
+**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)):
+
+**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)):
+
+**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)):
+
+**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)) 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)) 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)) 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)
+* [Connect By OAuth](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-o-auth)
+* [Connect By Credentials](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-credentials)
+* [Get Connection](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/get-connection)
+* [Update Sync Config](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/update-sync-config)
+* [List Events](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-events)
+* [Query Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/query-schedules)
+* [Apps Installer API](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)