> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # SortStaffMembers # Package: staffMembers # Namespace: StaffSortingProvider # Method link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-sorting-service-plugin/sort-staff-members.md ## Introduction Sorts staff members using custom business logic for assigning resources to a booking. Wix calls this method in real time when multiple staff members are available and Wix needs to assign a staff member: - **During booking creation**: When a customer completes a booking and multiple staff members are available for the selected time slot. - **During booking modifications**: When an existing booking is modified (time change, service change) and staff reassignment is needed. - **During availability checks**: In some cases, when displaying available time slots to customers, to optimize the staff assignment preview. Your implementation must return the resources in your preferred assignment order. Wix assigns the first resource to the booking and uses subsequent resources as fallbacks if the primary choice becomes unavailable before creating the booking. --- ## REST API ### Schema ``` Method: sortStaffMembers Description: Sorts staff members using custom business logic for assigning resources to a booking. Wix calls this method in real time when multiple staff members are available and Wix needs to assign a staff member: - **During booking creation**: When a customer completes a booking and multiple staff members are available for the selected time slot. - **During booking modifications**: When an existing booking is modified (time change, service change) and staff reassignment is needed. - **During availability checks**: In some cases, when displaying available time slots to customers, to optimize the staff assignment preview. Your implementation must return the resources in your preferred assignment order. Wix assigns the first resource to the booking and uses subsequent resources as fallbacks if the primary choice becomes unavailable before creating the booking. ### Response validation Your response must contain the exact same resource GUIDs provided in the request, in your preferred order. Don't add, remove, or duplicate resources. If the response is invalid, Wix falls back to random staff assignment. ### Performance requirements Your implementation must respond in under 5 seconds or Wix times out and falls back to random staff assignment. For optimal user experience, we recommend responding in under 500 milliseconds. You can use caching strategies and avoid synchronous external API calls during sorting. URL: null Method: POST Method parameters: param name: availableResourceIds | type: array | description: Array of resource GUIDs for staff members who are available for this time slot. The field uses "resource" terminology for future extensibility, but currently all resources are staff members. Your algorithm must return these same GUIDs in your preferred assignment order. Don't add, remove, or duplicate resources. param name: extendedFields | type: ExtendedFields - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). param name: policyId | type: policyId | description: GUID of the service's [booking policy](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md). param name: slot | type: Slot - name: startDate | type: string | description: Local start time of the booking slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. Wix always provides this value when calling your service plugin. - name: endDate | type: string | description: Local end time of the booking slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T14:00:00`. Wix always provides this value when calling your service plugin. - name: serviceId | type: string | description: GUID of the [service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md) being booked. Wix always provides this value when calling your service plugin. - name: locationId | type: string | description: GUID of the [location](https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md) where the business provides the service. Consider this for proximity-based sorting or location-specific staff assignments. Wix always provides this value when calling your service plugin. - name: timeZone | type: string | description: Time zone for the slot. For example, `America/New_York` or `UTC`. Wix always provides this value when calling your service plugin. Return type: SortStaffMembersResponse - name: staff | type: array | description: Array of staff members sorted according to your custom sorting algorithm, in order of assignment priority. Wix assigns the first staff member to the booking. Subsequent staff members serve as fallbacks if the primary choice becomes unavailable during the booking process. - name: resourceId | type: string | description: Resource GUID. This must match one of the GUIDs specified in the SortStaffMembersRequest.available_resource_ids array. Currently, this service plugin only supports staff members as resources. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: SORTING_ERROR | Description: none ``` ### Examples ### Sort staff members by custom algorithm The data payload is sent as an encoded JWT. For the purposes of this example, we show the request and response objects decoded. In production, you must verify the JWT signature to ensure the request is from Wix. ```curl curl -X POST \ 'https://provider.example.com/v1/sort-staff-members' \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "data": { "request": { "policyId": "9bf5cd2d-32fa-4ee7-952c-5e4b6de14714", "slot": { "startDate": "2026-01-30T13:30:00", "endDate": "2026-01-30T14:00:00", "serviceId": "7474452d-ab93-4d42-af61-b15e9f93981d", "locationId": "bb2b1658-9855-4598-b1e0-48e8cdb7f98a", "timeZone": "America/New_York" }, "availableResourceIds": [ "c7808c1d-e6a5-49e5-bcbe-b3fcf2f72d28", "044667f4-c13f-46c2-8506-de9e42293896", "3467d501-9004-498d-9b5c-d50f6d4ede66" ] }, "metadata": { "requestId": "1674480822.92546993606315181", "identity": { "identityType": "MEMBER", "memberId": "a8119733-f872-4b0a-963b-09a95208474e" }, "instanceId": "bb2b1658-9855-4598-b1e0-48e8cdb7f98a" } }, "aud": "13d21c63-b5ec-5912-8397-c3a5ddb27a97", "iss": "wix.com", "iat": 1674480823, "exp": 1678080823 }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.staffMembers.StaffSortingProvider.sortStaffMembers(request, metadata) Description: Sorts staff members using custom business logic for assigning resources to a booking. Wix calls this method in real time when multiple staff members are available and Wix needs to assign a staff member: - **During booking creation**: When a customer completes a booking and multiple staff members are available for the selected time slot. - **During booking modifications**: When an existing booking is modified (time change, service change) and staff reassignment is needed. - **During availability checks**: In some cases, when displaying available time slots to customers, to optimize the staff assignment preview. Your implementation must return the resources in your preferred assignment order. Wix assigns the first resource to the booking and uses subsequent resources as fallbacks if the primary choice becomes unavailable before creating the booking. ### Response validation Your response must contain the exact same resource GUIDs provided in the request, in your preferred order. Don't add, remove, or duplicate resources. If the response is invalid, Wix falls back to random staff assignment. ### Performance requirements Your implementation must respond in under 5 seconds or Wix times out and falls back to random staff assignment. For optimal user experience, we recommend responding in under 500 milliseconds. You can use caching strategies and avoid synchronous external API calls during sorting. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: SortStaffMembersRequest - name: policyId | type: string | description: GUID of the service's [booking policy](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md). - name: slot | type: Slot | description: Booking slot context including time, service, and location details. You can use this information to make informed sorting decisions based on factors like staff proximity to location, expertise with the specific service, or availability patterns. - name: startDate | type: string | description: Local start time of the booking slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. Wix always provides this value when calling your service plugin. - name: endDate | type: string | description: Local end time of the booking slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T14:00:00`. Wix always provides this value when calling your service plugin. - name: serviceId | type: string | description: GUID of the [service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md) being booked. Wix always provides this value when calling your service plugin. - name: locationId | type: string | description: GUID of the [location](https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md) where the business provides the service. Consider this for proximity-based sorting or location-specific staff assignments. Wix always provides this value when calling your service plugin. - name: timeZone | type: string | description: Time zone for the slot. For example, `America/New_York` or `UTC`. Wix always provides this value when calling your service plugin. - name: availableResourceIds | type: array | description: Array of resource GUIDs for staff members who are available for this time slot. The field uses "resource" terminology for future extensibility, but currently all resources are staff members. Your algorithm must return these same GUIDs in your preferred assignment order. Don't add, remove, or duplicate resources. - name: extendedFields | type: ExtendedFields | description: Custom field data for the policy. [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). Return type: PROMISE - name: staff | type: array | description: Array of staff members sorted according to your custom sorting algorithm, in order of assignment priority. Wix assigns the first staff member to the booking. Subsequent staff members serve as fallbacks if the primary choice becomes unavailable during the booking process. - name: resourceId | type: string | description: Resource GUID. This must match one of the GUIDs specified in the SortStaffMembersRequest.available_resource_ids array. Currently, this service plugin only supports staff members as resources. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: SORTING_ERROR | Description: none ``` ### Examples ### sortStaffMembers ```javascript import { staffSorting } from '@wix/bookings/service-plugins'; async function sortStaffMembers(request,metadata) { const response = await staffSorting.sortStaffMembers(request,metadata); }; ``` ### sortStaffMembers (with elevated permissions) ```javascript import { staffSorting } from '@wix/bookings/service-plugins'; import { auth } from '@wix/essentials'; async function mySortStaffMembersMethod(request,metadata) { const elevatedSortStaffMembers = auth.elevate(staffSorting.sortStaffMembers); const response = await elevatedSortStaffMembers(request,metadata); } ``` ### sortStaffMembers (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { staffSorting } from '@wix/bookings/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { staffSorting }, // Include the auth strategy and host as relevant }); async function sortStaffMembers(request,metadata) { const response = await myWixClient.staffSorting.sortStaffMembers(request,metadata); }; ``` ---