About the Tips Settings API

The Tips Settings API allows app developers to manage how Wix Tips calculates tips and distributes them among staff.

With the Tips Settings API, your app can:

  • Update a site's default tip settings.
  • Manage non-default tips settings.

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.
  • You can't delete the default tip settings that Wix Tips automatically creates upon installation, but you can update them.
  • For each tipSettings object, you can configure up to 3 preset tip choices that Wix Tips displays to customers during the eCommerce checkout. Additionally, you can allow customers to manually enter a custom tip amount.

Sample Use Cases

Terminology

  • Tip: Details the tip amount, how it’s distributed among staff, and the associated order’s line item subtotal. Refer to the Tips API for more information.
  • Tip distribution: How the total tip is allocated among eligible staff. You can split tips equally among staff or define proportional shares. The business receives the undistributed tip amount.
  • Tip settings: Allow you to customize how Wix Tips previews and calculates tips based on various factors; including business location, external payment terminal used for the eCommerce checkout, product or service being purchased or which site collaborator manages the payment process via the site's dashboard.
  • Staff: Team members receiving a portion of the tip. Currently, only Bookings staff members and site collaborators are eligible to receive tip distributions. Refer to the Tippable Staff API for more information.
Did this help?

Tips Settings API: Sample Use Cases and Flows

This article shares basic flows your app could support. You're certainly not limited to these use cases, but they can be a helpful jumping-off point for your planning.

Create location-specific tip settings

Your app could create tip settings tailored to a specific location.

To create location-specific tip settings:

  1. Use List Locations to retrieve a list of all locations associated with the site.
  2. Display the list of locations to the business owners and allow them select the location for which they want to configure specific tip settings.
  3. Check if tip settings already exist for the chosen location using Query Tip Settings. Filter the query by the relevant location ID.
  4. If location-specific tip settings exist, display them to the business owners for review and editing. If no settings exist, display default values and allow customization.
  5. Save the tip settings using either Create Tip Settings, (for new settings) or Update Tip Settings (for existing settings).

Create payment-terminal-specific tip settings

Your app could create tip settings tailored to a specific device used for processing payments.

To create payment-terminal-specific tip settings:

  1. Check if tip settings already exist for the relevant payment terminal using Query Tip Settings. Provide paymentTerminalId as filter.
  2. If payment-terminal-specific tip settings exist, display them to the business owners for review and editing. If no settings exist, display default values and allow customization.
  3. Save the tip settings using either Create Tip Settings, (for new settings) or Update Tip Settings (for existing settings).
Did this help?

Tip Settings: Supported Filters and Sorting

Query endpoints allow you to filter and sort results based on service properties. This article covers field support for filtering and sorting.

The following table shows field support for filters and sorting for the tipSettings object in Query Tip Settings:

FieldSupported FiltersSortable
id$eq, $ne, $in, $existsSortable
tipType$eq, $ne, $in, $existsSortable
locationId$eq, $ne, $in, $existsSortable
paymentTerminalId$eq, $ne, $in, $existsSortable
default$eq, $ne, $in, $existsSortable
allowCustomerTip$eq, $ne, $in, $existsSortable
allowBusinessTipAtPayment$eq, $ne, $in, $existsSortable
allowCustomAmount$eq, $ne, $in, $existsSortable

Related content:

Did this help?

Tip Settings Object


Tip settings define how tips are calculated and distributed among staff. When Wix Tips is installed, default settings are automatically created. You can't delete these default settings but you can update them. Creating additional settings allows business owners to customize tip screens for different payment terminals or set specific presets for various products or services.

Properties
idstringRead-onlyformat GUID

ID of the tip settings.


tipTypestring

Tip type.

Supported values:

  • UNKNOWN_TIP_TYPE: There is no information about the tip type.
  • PERCENTAGE: The tip is calculated as a percentage of the subtotal for all related line items.
  • AMOUNT: The tip is a fixed amount.

presetsArray <Preset>minItems 1maxItems 3

Information about the tip choices that Wix Tips displays to customers during the eCommerce checkout.

Min: 1 preset Max: 3 presets


allowCustomerTipboolean

Whether customer are allowed to tip during the eCommerce checkout.

Default: true


allowBusinessTipAtPaymentboolean

Whether the business owners are given the option to add a tip during the payment collection flow in their dashboard.

Default: true


allowCustomAmountboolean

Whether customers can enter a custom tip amount. If set to false, customers can only select a tip value from the available presets and can't enter a custom amount.

Default: true


allowEditDistributionboolean

Whether business owners are allowed to edit tip distributions. If set to false, owners can't edit distributions after they were created.

Default: true


staffDistributionMethodstring

How the tip is distributed among staff.

Supported values: UNKNOWN_SPLIT_METHOD: There is no information about the staff distribution method. EQUAL: The tip is distributed equally among all staff. PROPORTIONAL: The tip is distributed proportionally among staff.


revisionintegerRead-onlyformat int64

Revision number, which increments by 1 each time tipSettings object is updated. To prevent conflicting changes, the current revision must be passed when updating tipSettings. Ignored when creating a tipSettings object.


createdDatestringRead-onlyformat date-time

Date and time the tip settings were created in YYYY-MM-DDThh:mm:ss.sssZ format.


updatedDatestringRead-onlyformat date-time

Date and time the tip settings were last updated YYYY-MM-DDThh:mm:ss.sssZ format.


defaultbooleanRead-only

Whether these are the default tip settings. Wix Tips automatically creates the default settings during the app's installation. You can't delete these default settings but you can update them. Wix Tips uses the default settings to calculate tips, unless you specify other settings.


appIdstringformat GUID

ID of the app that has created the settings. See the list of app IDs for Wix business solutions.


extendedFieldsExtendedFields

Custom field data for the tipSettings object. Extended fields must be configured in the app dashboard before they can be accessed with API calls.


ONE OF:

locationIdstringformat GUID

ID of the location for which the tip settings apply.


paymentTerminalIdstringmaxLength 30

ID of the payment terminal for which the tip settings apply. Wix Tips doesn't validate the ID you provide.

Max: 30 characters


userIdstringformat GUID

ID of the Wix user for whom the tip settings apply. For example, the site owner or a site collaborator.

Did this help?

POST

Query Tip Settings


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 tip of up to 100 tip settings, given the provided paging, filtering, and sorting.

Query Tip Settings runs with these defaults, which you can override:

  • cursorPaging.limit is 50.
  • Sorted by id in ascending order.

For field support for filters and sorting, see Tip Settings: Supported Filters and Sorting.

Use UTC time when setting a filter for dates.

To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.

Permissions
Manage Bookings - all permissions
Manage Bookings
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/tip-settings/v1/tip-settings/query

Body Params
queryQueryRequired

WQL expression

Response Object
tipSettingsArray <TipSettings>

Retrieved tipSettings objects.


pagingMetadataPagingMetadata

Metadate for the paged set of retrieved tipSettings objects.

Query tip settings
Request
cURL
curl -X POST \ 'https://www.wixapis.com/tip-settings/v1/tip-settings/query' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \
Response
JSON
{ "tipSettings": [ { "id": "1338729c-7255-48f1-a66e-f6a8e4b6f9f3", "tipType": "PERCENTAGE", "presets": [ { "value": 5, "default": true }, { "value": 10, "default": null }, { "value": 15, "default": null } ], "allowCustomerTip": false, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL", "revision": "1", "createdDate": "2024-09-23T08:16:35.039Z", "updatedDate": "2024-09-23T08:16:35.039Z", "default": false, "appId": null, "extendedFields": null } ], "pagingMetadata": { "count": 1, "hasNext": false } }
Did this help?

POST

Create Tip Settings


Developer Preview

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

Creates a tipSettings object.

You can't create a tipSettings object with {"default": true}.

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
POST
https://www.wixapis.com/tip-settings/v1/tip-settings

Body Params
tipSettingsTipSettingsRequired

Tip settings to create.

Response Object
tipSettingsTipSettings

Created tip settings.

Create tip settings
Request
cURL
curl -X POST \ 'https://www.wixapis.com/tip-settings/v1/tip-settings' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "tipSettings": { "presets": [ { "value": 5, "default": true }, { "value": 10 }, { "value": 15 } ], "tipType": "PERCENTAGE", "allowCustomerTip": false, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL", "default": false } }'
Response
JSON
{ "tipSettings": { "id": "1338729c-7255-48f1-a66e-f6a8e4b6f9f3", "tipType": "PERCENTAGE", "presets": [ { "value": 5, "default": true }, { "value": 10, "default": null }, { "value": 15, "default": null } ], "allowCustomerTip": false, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL", "revision": "1", "createdDate": "2024-09-23T08:16:35.039Z", "updatedDate": "2024-09-23T08:16:35.039Z", "default": false, "appId": null, "extendedFields": null } }
Errors
428Failed Precondition

There are 2 errors with this status code:

See the entire list and learn more about Wix errors.

Did this help?

PATCH

Update Tip Settings


Developer Preview

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

Updates a tipSettings object.

You can't update the default field.

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
PATCH
https://www.wixapis.com/tip-settings/v1/tip-settings

Body Params
tipSettingsTipSettingsRequired

Tip settings to update.

Response Object
tipSettingsTipSettings

Updated tip settings.

Update tip settings
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/tip-settings/v1/tip-settings' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "tipSettings": { "id": "1338729c-7255-48f1-a66e-f6a8e4b6f9f3", "presets": [ { "value": 5, "default": true }, { "value": 10 }, { "value": 15 } ], "tipType": "PERCENTAGE", "allowCustomerTip": true, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL", "default": false, "revision": "1" }, "field_mask": { "paths": [ "allowCustomerTip" ] } }'
Response
JSON
{ "tipSettings": { "id": "1338729c-7255-48f1-a66e-f6a8e4b6f9f3", "tipType": "PERCENTAGE", "presets": [ { "value": 5, "default": true }, { "value": 10, "default": null }, { "value": 15, "default": null } ], "allowCustomerTip": true, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL", "revision": "2", "createdDate": "2024-09-23T08:16:35.039Z", "updatedDate": "2024-09-23T08:16:35.039Z", "default": false, "appId": null, "extendedFields": null } }
Errors
428Failed Precondition

There are 3 errors with this status code:

See the entire list and learn more about Wix errors.

Did this help?

POST

Create Default Tip Settings


Developer Preview

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

Creates a default tipSettings object.

The call fails if there is already an existing default tipSettings object.

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
POST
https://www.wixapis.com/tip-settings/v1/tip-settings/create-default

Body Params
tipSettingsTipSettingsRequired

Dafault tip settings to create.

Response Object
tipSettingsTipSettings

Created default tip settings.

Create default tip settings
Request
cURL
curl -X POST \ 'https://www.wixapis.com/tip-settings/v1/tip-settings/create-default' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "tipSettings": { "presets": [ { "value": 5, "default": true }, { "value": 10 }, { "value": 15 } ], "tipType": "PERCENTAGE", "allowCustomerTip": false, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL" } }'
Response
JSON
{ "tipSettings": { "id": "1338729c-7255-48f1-a66e-f6a8e4b6f9f3", "tipType": "PERCENTAGE", "presets": [ { "value": 5, "default": true }, { "value": 10, "default": null }, { "value": 15, "default": null } ], "allowCustomerTip": false, "allowBusinessTipAtPayment": true, "allowCustomAmount": true, "staffDistributionMethod": "PROPORTIONAL", "revision": "1", "createdDate": "2024-09-23T08:16:35.039Z", "updatedDate": "2024-09-23T08:16:35.039Z", "default": true, "appId": null, "extendedFields": null } }
Errors
428Failed Precondition

There are 3 errors with this status code:

See the entire list and learn more about Wix errors.

Did this help?

DELETE

Delete Tip Settings


Developer Preview

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

Deletes a tipSettings object.

You can't delete the default tipSettings object.

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
DELETE
https://www.wixapis.com/tip-settings/v1/tip-settings/{tipSettingsId}

Path Params
tipSettingsIdstringRequired

ID of the tipSettings object to delete.

Response Object
Returns an empty object.
Delete tip settings
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/tip-settings/v1/tip-settings/1338729c-7255-48f1-a66e-f6a8e4b6f9f3' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Errors
428Failed Precondition

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?