Diagnose Bookings Availability Issues

When to use

A site owner reports that an appointment-based service has no bookable time slots — the calendar shows nothing available, or customers can't book. This recipe finds the cause.

Diagnosis is endpoint-first:

1. Call DiagnoseAvailability. It returns ordered, machine-readable reason codes — each with a suggested owner action — for setup/configuration problems. Fix what it reports and re-check.
2. Fall back to ListAvailabilityTimeSlots only when the endpoint is inconclusive. The endpoint detects setup/configuration problems; it does not evaluate booking policy or remaining capacity, so those are checked here.

Prerequisites

• Wix Bookings app installed (App ID: 13d21c63-b5ec-5912-8397-c3a5ddb27a97).

• 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.

• Authorization: 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 to the caller — that's an auth problem, not "no cause found." Ensure the calling context carries the permission before treating a 403 as inconclusive.

Step 1 — 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 2.
• 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.

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

Response

• 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 2.

Reason codes → owner fix (agent-internal — never shown to the user)

Endpoint errors

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 2 — Fallback when the endpoint is inconclusive

Empty reasons + still no bookable slots usually means the cause is one the endpoint doesn't evaluate: booking policy or remaining capacity. Call ListAvailabilityTimeSlots for the same service and window, and inspect the returned slots:

• 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 for the ListAvailabilityTimeSlots request shape.

Presenting the diagnosis to the user

The diagnosis is part of a conversation with a site owner. Reply in plain, friendly language:

• Don't expose the internals — no reason codes, suggestedAction enums, raw JSON, endpoint names, or field paths.
• Lead with the cause in plain English, then give the concrete fix as the 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 the result 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." In particular, on the resource-only path never say the staff "have working hours set"; the check doesn't verify that. Don't imply the service is fine.

Plain-language phrasing per cause:

Example conversational reply (for a location-mismatch result):

Common causes (quick reference)

Popular reasons a service shows no availability, and where each surfaces:

Gotchas

• hasAvailability: false + empty reasons ≠ a confirmed problem. It means "no blocking cause detected." Always confirm with ListAvailabilityTimeSlots.
• The endpoint is ALPHA and feature-toggled. If it returns nothing for an obviously broken service, the diagnoseAvailabilityEndpoint toggle may be off — fall back to Step 2.
• 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).
• deep: true needs a serviceId (resource-only + deep → MISSING_ARGUMENTS) and only refines a "no windows" result — it does nothing when windows already exist.
• The endpoint ignores booking policy and capacity — those are Step 2.
• 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
• Services V2
• Staff Members
• Booking Policies
• Related recipes: Bookings Staff Setup · Create and Update Booking Services · End-to-End Booking Flow