wix_bookings_create_update_service id: wix_bookings_create_update_service Content

Technical Step-by-Step Instructions: Creating or Updating a Wix Bookings Service (Real-World, API-First)

Description

Below are the recommended steps to successfully create or update a Wix Bookings service (or several at once) on Wix, with real-world troubleshooting and fixes for common API issues.

Article URL

https://dev.wix.com/docs/kb-only/MCP_REST_RECIPES_KB_ID/wix_bookings_create_update_service

Prerequisites

Required App Installations

Before creating services, ensure Wix Bookings is installed on the site:

1. Wix Bookings - Core app for booking functionality
   • Usually pre-installed on business sites
   • Verify installation by querying existing services or staff members
   • Install via Apps Installer API if needed

App Installation Process

If you encounter app-related errors, install the required apps using the Apps Installer API.

Steps:

1. Identify the missing app from error messages (typically 428 "App not installed")
2. Use the Apps Installer API to install the required app
3. Verify installation by testing basic functionality

For detailed app installation procedures, refer to:

• Apps Installer API Documentation
• Business setup recipes for comprehensive app installation workflows
• API error responses which typically indicate the specific app needed

Overview

A Bookings service defines a time based offering and includes the following considerations:

• type - for detailed information about service type - refer to the article
• APPOINTMENT - Appointments allow customers to book services at their preferred time during the business hours. For example, a hair salon might offer different appointment-based hair cutting and styling services. Appointments appear in the booking calendar once they're booked by a customer. Not-yet-booked times during the business hours are displayed as available slots to potential customers while booking. The availability of the service is based on the availability of the staff member providing it
• CLASS - A class is a single event or a series of recurring events that multiple customers can book. For example, a yoga studio might offer a twice-weekly vinyasa flow class. Classes may have a set end date or continue indefinitely. If a class includes more than a single event, customers can sign up for 1, several, or all of the events. Upon creation, classes are listed immediately in the booking calendar.
• COURSE - A course starts and ends on pre-defined dates with a limited number of events that multiple customers can book. For example, a yoga studio might offer a teacher training course with 5 events. In contrast to classes, customers must book the entire course. Upon creation, courses are displayed immediately in the booking calendar.
• Staff Member - a resource required in order to provide a service. REST A staff member availability is defined by the schedule associated with the staff member, by default it is the main business schedule and cannot be modified by schedule APIs, but a staff member can have its own schedule by calling assignWorkingHoursSchedule which allows the staff member to have its own availability. The property staffMember.usesDefaultWorkingHours defines whether the default hours (business hours) are used.
• Schedule (availability) - availbility is defined by Events (SDK | REST) defined on a schedule.
• The schedule which defines the service availability is based on the service type.
• For appointment service, it is based on the schedule of staff members which provides it (service.staffMemberIds which is mapped to staffMember.resourceId). In order to fetch the staff schedule you should retrieve the staff memeber with RESOURCE_DETAILS fieldmask and read the schedule id from the staffMember.resource.eventsSchedule.id - This is needed if you wish to define the staff member's availability as part of the process
• For classes and courses it is based on the schedule of the service itself (service.schedule)
• When creating an APPOINTMENT service and specifying staffMemberIds, ensure you are using the staff member's resourceId, not their primary staff member id.
• Service Images - the service may have several images - service.media.mainMedia - presented in the services list, service.media.coverMedia - presented in the service page and service.media.items - array of images presented as a gallery in the service page for site visitors.
• In order to add a media (image) to a service, it should first be defined in Wix Media Manager - search existing (SDK | REST) or new (SDK | REST)
• You should only set the image id (for example item.id -> service.media.mainMedia.id) there is no need to set the entire object.

CRITICAL: Staff Assignment Behavior by Service Type

APPOINTMENT Services:

• Staff assignment WORKS: Can specify staffMemberIds array with staff member resourceId values
• Behavior: Service availability based on assigned staff schedules
• Example: Personal training session assigned to specific trainer

CLASS and COURSE Services:

• Staff assignment IGNORED: Setting staffMemberIds has no effect on service creation
• Behavior: Service uses its own schedule (service.schedule), not staff schedules
• Workaround: Staff association must be handled separately through calendar events or other mechanisms
• Example: Yoga class where any qualified instructor can teach

This is a critical API limitation that affects service planning and staff resource management.

IMPORTANT NOTES

• If I am writing javascript/typescript code I MUST used the SDK documentations when both REST and SDK links are provided, if I am attempting to call APIs (site level APIs) or if the code is other development language I MUST used the REST documentations when both REST and SDK links are provided
• I MUST read the full articles about service types, service payments, service location in order to fully understand how to set the service properties
• If the service type is CLASS or COURSE I MUST read the full articles service's schedule and events mentioned before
• If the service type is APPOINTMENT I MUST read the relevant full article about staff members (SDK | REST) in order to determine whether I should create a new staff memeber (or members)
• For free service I MUST set the service.payment.rateType as "NO_FEE" and service.payment.online as false
• For paid service I MUST set the service.payment.fixed.price.value (must be above 0) as well as service.payment.fixed.price.currency
• Always Prioritize Reading Full API Method Documentation: this overview article provides a general workflow. However, it repeatedly stresses the importance of reading the full documentation for each specific REST/SDK method you intend to use. This is critical for understanding detailed requirements.
• I should pay close attention to all required fields, data types, enum values, and specific ID types (e.g., resourceId vs. id) as defined in the detailed schema of each API endpoint. The overview article serves as a guide but doesn't replace the need to consult these specifics.

Service Categories - CRITICAL for UI Visibility

IMPORTANT: Services without categories may not appear in category-based UI filters, which are commonly used in booking interfaces.

Service Category Considerations:

• Default Behavior: Services created without explicit category assignment may not be visible in filtered views
• UI Impact: Many booking interfaces filter services by category.id, hiding uncategorized services
• Best Practice: Always assign services to appropriate categories during creation

Category Management Steps:

1. Query existing categories using Query Categories to see available options
2. Create new category if needed using Create Category
3. Assign category during service creation by including category.id in the service object
4. Update existing services using Update Service to add missing categories

Common Category Filter Patterns:

{
  "filter": {
    "category.id": {
      "$exists": true
    }
  }
}

This filter will only show services with assigned categories, making uncategorized services invisible to users.

Querying Existing Services

You can retrieve a list of existing booking services using the Query Services endpoint. This allows you to filter, sort, and page through up to 100 services at a time, making it easy to find and manage your current offerings.

Steps

0. Query and Setup Categories (CRITICAL FIRST STEP)

1. Query existing categories using queryCategories API (REST) to identify available categories
2. Create category if needed using createCategory API (REST) if no suitable category exists
3. Record category ID for use in service creation - this prevents services from being hidden in UI filters

1. Define staff member to use

1. Either create a staff member or select from the existing ones using the staff member APIs.
2. For new one, create a staff member using createStaffMember API (SDK | REST) and keep the response staffMember.id (staff member ID) and resourceId (to be used in service.staffMemberIds in APPOINTMENT service)
3. If you wish to update the working hours of the staff member use the staff member ID (just created or known from previous calls) to call getStaffMember API (SDK | REST) in order to their resource.eventsSchedule.id (schedule ID).
4. If you wish to use an existing staff member but ID is unknown use queryStaffMembers API (SDK | REST), specifying RESOURCE_DETAILS in the fields parameter. Save the relevant staff member ID, resourceId (for service.staffMemberIds) and their resource.eventsSchedule.id.

Note for Service Type Planning:

• For APPOINTMENT services: Staff assignment is required and functional
• For CLASS/COURSE services: Staff assignment is ignored; plan alternative staff management approach

2. Creating or Updating a service

Based on the information gathered above, use the relevant API based on the desired outcome, In case you wish to create a service (one or more) use the bulkCreateServices endpoint (SDK | REST), in order to update a service, you can update several services at once, using bulkUpdateServices (SDK | REST) and if you wish to update serval services by a criteria (without even retrieving them) you can use bulkUpdateServicesByFilter (SDK | REST).

CRITICAL: Include Category Assignment

• Always specify service.category.id when creating services to ensure UI visibility
• Use category ID obtained from Step 0 (category setup)
• Example service object structure:

{
  "service": {
    "name": "Your Service Name",
    "type": "APPOINTMENT",
    "category": {
      "id": "your-category-id-here"
    },
    // ... other service properties
  }
}

Service Type Specific Considerations:

• APPOINTMENT: Include staffMemberIds with staff resourceId values AND category.id
• CLASS/COURSE: Omit staffMemberIds or expect them to be ignored; focus on service.schedule configuration AND category.id

3. Set the availability of the service

Once the service and staff member are available, you can define when the service is available,

1. Define the schedule to use based on the service type.

• In APPOINTMENT service, the staff member working hours determines the service availability, if the staff member availability is different from the business' working hours, call assignWorkingHoursSchedule (SDK | REST). specify the staffMember.id and use the resource.eventsSchedule.id retrieved previously as the scheduleId and define new availability for this staff member.
• In CLASS or COURSE services, use the service.schedule.id from the service created/updated

1. use bulkCreateEvents (SDK | REST) to create the events that dictates the availability or bulkUpdateEvents (SDK | REST) to update existing schedule events.

• The event should include at least one resourse (a staff member/room/etc.) in the event.resources array, it should be the resourceId of the staff member defined previously.
• The event.scheduleId should include the schedule Id of the staff member when setting APPOINTMENT availability and the service.schedule.id for CLASS or COURSE.
• The event.type should be according to the created event - for staff member working hours it should be WORKING_HOURS when creating a CLASS it should be CLASS and when creating a COURSE it should be COURSE

Troubleshooting Common Issues

Services Not Appearing in UI Filters:

• Problem: Services created without category assignment are invisible in category-based filters
• Root Cause: Many UI implementations filter by category.id existence or specific category values
• Solution: Query all services, identify those missing categories, and update them using bulk update operations
• Prevention: Always assign categories during service creation (Step 0)

Staff Assignment Not Working for CLASS/COURSE Services:

• Problem: Setting staffMemberIds in CLASS or COURSE services appears to be ignored
• Solution: This is expected behavior; use service schedules instead of staff assignments
• Alternative: Manage staff-to-class relationships through calendar events or custom data structures

App Not Installed Errors:

• Problem: 428 "App not installed" errors when creating services
• Solution: Install Wix Bookings app using Apps Installer API before creating services
• Verification: Query existing services to confirm app installation

Resource ID vs Staff ID Confusion:

• Problem: Using wrong ID type for staffMemberIds array
• Solution: Always use staffMember.resourceId, not staffMember.id
• Verification: Query staff with RESOURCE_DETAILS fieldMask to get correct IDs

Service Schedule vs Staff Schedule Confusion:

• Problem: Mixing up schedule IDs between service and staff schedules
• Solution:
  • APPOINTMENT: Use staff schedule ID (staffMember.resource.eventsSchedule.id)
  • CLASS/COURSE: Use service schedule ID (service.schedule.id)

IMPORTANT NOTES

• I MUST read the full article about the REST/SDK method I wish to use
• onlineBooking Field: The onlineBooking object (e.g., {"enabled": true}) is a required field when creating services, even if not explicitly highlighted as mandatory in the high-level overview. This is a schema-level requirement.
• Event Creation (BulkCreateEvents): When specifying recurrenceRule.days, I MUST use full day names (e.g., "TUESDAY", "FRIDAY")
• The recurrenceRule.days field within an event object can only accept a single day of the week (e.g., ["TUESDAY"]).
• If I need to set up recurring events for multiple days of the week (e.g., a staff member working every Tuesday and Friday), I MUST define a separate event for each day and send them as separate items for BulkCreateEvents.
• Start Dates for Recurring Events: Recurring events must have a start.localDate that is today or in the future, relative to the server's current time. If I am not sure what the current date and time are I MUST check it.
• When setting event.type as WORKING_HOURS (APPOINTMENT) I MUST call assignWorkingHoursSchedule BEFORE CREATING THE EVENTS so that the staff member is no longer linked to the business working hours
• When setting event.type as CLASS or COURSE I MUST use the service schedule id, so the service has to exist (created/updated) before setting the availability of it

Booking REST API Documentation Reference

• Query Categories
• Create Category
• Update Service
• Create Staff Member
• Get Staff Member
• Query Staff Members
• Bulk Create Services
• Bulk Update Services
• Bulk Update Services By Filter
• Assign Working Hours Schedule
• Bulk Create Events
• Media Manager: Search Files
• Media Manager: Bulk Import File
• Query Services
• Apps Installer API