@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-manage/references/bookings/diagnose-availability-issues.md

@@ -0,0 +1,299 @@
+---
+name: "Check Bookings Availability (and Diagnose Issues)"
+description: "Answers whether an appointment-based Wix Bookings service currently has bookable availability — the primary question — and diagnoses the cause only when there's no availability or the owner asks why. To diagnose, first rules out service-level blockers the availability endpoint can't see (service hidden, online booking off), then runs DiagnoseAvailability for ordered, machine-readable staff/setup reasons, with a manual fallback for booking-policy and capacity causes. Use when someone asks whether a service has availability, or why a service shows no times / customers can't book it."
+---
+# Check Bookings Availability (and Diagnose Issues)
+
+This recipe answers two related questions, in order of how often they're asked:
+
+1. **"Does this service have availability right now?"** — the default. Give a short, plain status answer.
+2. **"Why is there no availability / why can't customers book?"** — diagnose the cause. Only do this when there's **no bookable availability**, or the owner **explicitly asks** why / how to fix it.
+
+Don't diagnose by default. If the owner just wants to know the status and the service is bookable, answer that and stop.
+
+> ## ⚠️ Output rule (read first)
+> You are talking to a **site owner**, not a developer. Use everything below — endpoints, JSON, reason codes, `suggestedAction` values, field names — **only to do the work.** Your **reply must be plain language**.
+>
+> **Keep it short and only say what's relevant:**
+> - When the service **is** bookable, confirm it in a sentence. **Don't recite everything that happens to be fine** — the owner didn't ask for an audit. ❌ "It's visible on your site (not hidden). Online booking is ON. It has 1 staff member assigned and 1 location." ✅ "Yes — **[service]** has open times customers can book."
+> - When you diagnose, surface **only the blocking cause and its fix** — not a checklist of everything that passed.
+>
+> **Never put any of these in your reply:** endpoint paths or curl, JSON, reason-code names (e.g. `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION`), `suggestedAction` enums, or field names. Translate them. See [Presenting to the user](#presenting-to-the-user).
+>
+> ✅ "Your staff don't have working hours at the location this service is offered at, so there's nothing to book. Want me to add hours there?"
+> ❌ "`DiagnoseAvailability` returned `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION` / `CHECK_WORK_LOCATIONS`."
+
+## When to use
+
+- Owner asks whether an **appointment-based** service has availability / bookable times → [Step 1](#step-1--report-the-current-availability-status).
+- Owner reports the service has **no bookable times**, or that **customers can't book (or can't even find) it** → Step 1 will come back empty, so go on to diagnose ([Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking) onward). For "can't book / can't find," start diagnosis at Step 2 even if Step 1 returned slots — a hidden service still lists slots (see the note in Step 1).
+
+> **Scope:** appointment-based services.
+
+---
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`).
+
+> **Note:** If Bookings APIs return errors, the app may not be installed. 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.
+
+- Typically the `serviceId` (optionally with a staff member's `resourceId` to scope to one provider). A `resourceId` on its own is also supported for the staff editor, where no service is in context — see [Which inputs to pass](#which-inputs-to-pass-prefer-a-service).
+
+- **Authorization (diagnosis only):** to call `DiagnoseAvailability` the caller needs the `bookings:availability:v2:time_slot:diagnose_availability` permission. A plain site/owner token can come back **403 (empty body)** if that permission isn't granted — that's an auth problem, not "no cause found." Ensure the calling context carries the permission before treating a 403 as inconclusive.
+
+---
+
+## Step 1 — Report the current availability status
+
+This is the default answer. Find out whether customers can actually book the service right now, then say so plainly.
+
+- **Endpoint:** `ListAvailabilityTimeSlots` — the same slots a customer sees. See [End-to-End Booking Flow](end-to-end-booking-flow.md) for the request shape. Query the service over a sensible upcoming window (e.g. the next few weeks) in the site's time zone.
+
+Interpret the result:
+
+| What comes back | Availability status | What to do |
+|-----------------|---------------------|------------|
+| One or more **bookable** slots | **Bookable.** | Tell the owner in a sentence and stop — no diagnosis needed unless they ask why/how to change something. |
+| Slots exist but **none are bookable** (`nonBookableReasons` / `bookingPolicyViolations` set) | **Not bookable — policy/capacity.** | This is the cause. Surface it directly ([policy/capacity causes](#booking-policy--capacity-slots-exist-but-arent-bookable)). No need to run `DiagnoseAvailability`. |
+| **No slots at all** | **No availability.** | Diagnose: go to [Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking). |
+
+> **The hidden-service trap.** A service that's **hidden** from the site, or has **online booking turned off**, can still list slots here — so bookable slots do **not** prove customers can book it. When the complaint is "customers can't book / can't find this service" (as opposed to "the calendar is empty"), **run [Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking) before trusting the slot count** — it's the single most common cause and neither `ListAvailabilityTimeSlots` nor `DiagnoseAvailability` detects it.
+
+If **no slots come back at all**, also sanity-check the inputs before concluding "no availability": the queried window isn't entirely in the past, and any `locations` filter is actually offered by the service.
+
+---
+
+## Diagnosis
+
+Do the following **only** when Step 1 found no availability, or the owner asks why there are no times / how to fix it / why customers can't book. Run the checks in order — cheapest, most common blockers first.
+
+## Step 2 — Rule out service-level blockers (visibility & online booking)
+
+Two service settings block booking **entirely**, regardless of staff availability, and are invisible to `DiagnoseAvailability`. Check them **first** with a single read of the service.
+
+- **Endpoint:** `GET https://www.wixapis.com/_api/bookings/v2/services/{serviceId}`
+
+Inspect two fields on the returned `service`:
+
+| Field | Blocking value | What it means (the "Visible on your site and app" toggle is `hidden` inverted) |
+|-------|----------------|------------------|
+| `hidden` | `true` | The service is **hidden from the site and app**. Customers can't see or book it. In the dashboard this is the **"Visible on your site and app"** toggle turned **off**. |
+| `onlineBooking.enabled` | `false` | **Online booking is turned off** for this service. It may be visible, but customers can't book it online (staff can still book it manually). |
+
+- If **`hidden: true`** → that's the cause. Stop here. Fix: make the service visible (offer to flip the toggle for them).
+- If **`onlineBooking.enabled: false`** → that's the cause (for "can't book online"). Fix: turn online booking on.
+- If both are fine (`hidden: false`, `onlineBooking.enabled: true`) → proceed to Step 3. **Don't announce that they're fine** — just move on.
+
+> **Why this comes first:** a hidden service can still have staff, working hours, and internally-generated time slots — so `ListAvailabilityTimeSlots` and `DiagnoseAvailability` will happily report on those slots (including policy details like "too late to book"). None of that is the real reason the customer can't book. Confirming visibility first prevents a confidently-wrong answer.
+
+---
+
+## Step 3 — Run the diagnosis
+
+`DiagnoseAvailability` is a read-only custom action that explains **why availability is empty** rather than returning slots.
+
+- **Endpoint:** `POST https://www.wixapis.com/_api/service-availability/v2/time-slots/diagnose`
+- **Maturity:** ALPHA, behind the `diagnoseAvailabilityEndpoint` feature toggle (deployed and available in production). If it returns **no reasons** for a service you'd expect to be broken, treat the result as inconclusive and go to [Step 4](#step-4--fallback-when-the-endpoint-is-inconclusive).
+- **`hasAvailability`** is set `true` only on the **service paths**, when the availability-window check confirms real availability — and for `serviceId`-only, only when the service needs a single staff resource type. It is **never** asserted `true` for `serviceId`+`resourceId` (one resource can't confirm the whole service) or for resource-only. So `hasAvailability: false` with an empty `reasons` array means **inconclusive** ("no blocking cause found"), not necessarily "no availability."
+
+### Which inputs to pass (prefer a service)
+
+**Prefer passing `serviceId`** — on its own, or together with a `resourceId` to scope to one provider. `resourceId` alone is a valid mode (it serves the staff editor, where there is no service context) but is shallower; use it when a service genuinely isn't available.
+
+The service is what makes the diagnosis deep. Only the service paths run the L2 availability-window check — it needs the service configuration (duration, buffer, offered locations, resource types) to actually verify the resource has real windows in the range and at the right locations. That L2 check is what produces `NO_RESOURCE_AVAILABILITY_WINDOWS`, `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION`, and `REQUESTED_LOCATION_NOT_OFFERED_BY_SERVICE`.
+
+| Inputs | Diagnoses | Depth | `hasAvailability` |
+|--------|-----------|-------|-------------------|
+| `serviceId` + `resourceId` *(preferred)* | Why a specific provider has no slots for the service | L1 setup + L2 window/location | never asserted `true` |
+| `serviceId` only | Whole-service availability across assigned staff/locations | L1 setup + L2 window/location | `true` only if the service needs a single staff resource type |
+| `resourceId` only | Staff-editor check, no service context | L1 setup + missing/empty working-hours check (no window/location; `deep` not allowed) | never asserted `true` |
+
+**Resource-only is a valid mode, but lighter.** It exists for contexts where there is no service — e.g. the **staff editor**, diagnosing a staff member on their own. It catches a **missing or empty** working-hours schedule (`RESOURCE_HAS_NO_WORKING_HOURS`), but with no service configuration it can't run the availability-window or location checks, can't resolve locations, and can't use `deep`. So problems that only surface against a service — no windows despite having hours, a location mismatch, duration/buffer — are caught only when a `serviceId` is supplied.
+
+- Owner reports a **service** has no availability → pass `serviceId`.
+- Concern is a **specific provider**, and you have (or can find) a service → pass `serviceId` + `resourceId` (use a service they're assigned to) for the fullest diagnosis.
+- **Only a `resourceId` is available** (e.g. from the staff editor, with no service in context) → use resource-only; it flags missing/empty working hours, but treat an inconclusive result with care — it can't check windows, locations, or run `deep`. When you can, re-run with a service the resource is assigned to.
+
+### Request
+
+```bash
+curl -X POST 'https://www.wixapis.com/_api/service-availability/v2/time-slots/diagnose' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "serviceId": "<SERVICE_ID>",
+    "fromLocalDate": "2026-07-01T00:00:00",
+    "toLocalDate": "2026-09-29T00:00:00",
+    "timeZone": "America/New_York"
+  }'
+```
+
+| Field | Notes |
+|-------|-------|
+| `serviceId` | Service to diagnose. Provide this or `resourceId`. |
+| `resourceId` | Staff member / resource to diagnose. Pair it with `serviceId` (see [Which inputs to pass](#which-inputs-to-pass-prefer-a-service)). Resource-only (no `serviceId`) runs a lighter check — missing/empty working hours only, no window/location/`deep` — and can miss service-dependent problems. |
+| `fromLocalDate` | `YYYY-MM-DDThh:mm:ss` (ISO-8601). Optional; defaults to now. |
+| `toLocalDate` | Optional; defaults to `fromLocalDate` + 90 days. |
+| `timeZone` | IANA tz (e.g. `America/New_York`). Defaults to the site's time zone. |
+| `locations` | Locations to diagnose. Empty ⇒ all locations the service offers. |
+| `deep` | Optional (default `false`). Set `true` **with a `serviceId`** to refine a "no availability windows" result into *why* — outside working hours vs. blocked/busy time. Extra sampling call; only acts when no windows exist; rejected on the resource-only path (`MISSING_ARGUMENTS`). See [Deep mode](#deep-mode). |
+
+### Response
+
+```json
+{
+  "hasAvailability": false,
+  "reasons": [
+    { "code": "RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION", "suggestedAction": "CHECK_WORK_LOCATIONS" }
+  ],
+  "resolvedContext": {
+    "serviceId": "<SERVICE_ID>",
+    "resolvedLocations": [ { "id": "...", "name": "...", "locationType": "BUSINESS" } ],
+    "durationInMinutes": 60,
+    "bufferTimeInMinutes": 0,
+    "fromLocalDate": "2026-07-01T00:00:00",
+    "toLocalDate": "2026-09-29T00:00:00",
+    "timeZone": "..."
+  }
+}
+```
+
+- `reasons` are ordered **most-specific first**. Fix the first, then re-run.
+- `resolvedContext` echoes the inputs actually used (resolved locations, duration, buffer, window, time zone) — use it to confirm you diagnosed what you meant to.
+- Empty `reasons` ⇒ **inconclusive** → go to **Step 4**.
+
+### Reason codes → owner fix (agent-internal — never shown to the user)
+
+> This table is for **your** interpretation only. Map the returned code to the plain-language cause and fix, then write the reply in everyday words — the code names and `suggestedAction` values must not appear in your response. See [Presenting to the user](#presenting-to-the-user).
+
+| `code` | `suggestedAction` | Meaning & fix |
+|--------|-------------------|---------------|
+| `NO_ASSIGNED_STAFF_OR_RESOURCES` | `ASSIGN_STAFF_OR_RESOURCES` | No staff/resources assigned to the service. Assign at least one. |
+| `RESOURCE_NOT_ASSIGNED_TO_SERVICE` | `ASSIGN_RESOURCE_TO_SERVICE` | The given resource isn't assigned to the service. Assign it, or diagnose a resource that is. |
+| `RESOURCE_HAS_NO_WORKING_HOURS` | `CHECK_STAFF_WORKING_HOURS` | The staff member has no working-hours schedule. Configure working hours — see [Bookings Staff Setup](bookings-staff-setup.md). |
+| `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION` | `CHECK_WORK_LOCATIONS` | Assigned resources have availability windows, but none at a location the service offers. Add working hours at an offered location, offer the service where the staff works, or assign a provider who works at the offered location. |
+| `NO_RESOURCE_AVAILABILITY_WINDOWS` | `CHECK_STAFF_WORKING_HOURS` | No availability windows exist anywhere in the diagnosed range. Add working hours, or widen the range. |
+| `REQUESTED_LOCATION_NOT_OFFERED_BY_SERVICE` | `CHECK_SERVICE_LOCATIONS` | A requested `locations` filter isn't offered by the service. Drop the filter or fix the service's locations. |
+| `DURATION_TOO_LONG_FOR_AVAILABLE_WINDOWS` | `REDUCE_DURATION_OR_BUFFER` | The service is longer than every free window. Shorten it or lengthen working hours. |
+| `BUFFER_TIME_ELIMINATES_WINDOWS` | `REDUCE_DURATION_OR_BUFFER` | Buffer time consumes all otherwise-free windows. Reduce the buffer or lengthen working hours. |
+| `SERVICE_AVAILABILITY_CONFIGURATION_MISSING` | — | The service's availability configuration is missing. |
+| `RESOURCE_TYPE_RESOLUTION_FAILED` | — | The service's resource types couldn't be resolved. |
+| `RESOURCE_NOT_IN_WORKING_HOURS` | `CHECK_STAFF_WORKING_HOURS` | The resource works, but not during the empty range — it's outside their working hours. **Reported only with `deep: true`.** Fix: adjust/extend working hours. |
+| `RESOURCE_BLOCKED` | `CHECK_BLOCKED_TIME` | The resource is within working hours but blocked by existing bookings, calendar events, or an external calendar. **Reported only with `deep: true`.** Fix: free up the blocked time. |
+
+### Endpoint errors
+
+| HTTP | `application_code` | Cause |
+|------|-------------------|-------|
+| 400 | `MISSING_ARGUMENTS` | Neither `serviceId` nor `resourceId` provided; or `deep: true` sent without a `serviceId`. |
+| 400 | `INVALID_TIME_ZONE` | `timeZone` isn't a valid IANA zone. |
+| 400 | `INVALID_SERVICE_IDS_PROVIDED` | The `serviceId` doesn't resolve to a service on the site. In practice a well-formed-but-nonexistent `serviceId` (not only a malformed one) currently surfaces here rather than as a 404 — re-check the ID. |
+| 404 | `SERVICE_NOT_FOUND` / `RESOURCE_NOT_FOUND` | Service / staff record missing. (A missing `serviceId` may instead surface as the 400 `INVALID_SERVICE_IDS_PROVIDED` above.) |
+| 404 | `NO_IMPLEMENTERS_FOUND` / `MULTIPLE_IMPLEMENTERS_FOUND` | No / multiple availability providers configured. |
+| 403 | `UNAUTHORIZED_OPERATION` | Caller lacks `bookings:availability:v2:time_slot:diagnose_availability`. |
+
+### Deep mode
+
+`deep: true` (with a `serviceId`) refines a **no-availability-windows** result — it tells you *why* there are no windows: the staff are **outside their working hours** for that range (`RESOURCE_NOT_IN_WORKING_HOURS`) vs. within hours but **blocked/busy** (`RESOURCE_BLOCKED`, e.g. existing bookings or an external calendar).
+
+- **When to use:** the standard call returns `NO_RESOURCE_AVAILABILITY_WINDOWS` and you want to tell the owner whether to *add hours* or *free up blocked time*.
+- **How it works:** it samples a handful of slots across the range and makes one availability check, then attributes the cause. It runs **only when no windows exist** — it does nothing when availability is already present.
+- **Constraints:** requires a `serviceId` (resource-only + `deep` → `MISSING_ARGUMENTS`); it's a best-effort refinement and silently falls back to the generic `NO_RESOURCE_AVAILABILITY_WINDOWS` cause if the sampling is inconclusive.
+
+---
+
+## Step 4 — Fallback when the endpoint is inconclusive
+
+Empty `reasons` + still no bookable slots usually means the cause is one `DiagnoseAvailability` **doesn't evaluate**: booking policy or remaining capacity. You may already have this from the `ListAvailabilityTimeSlots` call in Step 1 — if not, call it again for the same service and window and inspect the returned slots.
+
+<a id="booking-policy--capacity-slots-exist-but-arent-bookable"></a>
+- **`nonBookableReasons`** — `noRemainingCapacity`, `violatesBookingPolicy`, `reservedForWaitingList`, `eventCancelled`.
+- **`bookingPolicyViolations`** — `tooEarlyToBook`, `tooLateToBook`, `bookOnlineDisabled`.
+
+If **no slots come back at all**, re-check the inputs: the diagnosed window isn't entirely in the past, and any `locations` filter is actually offered by the service.
+
+See [End-to-End Booking Flow](end-to-end-booking-flow.md) for the `ListAvailabilityTimeSlots` request shape.
+
+---
+
+## Presenting to the user
+
+Whether you're reporting status or a cause, reply in plain, friendly language and keep it short.
+
+- **Answer the actual question.** If they asked "is it available," the reply is a status line — not a diagnosis. Only explain causes when there's no availability or they asked why.
+- **Only say what's relevant.** When the service is bookable, confirm it in a sentence; **don't list every setting that's fine** ("visible, online booking on, 1 staff, 1 location" — the owner didn't ask). When diagnosing, give **only the blocking cause and its fix**, not a rundown of everything that passed.
+- **Don't expose internals** — no reason codes, `suggestedAction` enums, raw JSON, endpoint names, or field paths.
+- **Lead with the point in plain English**, then the concrete next step. One or two short sentences is usually enough.
+- **Use the owner's own terms** — "your service", "your staff", "the dates you're looking at", real location names from `resolvedLocations`.
+- **Offer to help with the fix** rather than only stating it.
+- If diagnosis is **inconclusive** (empty `reasons`), say only that you **couldn't find a blocking problem**, and describe what you'll check next (policy/capacity, or re-run against a service for a resource-only check). **Do not state or imply that anything is set up correctly** — an empty `reasons` array means "no blocker detected," *not* "working hours / locations / setup are present." On the resource-only path never say the staff "have working hours set"; the check doesn't verify that.
+
+**Plain-language phrasing per outcome:**
+
+| Outcome | Say something like |
+|---------|--------------------|
+| Service **is** bookable (status) | "Yes — **[service]** has open times customers can book (the next one is [day/time])." |
+| Service is hidden from the site (`hidden: true`) | "This service is currently hidden from your site and app, so customers can't see or book it. Want me to make it visible?" |
+| Online booking turned off (`onlineBooking.enabled: false`) | "Online booking is turned off for this service, so customers can't book it themselves online (you can still book it for them manually). Want me to turn online booking on?" |
+| No staff/resources on the service | "This service doesn't have any staff assigned yet, so there's nothing to book. Want me to help you add someone?" |
+| Provider isn't on the service | "That staff member isn't assigned to this service, so their times don't show. I can add them to it." |
+| Provider has no working hours | "The staff for this service don't have any working hours set, so there are no times to offer. Let's set their hours." |
+| Provider works only at other locations | "Your staff have working hours, but not at the location(s) this service is offered at. We can either add hours at one of the service's locations, or offer the service where they already work." |
+| No working-hours windows in range | "None of the staff for this service have working hours in the dates you're checking. Let's add or extend their hours — or try a different date range." |
+| Outside working hours (deep) | "For those dates, your staff simply aren't scheduled to work, so there's nothing to offer. Let's add working hours in that period." |
+| Within hours but blocked/busy (deep) | "Your staff are scheduled to work then, but that time is already taken up — by existing bookings or events on their calendar. Freeing some of it up will open slots." |
+| Service too long / buffer too large | "The service is longer than any open gap in your staff's schedule (the duration plus buffer doesn't fit). Shortening it a bit, or widening working hours, would open up slots." |
+| Requested location not offered | "This service isn't offered at the location you picked. Want me to add that location to the service, or check a different one?" |
+| Slots exist but aren't bookable | "There are times available, but customers can't book them right now — [e.g. they're fully booked / it's too early or late to book per your policy]. Here's how to adjust that." |
+
+**Example conversational reply** (for a location-mismatch result):
+
+> I looked into why no times are showing for **[service name]**. Your staff do have working hours, but none of them are at the locations this service is offered at (**Jerusalem2** and **Holon**) — so there's nothing available to book.
+>
+> To fix it you can either add working hours for a staff member at Jerusalem2 or Holon, or offer the service at the location where your staff already work. Want me to set that up?
+
+---
+
+## Common causes (quick reference)
+
+Popular reasons a service shows no availability, and where each surfaces:
+
+| Situation | Where it surfaces | Fix |
+|-----------|-------------------|-----|
+| Service **is** bookable | Step 1 — `ListAvailabilityTimeSlots` returns bookable slots | Nothing — report the status. |
+| Service hidden from the site/app | Step 2 — `service.hidden: true` | Make the service visible ("Visible on your site and app" toggle). |
+| Online booking turned off | Step 2 — `service.onlineBooking.enabled: false` | Turn online booking on for the service. |
+| No staff/resources on the service | `NO_ASSIGNED_STAFF_OR_RESOURCES` | Assign staff/resources. |
+| Provider isn't on the service | `RESOURCE_NOT_ASSIGNED_TO_SERVICE` | Assign the provider. |
+| Provider has no working hours | `RESOURCE_HAS_NO_WORKING_HOURS` | Configure working hours. |
+| Provider works only at other locations | `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION` | Align staff work locations with the service's offered locations. |
+| No working-hours windows in range | `NO_RESOURCE_AVAILABILITY_WINDOWS` | Add working hours / widen the range. |
+| No windows — outside working hours (deep) | `RESOURCE_NOT_IN_WORKING_HOURS` (`deep: true`) | Add or extend working hours in the range. |
+| No windows — within hours but blocked/busy (deep) | `RESOURCE_BLOCKED` (`deep: true`) | Free up blocked time / check the external calendar. |
+| Service too long / buffer too large for the windows | `DURATION_TOO_LONG_FOR_AVAILABLE_WINDOWS`, `BUFFER_TIME_ELIMINATES_WINDOWS` | Shorten duration/buffer or lengthen hours. |
+| Requested location not offered | `REQUESTED_LOCATION_NOT_OFFERED_BY_SERVICE` | Fix the location filter or the service's locations. |
+| Slots exist but aren't bookable (fully booked, too early/late, online booking off) | Step 1 / Step 4 — `ListAvailabilityTimeSlots` `nonBookableReasons` / `bookingPolicyViolations` | Adjust capacity or booking policy. |
+
+---
+
+## Gotchas
+
+- **Don't diagnose when you weren't asked to.** The default question is "does this have availability" — answer the status and stop. Only dig into causes when there's no availability or the owner asks why / how to fix.
+- **Keep the reply to what's relevant.** When a service is bookable, don't recite every setting that's fine; when diagnosing, give only the blocking cause, not a pass/fail checklist.
+- **A hidden service is the classic wrong-diagnosis trap.** `hidden: true` (or `onlineBooking.enabled: false`) blocks booking entirely, but a hidden service can still list slots — so `ListAvailabilityTimeSlots` and `DiagnoseAvailability` will report on those slots and their policy details (e.g. "too late to book"), none of which is the real reason. When the complaint is "customers can't book / can't see this service," **run Step 2 first.**
+- **`hasAvailability: false` + empty `reasons` ≠ a confirmed problem.** It means "no blocking cause detected." Always confirm with `ListAvailabilityTimeSlots`.
+- **`DiagnoseAvailability` is ALPHA and feature-toggled.** If it returns nothing for an obviously broken service, the `diagnoseAvailabilityEndpoint` toggle may be off — fall back to Step 4.
+- **A 403 is an auth problem, not a diagnosis.** The action needs the `bookings:availability:v2:time_slot:diagnose_availability` permission; a caller without it gets a 403 with an empty body. Don't read that as "no cause found" — confirm the caller has the permission (see [Prerequisites](#prerequisites)).
+- **`deep: true` needs a `serviceId`** (resource-only + `deep` → `MISSING_ARGUMENTS`) and only refines a "no windows" result — it does nothing when windows already exist.
+- **`DiagnoseAvailability` ignores booking policy and capacity** — those come from `ListAvailabilityTimeSlots` (Step 1 / Step 4).
+- **Resource-only diagnosis is lighter.** Passing `resourceId` without `serviceId` catches missing/empty working hours but skips the window, location, and deep checks, so it can return "inconclusive" for service-dependent problems. Valid when there's no service context (e.g. the staff editor); otherwise pair the resource with a service.
+- **Appointment-based services only.**
+
+## API Documentation References
+
+- [Time Slots V2 — List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots)
+- [Services V2](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction)
+- [Staff Members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/introduction)
+- [Booking Policies](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction)
+- Related recipes: [Bookings Staff Setup](bookings-staff-setup.md) · [Create and Update Booking Services](create-and-update-booking-services.md) · [End-to-End Booking Flow](end-to-end-booking-flow.md)

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -140,6 +140,12 @@ curl -X GET \
 | `SITE_MEMBER_AUTHOR` | Members who created the item |
 | `ADMIN` | Site admins only |
 
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `WDE0110` | Wix CMS (Wix Data) app is not installed on the site | Install it: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install` with body `{"tenant":{"tenantType":"SITE","id":"<SITE_ID>"},"appInstance":{"appDefId":"e593b0bd-b783-45b8-97c2-873d42aacaf4"}}`, then retry. See the [Install Wix Apps recipe](../app-installation/install-wix-apps.md). |
+
 ## Related Documentation
 
 - [Data Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)

package/skills/wix-manage/references/get-paid/how-to-setup-wix-payments.md

@@ -10,12 +10,19 @@ This recipe covers the setup flow needed before creating payment links or collec
 
 Before connecting Wix Payments, collect and confirm:
 
-1. Terms acceptance: https://www.wix.com/about/terms-of-payments
+1. Terms acceptance: https://support.wix.com/en/article/wix-payments-terms-of-service
 2. First name
 3. Last name
 4. Product/service description (minimum meaningful business description)
+5. The site's country — if not already known, get it from `properties.locale.country` via `GET https://www.wixapis.com/site-properties/v4/properties`
 
-## Step 2: Connect Wix Payments account
+## Step 2: Check country support
+
+Wix Payments self-serve connect is currently supported for these countries: `US, CA, GB, ES, AT, BE, FI, DE, IT, NL, PT, CH, LT`.
+
+If the site's country is not on this list, stop here — do not call connect. Tell the user self-serve connect isn't available yet for their country, and point them to the dashboard instead (Settings → Accept Payments).
+
+## Step 3: Connect Wix Payments account
 
 Call:
 
@@ -27,12 +34,13 @@ Call:
     "firstName": "<USER_FIRST_NAME>",
     "lastName": "<USER_LAST_NAME>",
     "tosAccepted": true,
-    "productDescription": "<PRODUCT_DESCRIPTION>"
+    "productDescription": "<PRODUCT_DESCRIPTION>",
+    "country": "<COUNTRY_CODE verified in Step 2>"
   }
 }
 ```
 
-## Step 3: Handle common setup blockers
+## Step 4: Handle common setup blockers
 
 ### Location-related failure
 
@@ -43,15 +51,30 @@ If setup fails due to location details, update the business location and retry:
 
 ### Already connected
 
-If the API returns an "already connected" style response, skip reconnect and continue with onboarding checks.
+If the account is already connected, the API returns `HTTP 500` with a body like:
+
+```json
+{
+  "message": "payments already connected",
+  "details": { "applicationError": { "code": "INTERNAL_ERROR" } }
+}
+```
+
+Match on the `message` text, not on the `code` alone — `INTERNAL_ERROR` is a generic code reused for unrelated failures too. On this match, skip reconnect and continue with onboarding checks.
 
-## Step 4: Complete dashboard onboarding
+### Unsupported country
+
+If `account.country` isn't one of the countries listed in Step 2, expect an `INVALID_ARGUMENT`-style `HTTP 400` error. Step 2's own check should make hitting this rare — don't retry the call with a different country value; tell the user the same thing Step 2 would have.
+
+## Step 5: Complete dashboard onboarding
 
 Connecting the account is not always the final step. To receive payments, the site owner may still need to complete Wix Payments onboarding in the site dashboard.
 
+Connecting Wix Payments and being able to accept real checkout payments are two separate gates: the site may also need a premium eCommerce plan (Settings → Plans). Mention this even after a successful connect.
+
 ## Important Notes
 
 1. Never invent or assume user identity/business details.
-2. Always obtain explicit user consent before calling connect.
+2. Always obtain explicit user consent before calling connect — this creates a real Wix Payments account and records a legally-binding Terms of Service acceptance under the name provided.
 3. Use the exact accepted values provided by the user.
 4. Verify readiness by testing a real payment flow (for example, create payment link) after setup.