Go Headless

Build Apps

Client

API Preview

test

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

# 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](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/wix-e-commerce-platform-handbook/overview/what-is-the-wix-e-commerce-platform). Currently, the API supports only
staff members from [Wix Bookings](fallback::https://support.wix.com/en/article/wix-bookings-about-wix-bookings)
and [site collaborators](fallback::https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site).

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:
+ [Tips API](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/tips/tips/introduction)
+ [Tip Settings API](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/tips/tip-settings/introduction)
+ [Bookings Staff Members API](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction)

## Before you begin

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

+ Ensure that the site owner has installed [Wix Tips](fallback::https://www.wix.com/app-market/wix-tips)
  on their site. Wix Tips is automatically installed with every
  [Wix Bookings](fallback::https://www.wix.com/app-market/bookings) installation.
+ Currently, only [Bookings staff members](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction)
  and [site collaborators](fallback::https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site)
  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

+ [Implement a staff performance dashboard](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6134b51c-9564-41d9-9e37-f4442923c66bslug::sample-flows#implement-a-staff-performance-dashboard*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/tips/tip-staff/sample-flows#implement-a-staff-performance-dashboard).

## 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](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction)
  and [site collaborators](fallback::https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site)
  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](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction).
  + **Site collaborator**: A Wix user authorized to edit or manage the business
    website.

For a comprehensive glossary of Wix Bookings terms, see
[Terminology](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/terminology).

# 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6134b51c-9564-41d9-9e37-f4442923c66bslug::list-tippable-staff*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/tips/tip-staff/list-tippable-staff)
   to retrieve all tippable staff and save their IDs.
1. Calculate the total tip amount for each staff member in your desired time
   range. Use [Sum Tip Distributions](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/tips/tips/sum-tip-distribution-amounts)
   and filter using the relevant staff ID and your desired range for `createdDate`.
   Alternatively, you can use
   [Query Tip Distributions](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/tips/tips/query-tip-distributions)
   with the same filter and calculate the total tip per staff on your servers.
1. Display each staff member's information and their associated tip total to
   the business owners.

value

StringValue

ID of the [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction)
in the site's [CRM by Ascend](https://www.wix.com/ascend/crm) system.

contactId

IdentificationData

IdentityType

ID of a site visitor who hasn't logged in to the site.

anonymousVisitorId

appId

ID of a site visitor who has logged in to the site.

memberId

ID of a Wix user. For example, the site owner or a
[site collaborator](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site).

wixUserId

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

filterByIds

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

filterByName

Whether to include staff who are only Wix users and not
[Bookings staff members](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction)
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`.

includeWixUsers

ListTippableStaffRequest

staff

ListTippableStaffResponse

Information about a team member who's eligible to receive a portion of the tip.
Currently, only [Bookings staff members](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction)
and [site collaborators](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site)
are eligible for tip distributions.

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

Identification data of the staff. Available only if the staff is a
[site collaborator](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site).

Staff name. Matches the name of the
[Bookings staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/staff-member-object)
if available.

name

Staff member ID. Available only if the staff is connected to a
[Bookings staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/staff-member-object).

staffMemberId

Staff

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