bookings: document booking gotchas on a minimally-provisioned site#385
Draft
omrimn wants to merge 1 commit into
Draft
bookings: document booking gotchas on a minimally-provisioned site#385omrimn wants to merge 1 commit into
omrimn wants to merge 1 commit into
Conversation
When Wix Bookings is installed via the apps-installer on a bare site (no
dashboard/CLI business setup), three things bite that the current docs don't
cover — all verified live:
- createBooking fails with "Resource settings conflict for resource type …"
(or "No available slot") even though listAvailabilityTimeSlots returned
bookable slots, because the default staff isn't bound to a location. The
"omit resource, Wix auto-assigns" shortcut doesn't apply here; pass
resource._id AND location { _id, locationType: "OWNER_BUSINESS" } explicitly.
- The root cause is that the site has no business location (locations/v1 query
returns []), so the APPOINTMENT service's placeholder location can't resolve.
Create a default business location first (timeZone is required).
- A free service (payment.rateType NO_FEE) rejects payment.options.online:true
("applicable only to FIXED or VARIED") — use inPerson:true instead.
Framed as edge-case notes for the apps-installer-on-a-bare-site path; sites set
up via the dashboard/CLI already have a location and aren't affected.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Three additive notes to the Bookings vertical docs (
references/bookings/INSTRUCTIONS.md+SERVICES_DATA.md), all hit and verified live while wiring Wix Bookings into a headless project on a site where Bookings had just been installed via the apps-installer (no dashboard/CLI business setup):createBooking→ "Resource settings conflict for resource type …" (orNo available slot) even thoughlistAvailabilityTimeSlotsreturned bookable slots. The current doc says "omitresource— Wix auto-assigns." That shortcut fails here because the default staff isn't bound to a location. Fix: passresource._id(the staff/Business-OwnerresourceId) andlocation: { _id: <slot.location._id>, locationType: "OWNER_BUSINESS" }explicitly.Root cause — no business location. A bare apps-installer install leaves
locations/v1/locations/queryreturning[], and the APPOINTMENT service gets the placeholder location id123e4567-…, which can't resolve at booking time. Added a failure-mode row: create a default business location first viaPOST /locations/v1/locations(timeZoneis required), then book againstOWNER_BUSINESS.Free service (
NO_FEE) rejectspayment.options.online: true("applicable only to FIXED or VARIED"). UseinPerson: trueinstead. Added to the seed failure-modes table next to the existingpayment.optionsrow.Scope / framing
These are framed as edge-case notes for the apps-installer-on-a-bare-site path. Sites set up through the Bookings dashboard or the CLI already have a business location and a location-bound default staff, so the existing "omit resource" guidance still holds for them — these notes just cover the case where it doesn't.
Provenance
Each was reproduced against a live site while building a headless Bookings integration end-to-end (createBooking → confirmBooking → booking visible in the dashboard). Docs-only change — no code paths touched.