About the Tippable Staff API

The Tippable Staff API allows app developers to retrieve information about which business staff members are eligible to receive tips via the eCommerce platform. Currently, the API supports only staff members from Wix Bookings and site collaborators.

With the Tippable Staff API, your app can:

  • Use custom filtering to identify staff members eligible to receive tips via the eCommerce platform.

See also:

Before you begin

It's important to note the following points before starting to code:

  • Ensure that the site owner has installed Wix Tips on their site. Wix Tips is automatically installed with every Wix Bookings installation.
  • Currently, only Bookings staff members and site collaborators can receive tip distributions.
  • Not all staff members have a Wix user identity, and not all site collaborators qualify as staff members.

Sample use cases

Terminology

  • Tip: Details the tip amount, how it’s distributed among staff, and the associated order’s line item subtotal.
  • Tip distribution: How the total tip is divided among staff. The business receives the undistributed tip amount.
  • Staff: Team members eligible to receive a portion of the tip. Currently, only Bookings staff members and site collaborators are eligible for tip distributions.
    • Bookings staff member: A business resource used to manage and provide services through Wix Bookings. Manage staff members, see via the Bookings Resources API.
    • Site collaborator: A Wix user authorized to edit or manage the business website.

For a comprehensive glossary of Wix Bookings terms, see Terminology.

Did this help?

Tippable Staff API: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Implement a staff performance dashboard

Your app could help business owners evaluate staff performance based on various metrics, including tips received.

To implement a staff performance dashboard:

  1. Use List Tippable Staff to retrieve all tippable staff and save their IDs.
  2. Calculate the total tip amount for each staff member in your desired time range. Use Sum Tip Distributions and filter using the relevant staff ID and your desired range for createdDate. Alternatively, you can use Query Tip Distributions with the same filter and calculate the total tip per staff on your servers.
  3. Display each staff member's information and their associated tip total to the business owners.
Did this help?

Staff Object


Information about a team member who's eligible to receive a portion of the tip. Currently, only Bookings staff members and site collaborators are eligible for tip distributions.

Properties
idstringRead-onlyformat GUID

Staff ID. Matches staffMemberId if available, or identificationData.wixUserId if not.


namestringmaxLength 500

Staff name. Matches the name of the Bookings staff member if available.


staffMemberIdstringformat GUID

Staff member ID. Available only if the staff is connected to a Bookings staff member.


identificationDataIdentificationData

Identification data of the staff. Available only if the staff is a site collaborator.

Did this help?

GET

List Tippable Staff


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of up to 100 staff who are eligible to receive tips, given the provided filtering.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Bookings - all permissions
Manage Bookings
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/tips-staff/v1/eligible-staff

Query Params
includeWixUsersboolean

Whether to include staff who are only Wix users and not Bookings staff members in the response. Setting {"includeWixUsers": true} returns all tippable staff, including Bookings staff, site collaborators, or those who are both. By default, or if you provide {"includeWixUsers": false}, only Bookings staff members or those who are both are returned.

Default: false.


filterByNamestring

Filters the returned staff by name. If you provide a name as filter, only staff whose names start with the given input are returned. The filter isn't case sensitive.

Max: 500 characters


filterByIdsArray <string>

Filters the returned staff by ID. If you provide a list of IDs as filter, only staff members with exact matching IDs are returned.

Max: 100 IDs

Response Object
staffArray <Staff>maxItems 100

Retrieved staff.

Request
cURL
curl -X POST \ 'https://www.wixapis.com/tips-staff-service/v1/eligible-staff' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \
Response
JSON
{ "staff": [ { "id": "79ee2a33-6937-39a4-ab46-6859171c5ad7", "name": "Malakah Mada", "staffMemberId": "79ee2a33-6937-39a4-ab46-6859171c5ad7", "identificationData": null }, { "id": "7ec295cd-120c-3bff-9f43-a7e10c387f02", "name": "Tiago Melo Correia", "staffMemberId": "7ec295cd-120c-3bff-9f43-a7e10c387f02", "identification_data": null }, { "id": "bdf56958-d4dd-306e-843c-e1196ed10cf5", "name": "Cornelia Brandybuck", "staffMemberId": "bdf56958-d4dd-306e-843c-e1196ed10cf5", "identificationData": null } ] }
Did this help?