/wix-manage

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.

✅ "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.
• 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 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).
• Owner narrows to a specific date/time ("why nothing on 3 Aug from 4pm?") and the slot check for that window comes back empty → this is a "why" question. Run the diagnosis (Step 2 → Step 3). Do not answer it from the empty slot list alone.

Scope: appointment-based services.

🚫 Never invent the cause (read first)

An empty ListAvailabilityTimeSlots tells you there is no availability — not why. The reason for an empty result comes only from the checks in Steps 2–4 (service.hidden / onlineBooking, then DiagnoseAvailability, then policy/capacity). Never state a cause you didn't get from them — do not guess "the staff aren't scheduled," "it's outside working hours," a date-range problem, or anything else from a zero slot count. If you haven't run the diagnosis, you don't know the reason yet: run it, then report what it returns.

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 to verify and Install Wix Apps 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.

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

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 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:

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

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"
  }'

Response

{
  "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.

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 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 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:

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:

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).
• Never state a cause you didn't diagnose. A zero slot count from ListAvailabilityTimeSlots means "no availability," not a reason. Guessing "the staff aren't scheduled to work" (or any other cause) from an empty list is the failure this recipe exists to prevent — run DiagnoseAvailability and report the code it returns. This applies especially when the owner narrows to a specific date/time and it comes back empty: that's a diagnosis trigger, not a status reply.
• A date-range restriction is a distinct cause — don't blame staff hours for it. When a service is only offered within a set date range and the owner asks about a date outside it, DiagnoseAvailability returns REQUESTED_DATE_OUTSIDE_SERVICE_AVAILABILITY_RANGE on the standard call, ahead of the deep working-hours/blocked reasons. If you see it, say the service isn't offered on those dates — not that staff aren't scheduled (they may well work then; the service just isn't offered). It covers dates both before and after the range.
• 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
• Services V2
• Staff Members
• Booking Policies
• Related recipes: Bookings Staff Setup · Create and Update Booking Services · End-to-End Booking Flow