> 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 # QueryTipSettings # Package: tips # Namespace: TipSettingsService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/other-services/tips/tip-settings/query-tip-settings.md ## Permission Scopes: Manage Bookings: SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS ## Introduction Retrieves a list 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. Use [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) when setting a filter for dates. To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/sorting-and-paging), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection). --- ## REST API ### Schema ``` Method: queryTipSettings Description: Retrieves a list 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. Use [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) when setting a filter for dates. To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/sorting-and-paging), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection). URL: https://www.wixapis.com/v1/tip-settings/query Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: query Method parameters: param name: query | type: QueryV2 | required: true - ONE-OF: - required: true - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: fields | type: array | description: Array of projected fields. A list of specific field names to return. If `fieldsets` are also specified, the union of `fieldsets` and `fields` is returned. - name: fieldsets | type: array | description: Array of named, predefined sets of projected fields. A array of predefined named sets of fields to be returned. Specifying multiple `fieldsets` will return the union of fields from all sets. If `fields` are also specified, the union of `fieldsets` and `fields` is returned. Return type: QueryTipSettingsResponse - name: tipSettings | type: array | description: Retrieved `tipSettings` objects. - ONE-OF: - name: locationId | type: string | description: GUID of the location ([SDK](https://dev.wix.com/docs/sdk/backend-modules/business-tools/locations/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-management/locations/location-object.md)) for which the tip settings apply. - name: paymentTerminalId | type: string | description: GUID of the payment terminal for which the tip settings apply. Wix Tips doesn't validate the GUID you provide. Max: 30 characters - name: userId | type: string | description: GUID of the Wix user for whom the tip settings apply. For example, the site owner or a [site collaborator](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site). - name: id | type: string | description: GUID of the tip settings. - name: tipType | type: TipType | description: Tip type. - enum: - UNKNOWN_TIP_TYPE: There is no information about the tip type. - PERCENTAGE: The tip is calculated as a percentage of the subtotal of all related line items. - AMOUNT: The tip is a fixed amount. - name: presets | type: array | description: Information about the tip choices that Wix Tips displays to customers during the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). Min: `1` preset Max: `3` presets - name: value | type: | description: Value of the preset tip choice that's displayed to customers in the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). For example, `5`, `10`, and `15` percent or `1`, `3`, and `5` USD. Min: `0` - name: default | type: boolean | description: Whether this tip choice value is the default preset that's highlighted automatically in the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). Default: `false` - name: allowCustomerTip | type: boolean | description: Whether customers are allowed to tip during the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). Default: `true` - name: allowBusinessTipAtPayment | type: boolean | description: Whether the Wix users are given the option to add a tip during the payment collection flow in their dashboard. Default: `true` - name: allowCustomAmount | type: boolean | description: 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` - name: allowEditDistribution | type: boolean | description: Whether Wix users are allowed to edit tip distributions. If set to `false`, Wix users can't edit distributions after they were created. Default: `true` - name: staffDistributionMethod | type: StaffDistributionMethod | description: 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. - enum: - UNKNOWN_SPLIT_METHOD: There is no information about the staff distribution method. - EQUAL: All staff receive an equal amount of the tip. - PROPORTIONAL: Staff receive a proportional amount of the tip. - name: revision | type: string | description: 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. - name: createdDate | type: string | description: Date and time the tip settings were created in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: updatedDate | type: string | description: Date and time the tip settings were last updated in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: default | type: boolean | description: 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. - name: appId | type: string | description: GUID of the app that has created the settings. See the list of app GUIDs for Wix business solutions ([SDK](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/apps-created-by-wix.md) | [REST](https://dev.wix.com/docs/rest/articles/getting-started/apps-created-by-wix.md)). - name: extendedFields | type: ExtendedFields | description: Custom field data for the `tipSettings` object. Extended fields 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). - name: pagingMetadata | type: PagingMetadataV2 | description: Metadata for the paged set of retrieved `tipSettings` objects. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. ``` ### Examples ### Query tip settings ```curl curl -X POST \ 'https://www.wixapis.com/tip-settings/v1/tip-settings/query' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.tips.TipSettingsService.queryTipSettings(query) Description: Retrieves a list 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. Use [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) when setting a filter for dates. To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/sorting-and-paging), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: query Method parameters: param name: query | type: TipSettingsQuery | required: true - ONE-OF: - required: true - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC Return type: PROMISE - name: tipSettings | type: array | description: Retrieved `tipSettings` objects. - ONE-OF: - name: locationId | type: string | description: GUID of the location ([SDK](https://dev.wix.com/docs/sdk/backend-modules/business-tools/locations/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-management/locations/location-object.md)) for which the tip settings apply. - name: paymentTerminalId | type: string | description: GUID of the payment terminal for which the tip settings apply. Wix Tips doesn't validate the GUID you provide. Max: 30 characters - name: userId | type: string | description: GUID of the Wix user for whom the tip settings apply. For example, the site owner or a [site collaborator](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site). - name: _id | type: string | description: GUID of the tip settings. - name: tipType | type: TipType | description: Tip type. - enum: - UNKNOWN_TIP_TYPE: There is no information about the tip type. - PERCENTAGE: The tip is calculated as a percentage of the subtotal of all related line items. - AMOUNT: The tip is a fixed amount. - name: presets | type: array | description: Information about the tip choices that Wix Tips displays to customers during the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). Min: `1` preset Max: `3` presets - name: value | type: number | description: Value of the preset tip choice that's displayed to customers in the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). For example, `5`, `10`, and `15` percent or `1`, `3`, and `5` USD. Min: `0` - name: default | type: boolean | description: Whether this tip choice value is the default preset that's highlighted automatically in the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). Default: `false` - name: allowCustomerTip | type: boolean | description: Whether customers are allowed to tip during the eCommerce checkout ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction.md) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/introduction.md)). Default: `true` - name: allowBusinessTipAtPayment | type: boolean | description: Whether the Wix users are given the option to add a tip during the payment collection flow in their dashboard. Default: `true` - name: allowCustomAmount | type: boolean | description: 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` - name: allowEditDistribution | type: boolean | description: Whether Wix users are allowed to edit tip distributions. If set to `false`, Wix users can't edit distributions after they were created. Default: `true` - name: staffDistributionMethod | type: StaffDistributionMethod | description: 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. - enum: - UNKNOWN_SPLIT_METHOD: There is no information about the staff distribution method. - EQUAL: All staff receive an equal amount of the tip. - PROPORTIONAL: Staff receive a proportional amount of the tip. - name: revision | type: string | description: 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. - name: _createdDate | type: Date | description: Date and time the tip settings were created in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: _updatedDate | type: Date | description: Date and time the tip settings were last updated in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: default | type: boolean | description: 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. - name: appId | type: string | description: GUID of the app that has created the settings. See the list of app GUIDs for Wix business solutions ([SDK](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/apps-created-by-wix.md) | [REST](https://dev.wix.com/docs/rest/articles/getting-started/apps-created-by-wix.md)). - name: extendedFields | type: ExtendedFields | description: Custom field data for the `tipSettings` object. Extended fields 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). - name: pagingMetadata | type: PagingMetadataV2 | description: Metadata for the paged set of retrieved `tipSettings` objects. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. ``` ### Examples ### queryTipSettings ```javascript import { tipSettings } from '@wix/ecom'; async function queryTipSettings(query) { const response = await tipSettings.queryTipSettings(query); }; ``` ### queryTipSettings (with elevated permissions) ```javascript import { tipSettings } from '@wix/ecom'; import { auth } from '@wix/essentials'; async function myQueryTipSettingsMethod(query) { const elevatedQueryTipSettings = auth.elevate(tipSettings.queryTipSettings); const response = await elevatedQueryTipSettings(query); } ``` ### queryTipSettings (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 { tipSettings } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { tipSettings }, // Include the auth strategy and host as relevant }); async function queryTipSettings(query) { const response = await myWixClient.tipSettings.queryTipSettings(query); }; ``` ---