> 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 # CreateTipSettings # Package: tips # Namespace: TipSettingsService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/other-services/tips/tip-settings/create-tip-settings.md ## Permission Scopes: Manage Bookings: SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS ## Introduction Creates a `tipSettings` object. You can't create a `tipSettings` object with `{"default": true}`. --- ## REST API ### Schema ``` Method: createTipSettings Description: Creates a `tipSettings` object. You can't create a `tipSettings` object with `{"default": true}`. URL: https://www.wixapis.com/v1/tip-settings Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: tipSettings Method parameters: param name: tipSettings | type: TipSettings | description: 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 Wix users to customize tip screens for different payment terminals or set specific presets for various products or services. | required: true - ONE-OF: - required: true - 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: 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: 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). Return type: CreateTipSettingsResponse - name: tipSettings | type: TipSettings | description: Created tip settings. - 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). Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PRESET_PERCENTAGE_TOO_HIGH | Description: Preset percentage exceeds the maximum allowed value. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: CANNOT_HAVE_MORE_THAN_ONE_DEFAULT_PRESET | Description: Only 1 preset can be set as default. ``` ### Examples ### Create tip settings ```curl curl -X POST \ 'https://www.wixapis.com/tip-settings/v1/tip-settings' \ -H 'Authorization: ' \ -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 } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.tips.TipSettingsService.createTipSettings(tipSettings) Description: Creates a `tipSettings` object. You can't create a `tipSettings` object with `{"default": true}`. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: tipSettings Method parameters: param name: tipSettings | type: TipSettings | description: 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 Wix users to customize tip screens for different payment terminals or set specific presets for various products or services. | required: true - ONE-OF: - required: true - 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: 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: 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). Return type: PROMISE - 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). Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PRESET_PERCENTAGE_TOO_HIGH | Description: Preset percentage exceeds the maximum allowed value. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: CANNOT_HAVE_MORE_THAN_ONE_DEFAULT_PRESET | Description: Only 1 preset can be set as default. ``` ### Examples ### createTipSettings ```javascript import { tipSettings } from '@wix/ecom'; async function createTipSettings(tipSettings) { const response = await tipSettings.createTipSettings(tipSettings); }; ``` ### createTipSettings (with elevated permissions) ```javascript import { tipSettings } from '@wix/ecom'; import { auth } from '@wix/essentials'; async function myCreateTipSettingsMethod(tipSettings) { const elevatedCreateTipSettings = auth.elevate(tipSettings.createTipSettings); const response = await elevatedCreateTipSettings(tipSettings); } ``` ### createTipSettings (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 createTipSettings(tipSettings) { const response = await myWixClient.tipSettings.createTipSettings(tipSettings); }; ``` ---