@wix/agent-skills 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +111 -0
  3. package/package.json +29 -0
  4. package/skills/wix-app/SKILL.md +344 -0
  5. package/skills/wix-app/references/APP_IDENTIFIERS.md +35 -0
  6. package/skills/wix-app/references/APP_MARKET_REVIEW.md +311 -0
  7. package/skills/wix-app/references/APP_VALIDATION.md +171 -0
  8. package/skills/wix-app/references/BACKEND_API.md +233 -0
  9. package/skills/wix-app/references/BACKEND_EVENT.md +116 -0
  10. package/skills/wix-app/references/CODE_QUALITY.md +33 -0
  11. package/skills/wix-app/references/CUSTOM_ELEMENT_WIDGET.md +587 -0
  12. package/skills/wix-app/references/DASHBOARD_MENU_PLUGIN.md +157 -0
  13. package/skills/wix-app/references/DASHBOARD_MODAL.md +283 -0
  14. package/skills/wix-app/references/DASHBOARD_PAGE.md +403 -0
  15. package/skills/wix-app/references/DASHBOARD_PLUGIN.md +205 -0
  16. package/skills/wix-app/references/DATA_COLLECTION.md +451 -0
  17. package/skills/wix-app/references/DOCUMENTATION.md +42 -0
  18. package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md +65 -0
  19. package/skills/wix-app/references/EMBEDDED_SCRIPT.md +468 -0
  20. package/skills/wix-app/references/EXTENSION_REGISTRATION.md +96 -0
  21. package/skills/wix-app/references/SERVICE_PLUGIN.md +235 -0
  22. package/skills/wix-app/references/SITE_PLUGIN.md +436 -0
  23. package/skills/wix-app/references/STORES_VERSIONING.md +334 -0
  24. package/skills/wix-app/references/backend-event/COMMON-EVENTS.md +84 -0
  25. package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md +345 -0
  26. package/skills/wix-app/references/dashboard-menu-plugin/blog-slots.md +71 -0
  27. package/skills/wix-app/references/dashboard-menu-plugin/bookings-slots.md +58 -0
  28. package/skills/wix-app/references/dashboard-menu-plugin/crm-slots.md +8 -0
  29. package/skills/wix-app/references/dashboard-menu-plugin/ecommerce-slots.md +17 -0
  30. package/skills/wix-app/references/dashboard-menu-plugin/events-slots.md +29 -0
  31. package/skills/wix-app/references/dashboard-menu-plugin/restaurants-slots.md +27 -0
  32. package/skills/wix-app/references/dashboard-menu-plugin/stores-slots.md +35 -0
  33. package/skills/wix-app/references/dashboard-page/API_SPEC.md +138 -0
  34. package/skills/wix-app/references/dashboard-page/DASHBOARD_API.md +573 -0
  35. package/skills/wix-app/references/dashboard-page/DYNAMIC_PARAMETERS.md +269 -0
  36. package/skills/wix-app/references/dashboard-page/ECOM_NAVIGATION.md +164 -0
  37. package/skills/wix-app/references/dashboard-plugin/SLOTS.md +294 -0
  38. package/skills/wix-app/references/data-collection/WIX_DATA.md +270 -0
  39. package/skills/wix-app/references/data-collection/extension-template.ts +107 -0
  40. package/skills/wix-app/references/editor-react-component/ACCESSIBILITY.md +138 -0
  41. package/skills/wix-app/references/editor-react-component/COMPONENT-API.md +454 -0
  42. package/skills/wix-app/references/editor-react-component/COMPONENT-CONFIGURATION.md +165 -0
  43. package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md +576 -0
  44. package/skills/wix-app/references/editor-react-component/DIRECTIONALITY.md +170 -0
  45. package/skills/wix-app/references/editor-react-component/EDIT-FLOW.md +6 -0
  46. package/skills/wix-app/references/editor-react-component/PARTS.md +25 -0
  47. package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md +203 -0
  48. package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md +167 -0
  49. package/skills/wix-app/references/editor-react-component/REACT-PATTERNS.md +137 -0
  50. package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md +112 -0
  51. package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md +118 -0
  52. package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md +87 -0
  53. package/skills/wix-app/references/service-plugin/GIFT-CARDS.md +86 -0
  54. package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md +135 -0
  55. package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md +79 -0
  56. package/skills/wix-app/references/service-plugin/VALIDATIONS.md +68 -0
  57. package/skills/wix-app/references/site-plugin/EXAMPLES.md +311 -0
  58. package/skills/wix-app/references/site-plugin/SLOTS.md +263 -0
  59. package/skills/wix-design-system/SKILL.md +129 -0
  60. package/skills/wix-design-system/references/file-structure.md +56 -0
  61. package/skills/wix-design-system/scripts/wds.cjs +531 -0
  62. package/skills/wix-headless/SKILL.md +418 -0
  63. package/skills/wix-headless/references/DISCOVERY.md +332 -0
  64. package/skills/wix-headless/references/ORCHESTRATION.md +269 -0
  65. package/skills/wix-headless/references/SETUP.md +154 -0
  66. package/skills/wix-headless/references/blog/BLOG_CONTENT.md +152 -0
  67. package/skills/wix-headless/references/blog/BLOG_PAGES.md +299 -0
  68. package/skills/wix-headless/references/blog/BLOG_SETUP.md +218 -0
  69. package/skills/wix-headless/references/blog/INSTRUCTIONS.md +32 -0
  70. package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md +373 -0
  71. package/skills/wix-headless/references/cms/FAQ_KNOWLEDGE_BASE.md +229 -0
  72. package/skills/wix-headless/references/cms/INSTRUCTIONS.md +40 -0
  73. package/skills/wix-headless/references/cms/PORTFOLIO.md +454 -0
  74. package/skills/wix-headless/references/cms/RESOURCE_LIBRARY.md +356 -0
  75. package/skills/wix-headless/references/cms/TEAM_DIRECTORY.md +299 -0
  76. package/skills/wix-headless/references/commands/install-app.md +42 -0
  77. package/skills/wix-headless/references/commands/known-apps.json +5 -0
  78. package/skills/wix-headless/references/commands/mcp-bootstrap.md +28 -0
  79. package/skills/wix-headless/references/designer/INSTRUCTIONS.md +828 -0
  80. package/skills/wix-headless/references/ecom/CART_PAGES.md +120 -0
  81. package/skills/wix-headless/references/ecom/CART_WIRING.md +103 -0
  82. package/skills/wix-headless/references/ecom/COMPONENTS_CSS.md +132 -0
  83. package/skills/wix-headless/references/ecom/INSTRUCTIONS.md +59 -0
  84. package/skills/wix-headless/references/forms/CONTACT_FORM.md +477 -0
  85. package/skills/wix-headless/references/forms/INSTRUCTIONS.md +43 -0
  86. package/skills/wix-headless/references/gift-cards/COMPONENTS.md +119 -0
  87. package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md +51 -0
  88. package/skills/wix-headless/references/gift-cards/PAGES.md +129 -0
  89. package/skills/wix-headless/references/images/INSTRUCTIONS.md +359 -0
  90. package/skills/wix-headless/references/shared/BUILD_NOISE.md +8 -0
  91. package/skills/wix-headless/references/shared/IMAGE_GENERATION.md +185 -0
  92. package/skills/wix-headless/references/shared/IMPLEMENTER.md +155 -0
  93. package/skills/wix-headless/references/shared/MCP_PREFIX.md +105 -0
  94. package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md +97 -0
  95. package/skills/wix-headless/references/shared/RETURN_CONTRACT.md +423 -0
  96. package/skills/wix-headless/references/shared/STYLING.md +117 -0
  97. package/skills/wix-headless/references/stores/BACK_IN_STOCK.md +178 -0
  98. package/skills/wix-headless/references/stores/CATEGORY_PAGES.md +86 -0
  99. package/skills/wix-headless/references/stores/COMPONENTS_CSS.md +129 -0
  100. package/skills/wix-headless/references/stores/HOME_AND_NAV.md +227 -0
  101. package/skills/wix-headless/references/stores/INSTRUCTIONS.md +96 -0
  102. package/skills/wix-headless/references/stores/PRODUCT_CATALOG_DATA.md +249 -0
  103. package/skills/wix-headless/references/stores/PRODUCT_PAGES.md +213 -0
  104. package/skills/wix-headless/references/stores/SHARED_WIRING.md +164 -0
  105. package/skills/wix-headless/references/verticals/_schema.json +160 -0
  106. package/skills/wix-headless/references/verticals/_schema.md +185 -0
  107. package/skills/wix-headless/references/verticals/blog.md +125 -0
  108. package/skills/wix-headless/references/verticals/cms.md +121 -0
  109. package/skills/wix-headless/references/verticals/ecom.md +96 -0
  110. package/skills/wix-headless/references/verticals/forms.md +106 -0
  111. package/skills/wix-headless/references/verticals/gift-cards.md +121 -0
  112. package/skills/wix-headless/references/verticals/stores.md +167 -0
  113. package/skills/wix-headless/scripts/check-manifest.mjs +198 -0
  114. package/skills/wix-headless/scripts/copy-utility-templates.mjs +153 -0
  115. package/skills/wix-headless/scripts/emit-design-tokens.mjs +77 -0
  116. package/skills/wix-headless/scripts/finalize-run-json.mjs +141 -0
  117. package/skills/wix-headless/scripts/init-site-json.mjs +63 -0
  118. package/skills/wix-headless/scripts/patch-decorative-slots.mjs +124 -0
  119. package/skills/wix-headless/scripts/plan-entity-image-waves.mjs +190 -0
  120. package/skills/wix-headless/scripts/preview.sh +45 -0
  121. package/skills/wix-headless/scripts/release.sh +73 -0
  122. package/skills/wix-headless/scripts/scaffold.sh +53 -0
  123. package/skills/wix-headless/scripts/seed-utilities.sh +55 -0
  124. package/skills/wix-headless/shared-utilities/analytics.ts +40 -0
  125. package/skills/wix-headless/shared-utilities/ricos.ts +179 -0
  126. package/skills/wix-headless/shared-utilities/wix-image.ts +72 -0
  127. package/skills/wix-headless/templates/ecom/CartBadge.tsx +84 -0
  128. package/skills/wix-headless/templates/ecom/CartView.tsx +543 -0
  129. package/skills/wix-headless/templates/ecom/cart.astro +13 -0
  130. package/skills/wix-headless/templates/ecom/components-ecom.css +215 -0
  131. package/skills/wix-headless/templates/ecom/discounts.ts +71 -0
  132. package/skills/wix-headless/templates/ecom/thank-you.astro +24 -0
  133. package/skills/wix-headless/templates/gift-cards/GiftCardPurchase.tsx +172 -0
  134. package/skills/wix-headless/templates/gift-cards/_home-teaser-snippet.astro +42 -0
  135. package/skills/wix-headless/templates/gift-cards/_nav-snippet.astro +11 -0
  136. package/skills/wix-headless/templates/gift-cards/components-gift-cards.css +219 -0
  137. package/skills/wix-headless/templates/gift-cards/gift-cards.astro +51 -0
  138. package/skills/wix-headless/templates/gift-cards/gift-cards.ts +75 -0
  139. package/skills/wix-headless/templates/stores/AddToCartButton.tsx +77 -0
  140. package/skills/wix-headless/templates/stores/BackInStockForm.tsx +176 -0
  141. package/skills/wix-headless/templates/stores/CategoryRail.astro +69 -0
  142. package/skills/wix-headless/templates/stores/ProductCard.astro +79 -0
  143. package/skills/wix-headless/templates/stores/ProductPurchase.tsx +397 -0
  144. package/skills/wix-headless/templates/stores/SeoTags.astro +21 -0
  145. package/skills/wix-headless/templates/stores/back-in-stock.ts +67 -0
  146. package/skills/wix-headless/templates/stores/categories.ts +155 -0
  147. package/skills/wix-headless/templates/stores/category/[slug].astro +130 -0
  148. package/skills/wix-headless/templates/stores/components-stores.css +295 -0
  149. package/skills/wix-headless/templates/stores/products/[slug].astro +128 -0
  150. package/skills/wix-headless/templates/stores/products/index.astro +101 -0
  151. package/skills/wix-manage/SKILL.md +280 -0
  152. package/skills/wix-manage/references/app-installation/install-wix-apps.md +155 -0
  153. package/skills/wix-manage/references/app-installation/list-installed-apps.md +124 -0
  154. package/skills/wix-manage/references/blog/how-to-create-blog-posts.md +226 -0
  155. package/skills/wix-manage/references/bookings/booking-service-policy-setup.md +95 -0
  156. package/skills/wix-manage/references/bookings/booking-system-integration-gaps.md +416 -0
  157. package/skills/wix-manage/references/bookings/bookings-staff-setup.md +255 -0
  158. package/skills/wix-manage/references/bookings/create-and-update-booking-services.md +462 -0
  159. package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md +278 -0
  160. package/skills/wix-manage/references/bookings/external-calendar-integration.md +258 -0
  161. package/skills/wix-manage/references/bookings/multi-resource-service-creation.md +231 -0
  162. package/skills/wix-manage/references/calendar/configure-default-business-hours.md +226 -0
  163. package/skills/wix-manage/references/cms/cms-data-items-crud.md +422 -0
  164. package/skills/wix-manage/references/cms/cms-data-operations-extended.md +263 -0
  165. package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md +136 -0
  166. package/skills/wix-manage/references/cms/cms-references-and-relationships.md +160 -0
  167. package/skills/wix-manage/references/cms/cms-schema-management.md +143 -0
  168. package/skills/wix-manage/references/contacts/bulk-delete-contacts.md +73 -0
  169. package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md +67 -0
  170. package/skills/wix-manage/references/domains/domain-search-and-purchase.md +434 -0
  171. package/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md +420 -0
  172. package/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md +267 -0
  173. package/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md +290 -0
  174. package/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md +300 -0
  175. package/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md +364 -0
  176. package/skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md +315 -0
  177. package/skills/wix-manage/references/ecommerce/flow-stock-mover.md +308 -0
  178. package/skills/wix-manage/references/ecommerce/flow-upsell-boost.md +271 -0
  179. package/skills/wix-manage/references/ecommerce/goal-clear-inventory.md +118 -0
  180. package/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md +122 -0
  181. package/skills/wix-manage/references/ecommerce/goal-increase-aov.md +132 -0
  182. package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md +148 -0
  183. package/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md +146 -0
  184. package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md +118 -0
  185. package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md +88 -0
  186. package/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md +108 -0
  187. package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md +124 -0
  188. package/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md +299 -0
  189. package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md +582 -0
  190. package/skills/wix-manage/references/ecommerce/setup-coupons.md +338 -0
  191. package/skills/wix-manage/references/ecommerce/setup-discount-rules.md +444 -0
  192. package/skills/wix-manage/references/ecommerce/setup-shipping-rates.md +86 -0
  193. package/skills/wix-manage/references/ecommerce/setup-shipping-regions.md +56 -0
  194. package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md +209 -0
  195. package/skills/wix-manage/references/ecommerce/skill-graph.md +139 -0
  196. package/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md +124 -0
  197. package/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md +95 -0
  198. package/skills/wix-manage/references/events/list-events.md +203 -0
  199. package/skills/wix-manage/references/forms/create-form.md +260 -0
  200. package/skills/wix-manage/references/get-paid/create-payment-links.md +212 -0
  201. package/skills/wix-manage/references/get-paid/how-to-setup-wix-payments.md +57 -0
  202. package/skills/wix-manage/references/get-paid/payment-links-for-bookings.md +101 -0
  203. package/skills/wix-manage/references/media/upload-media-to-wix.md +216 -0
  204. package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md +77 -0
  205. package/skills/wix-manage/references/pricing-plans/pricing-plans-bookings-integration.md +166 -0
  206. package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md +336 -0
  207. package/skills/wix-manage/references/rich-content/ricos-converter-service.md +295 -0
  208. package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md +59 -0
  209. package/skills/wix-manage/references/sites/create-site-from-template.md +183 -0
  210. package/skills/wix-manage/references/sites/query-sites.md +125 -0
  211. package/skills/wix-manage/references/stores/add-store-pages-to-site.md +57 -0
  212. package/skills/wix-manage/references/stores/bulk-create-products-with-options.md +1041 -0
  213. package/skills/wix-manage/references/stores/create-product-catalog-v1.md +125 -0
  214. package/skills/wix-manage/references/stores/create-product-from-image.md +824 -0
  215. package/skills/wix-manage/references/stores/create-product-with-options-catalog-v3.md +566 -0
  216. package/skills/wix-manage/references/stores/find-products-query-and-search-catalog-v3.md +194 -0
  217. package/skills/wix-manage/references/stores/query-products-catalog-v1.md +80 -0
  218. package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md +99 -0
  219. package/skills/wix-manage/references/stores/update-product-pre-order.md +213 -0
  220. package/skills/wix-manage/references/stores/update-product-with-options.md +318 -0
@@ -0,0 +1,462 @@
1
+ ---
2
+ name: "Create and Update Booking Services"
3
+ description: Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
4
+ ---
5
+
6
+ # Technical Step-by-Step Instructions: Creating or Updating a Wix Bookings Service (Real-World, API-First)
7
+
8
+ ## Description
9
+
10
+ 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.
11
+
12
+ ---
13
+
14
+ ## Prerequisites
15
+
16
+ - **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
17
+
18
+ > **Note:** If you receive errors from Bookings APIs, the Wix Bookings app may not be installed on the site. 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 if missing.
19
+
20
+ ## Overview
21
+
22
+ A Bookings service defines a time based offering and includes the following considerations:
23
+
24
+ - type - for detailed information about service type - refer to the [article](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
25
+ - `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
26
+ - `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.
27
+ - `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.
28
+ - Staff Member - a resource required in order to provide a service. [REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member) 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.
29
+ - Schedule (availability) - availability is defined by `Events` ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/introduction)) defined on a schedule.
30
+ - The schedule which defines the service availability is based on the service type.
31
+ - 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 member 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
32
+ - For classes and courses it is based on the schedule of the service itself (`service.schedule`)
33
+ - When creating an APPOINTMENT service and specifying `staffMemberIds`, ensure you are using the staff member's resourceId, not their primary staff member id.
34
+ - 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.
35
+ - In order to add a media (image) to a service, it should first be defined in Wix Media Manager - search existing ([REST](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/search-files)) or new ([REST](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/bulk-import-file))
36
+ - You should only set the image id (for example `item.id` -> `service.media.mainMedia.id`) there is no need to set the entire object.
37
+
38
+ ### Service Type Selection Guide
39
+
40
+ Choose based on these documented behaviors:
41
+
42
+ - **APPOINTMENT**: Customer picks available time slot. Availability based on staff schedules. One customer (or dedicated group) per booking.
43
+ - **CLASS**: Business sets recurring times. Multiple customers book same session. Customers can book 1, some, or all sessions in series.
44
+ - **COURSE**: Business sets fixed series. Multiple customers book. Customers must book entire course (all sessions).
45
+
46
+ When unsure, refer to [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types).
47
+
48
+ ### CRITICAL: Staff Assignment Behavior by Service Type
49
+
50
+ **APPOINTMENT Services:**
51
+
52
+ - **Staff assignment WORKS**: Can specify `staffMemberIds` array with staff member `resourceId` values
53
+ - **Behavior**: Service availability based on assigned staff schedules
54
+ - **Example**: Personal training session assigned to specific trainer
55
+
56
+ **CLASS and COURSE Services:**
57
+
58
+ - **Staff assignment IGNORED**: Setting `staffMemberIds` has no effect on service creation
59
+ - **Behavior**: Service uses its own schedule (`service.schedule`), not staff schedules
60
+ - **Workaround**: Staff association must be handled separately through calendar events or other mechanisms
61
+ - **Example**: Yoga class where any qualified instructor can teach
62
+
63
+ This is a critical API limitation that affects service planning and staff resource management.
64
+
65
+ ### IMPORTANT NOTES
66
+
67
+ - I MUST read the full articles about [service types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types), [service payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments), [service location](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-locations) in order to fully understand how to set the service properties
68
+ - If the service type is `CLASS` or `COURSE` I MUST read the full articles service's _schedule_ and _events_ mentioned before
69
+ - If the service type is `APPOINTMENT` I MUST read the relevant full article about staff members ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/introduction)) in order to determine whether I should create a new staff member (or members)
70
+ - For free service I MUST set `service.payment.rateType` as `"NO_FEE"` and `service.payment.options.inPerson` as `true` (at least one payment option must be true)
71
+ - For paid service I MUST set the `service.payment.fixed.price.value` (must be above 0) as well as `service.payment.fixed.price.currency`
72
+ - When changing a free service to a paid service, I MUST update `service.payment.rateType` from `"NO_FEE"` to `"FIXED"` in the same request where I set `service.payment.fixed.price`; patching only `fixed.price` on a `NO_FEE` service fails validation.
73
+
74
+ ### Payment Options Validation Rules
75
+
76
+ | rateType | `options.online` | `options.inPerson` | Valid? |
77
+ | -------- | ---------------- | ------------------ | --------------------------------- |
78
+ | FIXED | true | false | ✓ |
79
+ | FIXED | false | true | ✓ |
80
+ | FIXED | true | true | ✓ |
81
+ | VARIED | true | false | ✓ |
82
+ | VARIED | false | true | ✓ |
83
+ | NO_FEE | false | true | ✓ |
84
+ | NO_FEE | true | false | ✗ (online not allowed for NO_FEE) |
85
+ | Any | false | false | ✗ (at least one must be true) |
86
+
87
+ - 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 method you intend to use. This is critical for understanding detailed requirements.
88
+ - 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.
89
+
90
+ ### Service Categories - CRITICAL for UI Visibility
91
+
92
+ **IMPORTANT**: Services without categories may not appear in category-based UI filters, which are commonly used in booking interfaces.
93
+
94
+ **Service Category Considerations:**
95
+
96
+ - **Default Behavior**: Services created without explicit category assignment may not be visible in filtered views
97
+ - **UI Impact**: Many booking interfaces filter services by `category.id`, hiding uncategorized services
98
+ - **Best Practice**: Always assign services to appropriate categories during creation
99
+
100
+ **Category Management Steps:**
101
+
102
+ 1. **Query existing categories** using [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories) to see available options
103
+ 2. **Create new category if needed** using [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
104
+ 3. **Assign category during service creation** by including `category.id` in the service object
105
+ 4. **Update existing services** using [Update Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service) to add missing categories
106
+
107
+ **Common Category Filter Patterns:**
108
+
109
+ ```json
110
+ {
111
+ "filter": {
112
+ "category.id": {
113
+ "$exists": true
114
+ }
115
+ }
116
+ }
117
+ ```
118
+
119
+ This filter will only show services with assigned categories, making uncategorized services invisible to users.
120
+
121
+ ### Querying Existing Services
122
+
123
+ You can retrieve a list of existing booking services using the [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/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.
124
+
125
+ ---
126
+
127
+ ## Steps
128
+
129
+ ### 0. Query and Setup Categories (CRITICAL FIRST STEP)
130
+
131
+ 1. **Query existing categories** using `queryCategories` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)) to identify available categories
132
+ 2. **Create category if needed** using `createCategory` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)) if no suitable category exists
133
+ 3. **Record category ID** for use in service creation - this prevents services from being hidden in UI filters
134
+
135
+ **Query Categories:**
136
+
137
+ ```bash
138
+ curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
139
+ -H 'Authorization: <AUTH>' \
140
+ -H 'Content-Type: application/json' \
141
+ -d '{ "query": {} }'
142
+ ```
143
+
144
+ **Create Category (if none exist):**
145
+
146
+ ```bash
147
+ curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
148
+ -H 'Authorization: <AUTH>' \
149
+ -H 'Content-Type: application/json' \
150
+ -d '{ "category": { "name": "General" } }'
151
+ ```
152
+
153
+ ### 1. Define staff member to use (REQUIRED for APPOINTMENT)
154
+
155
+ > **IMPORTANT:** For APPOINTMENT services, `staffMemberIds` is **required**. The API will return a 400 error without it. You must query staff members first to obtain a valid `resourceId`.
156
+
157
+ 1. **Query existing staff members** to get their `resourceId` values
158
+ 2. For new staff, create using `createStaffMember` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member)) and keep the response `staffMember.id` and `resourceId`
159
+ 3. If you wish to update working hours, call `getStaffMember` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/get-staff-member)) to get `resource.eventsSchedule.id`
160
+
161
+ **Query Staff Members (to get resourceId):**
162
+
163
+ ```bash
164
+ curl -X POST 'https://www.wixapis.com/bookings/v1/staff-members/query' \
165
+ -H 'Authorization: <AUTH>' \
166
+ -H 'Content-Type: application/json' \
167
+ -d '{
168
+ "query": {},
169
+ "fields": ["RESOURCE_DETAILS"]
170
+ }'
171
+ ```
172
+
173
+ Use the `resourceId` from the response (not `id`) in `staffMemberIds` when creating APPOINTMENT services.
174
+
175
+ **Staff Selection Strategy:**
176
+
177
+ - If a staff member has `default: true` → use it
178
+ - If only one staff member exists → use it
179
+ - If multiple exist → pick the first or most appropriate
180
+ - If none exist → create one using the [Staff Setup recipe](bookings-staff-setup.md)
181
+
182
+ **Service Type Requirements:**
183
+
184
+ - **APPOINTMENT**: `staffMemberIds` is **required** - API will fail without it
185
+ - **CLASS/COURSE**: `staffMemberIds` is ignored; use `service.schedule` instead
186
+
187
+ ### 2. Creating or Updating a service
188
+
189
+ Based on the information gathered above, use the relevant API based on the desired outcome.
190
+
191
+ - **Create services**: `bulkCreateServices` endpoint ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services))
192
+ - **Update single service**: `updateService` endpoint ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service))
193
+ - **Update services (bulk)**: `bulkUpdateServices` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-update-services))
194
+ - **Update by filter**: `bulkUpdateServicesByFilter` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-update-services-by-filter))
195
+ - **Get single service**: `getService` endpoint ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service))
196
+
197
+ **Create Service Example (paid APPOINTMENT, 60 minutes):**
198
+
199
+ ```bash
200
+ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
201
+ -H 'Authorization: <AUTH>' \
202
+ -H 'Content-Type: application/json' \
203
+ -d '{
204
+ "services": [{
205
+ "name": "Consultation",
206
+ "type": "APPOINTMENT",
207
+ "onlineBooking": { "enabled": true },
208
+ "staffMemberIds": ["<RESOURCE_ID_FROM_STEP_1>"],
209
+ "schedule": {
210
+ "availabilityConstraints": {
211
+ "sessionDurations": [60]
212
+ }
213
+ },
214
+ "payment": {
215
+ "rateType": "FIXED",
216
+ "options": { "online": true, "inPerson": false },
217
+ "fixed": {
218
+ "price": { "value": "50", "currency": "USD" }
219
+ }
220
+ },
221
+ "category": {
222
+ "id": "<CATEGORY_ID_FROM_STEP_0>"
223
+ }
224
+ }]
225
+ }'
226
+ ```
227
+
228
+ > **Note:** Currency may default to the site's business currency regardless of what you specify. Verify the response if currency is critical.
229
+
230
+ **Create Service Example (free APPOINTMENT, 60 minutes):**
231
+
232
+ ```bash
233
+ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
234
+ -H 'Authorization: <AUTH>' \
235
+ -H 'Content-Type: application/json' \
236
+ -d '{
237
+ "services": [{
238
+ "name": "Free Consultation",
239
+ "type": "APPOINTMENT",
240
+ "onlineBooking": { "enabled": true },
241
+ "staffMemberIds": ["<RESOURCE_ID_FROM_STEP_1>"],
242
+ "schedule": {
243
+ "availabilityConstraints": {
244
+ "sessionDurations": [60]
245
+ }
246
+ },
247
+ "payment": {
248
+ "rateType": "NO_FEE",
249
+ "options": { "online": false, "inPerson": true }
250
+ },
251
+ "category": {
252
+ "id": "<CATEGORY_ID_FROM_STEP_0>"
253
+ }
254
+ }]
255
+ }'
256
+ ```
257
+
258
+ **Create Service Example (CLASS with capacity):**
259
+
260
+ > **Note:** CLASS services do not use `staffMemberIds` or `sessionDurations`. After creation, you must create events via `bulkCreateEvents` using the returned `service.schedule.id` to define when the class occurs.
261
+
262
+ ```bash
263
+ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
264
+ -H 'Authorization: <AUTH>' \
265
+ -H 'Content-Type: application/json' \
266
+ -d '{
267
+ "services": [{
268
+ "name": "Yoga Class",
269
+ "type": "CLASS",
270
+ "onlineBooking": { "enabled": true },
271
+ "defaultCapacity": 20,
272
+ "payment": {
273
+ "rateType": "FIXED",
274
+ "options": { "online": true, "inPerson": false },
275
+ "fixed": {
276
+ "price": { "value": "25", "currency": "USD" }
277
+ }
278
+ },
279
+ "category": {
280
+ "id": "<CATEGORY_ID_FROM_STEP_0>"
281
+ }
282
+ }]
283
+ }'
284
+ ```
285
+
286
+ After creation, use the `service.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3).
287
+
288
+ **Required Fields:**
289
+
290
+ - `name` - Service name
291
+ - `type` - `APPOINTMENT`, `CLASS`, or `COURSE`
292
+ - `onlineBooking: { enabled: true }` - Required for all services
293
+ - `staffMemberIds` - **Required for APPOINTMENT only** (use `resourceId` values); ignored for CLASS/COURSE
294
+ - `schedule.availabilityConstraints.sessionDurations` - Duration in minutes (APPOINTMENT only)
295
+ - `defaultCapacity` - **Required for CLASS/COURSE** (max participants per session)
296
+ - `payment.options` - At least one of `online` or `inPerson` must be `true` (required for all services, including free; see validation table above)
297
+
298
+ **Service Type Specific Considerations:**
299
+
300
+ - **APPOINTMENT**: Must include `staffMemberIds` with staff `resourceId` values
301
+ - **CLASS/COURSE**: Omit `staffMemberIds`; configure `service.schedule` instead
302
+
303
+ **Update Service Example (PATCH):**
304
+
305
+ > **Note:** Updates require the current `revision` value (from a GET response) placed **inside** the `service` object, not at the top level.
306
+
307
+ ```bash
308
+ # First, get current service to obtain revision
309
+ curl -X GET 'https://www.wixapis.com/bookings/v2/services/<SERVICE_ID>' \
310
+ -H 'Authorization: <AUTH>'
311
+
312
+ # Then update with revision inside service object
313
+ curl -X PATCH 'https://www.wixapis.com/bookings/v2/services/<SERVICE_ID>' \
314
+ -H 'Authorization: <AUTH>' \
315
+ -H 'Content-Type: application/json' \
316
+ -d '{
317
+ "service": {
318
+ "revision": "<REVISION_FROM_GET>",
319
+ "category": {
320
+ "id": "<CATEGORY_ID>"
321
+ }
322
+ }
323
+ }'
324
+ ```
325
+
326
+ **Update free service to fixed price:**
327
+
328
+ When an existing service has `payment.rateType: "NO_FEE"` and the user asks to set a price, convert it to `FIXED` and set the price in the same update.
329
+
330
+ ```bash
331
+ # First, get current service to obtain revision and current payment settings
332
+ curl -X GET 'https://www.wixapis.com/bookings/v2/services/<SERVICE_ID>' \
333
+ -H 'Authorization: <AUTH>'
334
+
335
+ curl -X PATCH 'https://www.wixapis.com/bookings/v2/services/<SERVICE_ID>' \
336
+ -H 'Authorization: <AUTH>' \
337
+ -H 'Content-Type: application/json' \
338
+ -d '{
339
+ "service": {
340
+ "revision": "<REVISION_FROM_GET>",
341
+ "payment": {
342
+ "rateType": "FIXED",
343
+ "options": { "online": false, "inPerson": true },
344
+ "fixed": {
345
+ "price": { "value": "200", "currency": "<SITE_CURRENCY>" }
346
+ }
347
+ }
348
+ }
349
+ }'
350
+ ```
351
+
352
+ ### 3. Set the availability of the service
353
+
354
+ Once the service and staff member are available, you can define when the service is available:
355
+
356
+ **3a. Determine the schedule to use** based on the service type:
357
+
358
+ - **APPOINTMENT**: The staff member working hours determine the service availability. If the staff member needs different hours from the business defaults, call `assignWorkingHoursSchedule` (`POST https://www.wixapis.com/bookings/v1/staff-members/<STAFF_MEMBER_ID>/assign-working-hours-schedule`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/assign-working-hours-schedule)). Use the `resource.eventsSchedule.id` as the `scheduleId`.
359
+ - **CLASS or COURSE**: Use the `service.schedule.id` from the service created/updated in Step 2.
360
+
361
+ **3b. Create events** using `bulkCreateEvents` (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)) or update existing ones with `bulkUpdateEvents` (`POST https://www.wixapis.com/calendar/v3/bulk/events/update`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-update-event)).
362
+
363
+ **Event requirements**:
364
+
365
+ - `event.resources` array **must include at least one resource** (a staff member/room/etc.) using the `resourceId`. CLASS and COURSE events will fail with a 400 error if no resources are provided.
366
+ - `event.scheduleId` — use the staff member's events schedule ID for APPOINTMENT availability, or `service.schedule.id` for CLASS/COURSE.
367
+ - `event.type` — set to `WORKING_HOURS` for staff availability, `CLASS` for class sessions, or `COURSE` for course sessions.
368
+
369
+ ### Troubleshooting Common Issues
370
+
371
+ **APPOINTMENT Service Creation Fails (staffMemberIds required):**
372
+
373
+ - **Error**: `"service of type appointment requires at least one staff member id"`
374
+ - **Cause**: APPOINTMENT services cannot be created without at least one staff member assigned
375
+ - **Solution**: Query staff members first (Step 1) to get a valid `resourceId`, then include it in `staffMemberIds`
376
+
377
+ **Service Creation Fails (payment.options required):**
378
+
379
+ - **Error**: `INVALID_PAYMENT_OPTIONS - "It is mandatory to specify either payment.options.online or payment.options.inPerson as true"`
380
+ - **Cause**: All services (including free) require at least one payment option to be `true`
381
+ - **Solution**: Add `"options": { "online": true, "inPerson": false }` (or `inPerson: true` for free services) to the `payment` object
382
+
383
+ **Free Service Fails with online=true:**
384
+
385
+ - **Error**: `INVALID_PAYMENT_OPTIONS - "Specifying payment.paymentOptions.online as true is applicable only to payments of types FIXED or VARIED"`
386
+ - **Cause**: `payment.options.online: true` is only valid for paid services (FIXED or VARIED)
387
+ - **Solution**: For free services (NO_FEE), use `"options": { "online": false, "inPerson": true }`
388
+
389
+ **Changing a free service price fails:**
390
+
391
+ - **Error**: `"Payment of type FREE cannot be used with payment.rate"`
392
+ - **Cause**: The service is still `NO_FEE` while the update tries to set `fixed.price`
393
+ - **Solution**: Change `payment.rateType` to `"FIXED"` and include `payment.fixed.price` in the same update request
394
+
395
+ **Services Not Appearing in UI Filters:**
396
+
397
+ - **Problem**: Services created without category assignment are invisible in category-based filters
398
+ - **Root Cause**: Many UI implementations filter by `category.id` existence or specific category values
399
+ - **Solution**: Query all services, identify those missing categories, and update them using bulk update operations
400
+ - **Prevention**: Always assign categories during service creation (Step 0)
401
+
402
+ **Staff Assignment Not Working for CLASS/COURSE Services:**
403
+
404
+ - **Problem**: Setting `staffMemberIds` in CLASS or COURSE services appears to be ignored
405
+ - **Solution**: This is expected behavior; use service schedules instead of staff assignments
406
+ - **Alternative**: Manage staff-to-class relationships through calendar events or custom data structures
407
+
408
+ **App Not Installed Errors:**
409
+
410
+ - **Problem**: 428 "App not installed" errors when creating services
411
+ - **Solution**: Install Wix Bookings app using Apps Installer API before creating services
412
+ - **Verification**: Query existing services to confirm app installation
413
+
414
+ **Resource ID vs Staff ID Confusion:**
415
+
416
+ - **Problem**: Using wrong ID type for `staffMemberIds` array
417
+ - **Solution**: Always use `staffMember.resourceId`, not `staffMember.id`
418
+ - **Verification**: Query staff with `RESOURCE_DETAILS` fieldMask to get correct IDs
419
+
420
+ **Service Schedule vs Staff Schedule Confusion:**
421
+
422
+ - **Problem**: Mixing up schedule IDs between service and staff schedules
423
+ - **Solution**:
424
+ - APPOINTMENT: Use staff schedule ID (`staffMember.resource.eventsSchedule.id`)
425
+ - CLASS/COURSE: Use service schedule ID (`service.schedule.id`)
426
+
427
+ **Update Service Fails with revision error:**
428
+
429
+ - **Error**: `revision must not be empty` or `service.revision is required`
430
+ - **Cause**: `revision` placed at top level of request body instead of inside `service` object
431
+ - **Solution**: Structure as `{ "service": { "revision": "...", ...fields } }` - get revision value from GET response first
432
+
433
+ ### IMPORTANT NOTES
434
+
435
+ - I MUST read the full article about the REST method I wish to use
436
+ - `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.
437
+ - Event Creation (BulkCreateEvents): When specifying recurrenceRule.days, I MUST use full day names (e.g., "TUESDAY", "FRIDAY")
438
+ - The recurrenceRule.days field within an event object can only accept a single day of the week (e.g., ["TUESDAY"]).
439
+ - 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.
440
+ - 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.
441
+ - 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
442
+ - 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
443
+
444
+ ## Booking REST API Documentation Reference
445
+
446
+ - [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)
447
+ - [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
448
+ - [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)
449
+ - [Update Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service)
450
+ - [Create Staff Member](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member)
451
+ - [Get Staff Member](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/get-staff-member)
452
+ - [Query Staff Members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members)
453
+ - [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)
454
+ - [Bulk Update Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-update-services)
455
+ - [Bulk Update Services By Filter](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-update-services-by-filter)
456
+ - [Assign Working Hours Schedule](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/assign-working-hours-schedule)
457
+ - [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)
458
+ - [Bulk Update Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-update-event)
459
+ - [Media Manager: Search Files](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/search-files)
460
+ - [Media Manager: Bulk Import File](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/bulk-import-file)
461
+ - [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
462
+ - [Apps Installer API](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)