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:
See also:
It's important to note the following points before starting to code:
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.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.
Your app could create tip settings tailored to a specific location.
To create location-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:
paymentTerminalId
as filter.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:
Field | Supported Filters | Sortable |
---|---|---|
id | $eq , $ne , $in , $exists | Sortable |
tipType | $eq , $ne , $in , $exists | Sortable |
locationId | $eq , $ne , $in , $exists | Sortable |
paymentTerminalId | $eq , $ne , $in , $exists | Sortable |
default | $eq , $ne , $in , $exists | Sortable |
allowCustomerTip | $eq , $ne , $in , $exists | Sortable |
allowBusinessTipAtPayment | $eq , $ne , $in , $exists | Sortable |
allowCustomAmount | $eq , $ne , $in , $exists | Sortable |
Related content:
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.
ID of the tip settings.
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.Information about the tip choices that Wix Tips displays to customers during the eCommerce checkout.
Min: 1
preset
Max: 3
presets
Whether customer are allowed to tip during the eCommerce checkout.
Default: true
Whether the business owners are given the option to add a tip during the payment collection flow in their dashboard.
Default: true
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
Whether business owners are allowed to edit tip distributions. If set to
false
, owners can't edit distributions after they were created.
Default: true
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.
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.
Date and time the tip settings were created in
YYYY-MM-DDThh:mm:ss.sssZ
format.
Date and time the tip settings were last updated
YYYY-MM-DDThh:mm:ss.sssZ
format.
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.
ID of the app that has created the settings. See the list of app IDs for Wix business solutions.
Custom field data for the tipSettings
object. Extended fields must be
configured in the app dashboard before they can be accessed with API calls.
ID of the location for which the tip settings apply.
ID of the payment terminal for which the tip settings apply. Wix Tips doesn't validate the ID you provide.
Max: 30 characters
ID of the Wix user for whom the tip settings apply. For example, the site owner or a site collaborator.
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
.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.
WQL expression
Retrieved tipSettings
objects.
Metadate for the paged set of retrieved tipSettings
objects.
curl -X POST \
'https://www.wixapis.com/tip-settings/v1/tip-settings/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/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
}
}
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}
.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tip settings to create.
Created tip settings.
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
}
}'
{
"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
}
}
There are 2 errors with this status code:
See the entire list and learn more about Wix errors.
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tip settings to update.
Updated tip settings.
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"
]
}
}'
{
"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
}
}
There are 3 errors with this status code:
See the entire list and learn more about Wix errors.
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Dafault tip settings to create.
Created default tip settings.
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"
}
}'
{
"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
}
}
There are 3 errors with this status code:
See the entire list and learn more about Wix errors.
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the tipSettings
object to delete.
curl -X DELETE \
'https://www.wixapis.com/tip-settings/v1/tip-settings/1338729c-7255-48f1-a66e-f6a8e4b6f9f3' \
-H 'Authorization: <AUTH>'
{}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.