> 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 # CreateCustomLoyaltyEarningRule # Package: loyaltyProgramManagement # Namespace: LoyaltyEarningRules # Method link: https://dev.wix.com/docs/api-reference/crm/loyalty-program/loyalty-program-management/earning-rules/create-custom-loyalty-earning-rule.md ## Permission Scopes: Manage Loyalty: SCOPE.DC-LOYALTY.MANAGE-LOYALTY ## Introduction Creates a custom automated earning rule. To learn more about the automated rules, see the Introduction. --- ## REST API ### Schema ``` Method: createCustomLoyaltyEarningRule Description: Creates a custom automated earning rule. To learn more about the automated rules, see the Introduction. URL: https://www.wixapis.com/v1/earning-rules/custom Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: type Method parameters: param name: earningRule | type: CustomLoyaltyEarningRule | description: Used in CreateCustomLoyaltyEarningRuleRequest - ONE-OF: - name: fixedAmount | type: FixedAmount | description: Fixed amount of points awarded for each qualifying activity. - name: configs | type: array | description: Fixed amount configurations for each tier. - name: points | type: integer | description: Number of points to award. - name: conversionRate | type: ConversionRate | description: Points awarded based on a conversion rate formula: `(amount spent) / (money_amount * points)`. - name: configs | type: array | description: Conversion rate configurations for each tier. Points are awarded proportionally to the amount spent. Formula: `(amount spent) / (money_amount * points)`. - name: moneyAmount | type: integer | description: The amount of money used as a reference for point calculation. Points are awarded proportionally to the amount spent. For example, if set to 10, 1 point is awarded for every 10 units of currency spent (assuming `points` is set to 1). Formula for points is: `(amount spent) / (money_amount * points)`. - name: points | type: integer | description: Points given for the specified `money_amount`. Works in conjunction with `money_amount` to define the earning rule. For example: If `money_amount` is 20 and `points` is 10: - Spending 10 units of currency earns 5 points - Spending 20 units of currency earns 10 points - Spending 30 units of currency earns 15 points - name: field | type: string | description: Specifies which field in the Wix automations trigger payload [REST](https://dev.wix.com/docs/rest/business-management/automations/introduction.md#how-do-automations-work)|[SDK](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/reporting-and-canceling-events.md) to use for calculating points in conversion rate rules. For example, if set to "priceSummary.totalAmount", the rule uses the total order amount to calculate loyalty points to be awarded. This field is only applicable for automated earning rules. - name: title | type: string | description: Name of the earning rule. param name: type | type: Type | required: true - enum: SOCIAL_MEDIA - Earning rule for social media. BIRTHDAY - Earning rule for birthdays. Return type: CreateCustomLoyaltyEarningRuleResponse - name: earningRule | type: LoyaltyEarningRule | description: Created earning rule. - ONE-OF: - name: fixedAmount | type: FixedAmount | description: Fixed amount of points awarded for each qualifying activity. - name: configs | type: array | description: Fixed amount configurations for each tier. - name: tierId | type: string | description: Tier GUID. If empty, the base tier is used. See the Tiers API for more information. - name: points | type: integer | description: Number of points to award. - name: conversionRate | type: ConversionRate | description: Points awarded based on a conversion rate formula: `(amount spent) / (money_amount * points)`. - name: configs | type: array | description: Conversion rate configurations for each tier. Points are awarded proportionally to the amount spent. Formula: `(amount spent) / (money_amount * points)`. - name: tierId | type: string | description: Tier GUID. If empty, the base tier is used. See the Tiers API for more information. - name: moneyAmount | type: integer | description: The amount of money used as a reference for point calculation. Points are awarded proportionally to the amount spent. For example, if set to 10, 1 point is awarded for every 10 units of currency spent (assuming `points` is set to 1). Formula for points is: `(amount spent) / (money_amount * points)`. - name: points | type: integer | description: Points given for the specified `money_amount`. Works in conjunction with `money_amount` to define the earning rule. For example: If `money_amount` is 20 and `points` is 10: - Spending 10 units of currency earns 5 points - Spending 20 units of currency earns 10 points - Spending 30 units of currency earns 15 points - name: field | type: string | description: Specifies which field in the Wix automations trigger payload [REST](https://dev.wix.com/docs/rest/business-management/automations/introduction.md#how-do-automations-work)|[SDK](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/reporting-and-canceling-events.md) to use for calculating points in conversion rate rules. For example, if set to "priceSummary.totalAmount", the rule uses the total order amount to calculate loyalty points to be awarded. This field is only applicable for automated earning rules. - name: id | type: string | description: Loyalty earning rule GUID. - name: sourceAppId | type: string | description: GUID of the app managing the earning rule. Can be a loyalty app GUID or a Wix automations app GUID. - name: triggerAppId | type: string | description: GUID of the app that triggers point assignment. Examples: Wix Stores, Wix Bookings, Wix Events. - name: triggerActivityType | type: string | description: Type of activity that triggers point assignment. For example, `wix-restaurants/orderSubmitted` or `birthday`. - name: title | type: string | description: Name of the earning rule. - name: status | type: Status | description: Current status of the earning rule. - enum: - UNKNOWN: Status is unknown or not specified. - ACTIVE: Earning rule is active and can assign points. - PAUSED: Earning rule is paused and can't assign points. - name: revision | type: string | description: Revision number, incremented by 1 each time the earning rule is updated. Pass the latest `revision` when updating to prevent conflicting changes. - name: createdDate | type: string | description: Date and time the earning rule was created. - name: updatedDate | type: string | description: Date and time the earning rule was last updated. - name: metadata | type: Metadata | description: Additional metadata about the earning rule. - name: canBeDeleted | type: boolean | description: Whether the earning rule can be deleted. - name: triggerFilters | type: array | description: Trigger filters parsed from automation configuration. Only present for automation-based rules with filters. - name: fieldKey | type: string | description: Key identifying the field in the trigger payload (e.g., "service_id", "eventId", "programId"). - name: values | type: array | description: Parsed entity GUIDs that the filter matches against. ``` ### Examples ### Create custom earning rule ```curl curl -X POST \ 'https://www.wixapis.com/_api/loyalty-earning-rules/v1/earning-rules/custom' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "type": "SOCIAL_MEDIA", "earningRule": { "title": "Follow us on Facebook", "conversionRate": { "configs": [ { "points": 20, "moneyAmount": 1 } ] } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.loyaltyProgramManagement.LoyaltyEarningRules.createCustomLoyaltyEarningRule(type, options) Description: Creates a custom automated earning rule. To learn more about the automated rules, see the Introduction. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: type Method parameters: param name: options | type: CreateCustomLoyaltyEarningRuleOptions none - name: earningRule | type: CustomLoyaltyEarningRule | description: Custom earning rule to create. - ONE-OF: - name: fixedAmount | type: FixedAmount | description: Fixed amount of points awarded for each qualifying activity. - name: configs | type: array | description: Fixed amount configurations for each tier. - name: points | type: integer | description: Number of points to award. - name: conversionRate | type: ConversionRate | description: Points awarded based on a conversion rate formula: `(amount spent) / (money_amount * points)`. - name: configs | type: array | description: Conversion rate configurations for each tier. Points are awarded proportionally to the amount spent. Formula: `(amount spent) / (money_amount * points)`. - name: moneyAmount | type: integer | description: The amount of money used as a reference for point calculation. Points are awarded proportionally to the amount spent. For example, if set to 10, 1 point is awarded for every 10 units of currency spent (assuming `points` is set to 1). Formula for points is: `(amount spent) / (money_amount * points)`. - name: points | type: integer | description: Points given for the specified `money_amount`. Works in conjunction with `money_amount` to define the earning rule. For example: If `money_amount` is 20 and `points` is 10: - Spending 10 units of currency earns 5 points - Spending 20 units of currency earns 10 points - Spending 30 units of currency earns 15 points - name: field | type: string | description: Specifies which field in the Wix automations trigger payload [REST](https://dev.wix.com/docs/rest/business-management/automations/introduction.md#how-do-automations-work)|[SDK](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/reporting-and-canceling-events.md) to use for calculating points in conversion rate rules. For example, if set to "priceSummary.totalAmount", the rule uses the total order amount to calculate loyalty points to be awarded. This field is only applicable for automated earning rules. - name: title | type: string | description: Name of the earning rule. param name: type | type: Type | required: true - enum: SOCIAL_MEDIA - Earning rule for social media. BIRTHDAY - Earning rule for birthdays. Return type: PROMISE - name: earningRule | type: LoyaltyEarningRule | description: Created earning rule. - ONE-OF: - name: fixedAmount | type: FixedAmount | description: Fixed amount of points awarded for each qualifying activity. - name: configs | type: array | description: Fixed amount configurations for each tier. - name: tierId | type: string | description: Tier GUID. If empty, the base tier is used. See the Tiers API for more information. - name: points | type: integer | description: Number of points to award. - name: conversionRate | type: ConversionRate | description: Points awarded based on a conversion rate formula: `(amount spent) / (money_amount * points)`. - name: configs | type: array | description: Conversion rate configurations for each tier. Points are awarded proportionally to the amount spent. Formula: `(amount spent) / (money_amount * points)`. - name: tierId | type: string | description: Tier GUID. If empty, the base tier is used. See the Tiers API for more information. - name: moneyAmount | type: integer | description: The amount of money used as a reference for point calculation. Points are awarded proportionally to the amount spent. For example, if set to 10, 1 point is awarded for every 10 units of currency spent (assuming `points` is set to 1). Formula for points is: `(amount spent) / (money_amount * points)`. - name: points | type: integer | description: Points given for the specified `money_amount`. Works in conjunction with `money_amount` to define the earning rule. For example: If `money_amount` is 20 and `points` is 10: - Spending 10 units of currency earns 5 points - Spending 20 units of currency earns 10 points - Spending 30 units of currency earns 15 points - name: field | type: string | description: Specifies which field in the Wix automations trigger payload [REST](https://dev.wix.com/docs/rest/business-management/automations/introduction.md#how-do-automations-work)|[SDK](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/reporting-and-canceling-events.md) to use for calculating points in conversion rate rules. For example, if set to "priceSummary.totalAmount", the rule uses the total order amount to calculate loyalty points to be awarded. This field is only applicable for automated earning rules. - name: _id | type: string | description: Loyalty earning rule GUID. - name: sourceAppId | type: string | description: GUID of the app managing the earning rule. Can be a loyalty app GUID or a Wix automations app GUID. - name: triggerAppId | type: string | description: GUID of the app that triggers point assignment. Examples: Wix Stores, Wix Bookings, Wix Events. - name: triggerActivityType | type: string | description: Type of activity that triggers point assignment. For example, `wix-restaurants/orderSubmitted` or `birthday`. - name: title | type: string | description: Name of the earning rule. - name: status | type: Status | description: Current status of the earning rule. - enum: - UNKNOWN: Status is unknown or not specified. - ACTIVE: Earning rule is active and can assign points. - PAUSED: Earning rule is paused and can't assign points. - name: revision | type: string | description: Revision number, incremented by 1 each time the earning rule is updated. Pass the latest `revision` when updating to prevent conflicting changes. - name: _createdDate | type: Date | description: Date and time the earning rule was created. - name: _updatedDate | type: Date | description: Date and time the earning rule was last updated. - name: metadata | type: Metadata | description: Additional metadata about the earning rule. - name: canBeDeleted | type: boolean | description: Whether the earning rule can be deleted. - name: triggerFilters | type: array | description: Trigger filters parsed from automation configuration. Only present for automation-based rules with filters. - name: fieldKey | type: string | description: Key identifying the field in the trigger payload (e.g., "service_id", "eventId", "programId"). - name: values | type: array | description: Parsed entity GUIDs that the filter matches against. ``` ### Examples ### createCustomLoyaltyEarningRule ```javascript import { earningRules } from '@wix/loyalty'; async function createCustomLoyaltyEarningRule(type,options) { const response = await earningRules.createCustomLoyaltyEarningRule(type,options); }; ``` ### createCustomLoyaltyEarningRule (with elevated permissions) ```javascript import { earningRules } from '@wix/loyalty'; import { auth } from '@wix/essentials'; async function myCreateCustomLoyaltyEarningRuleMethod(type,options) { const elevatedCreateCustomLoyaltyEarningRule = auth.elevate(earningRules.createCustomLoyaltyEarningRule); const response = await elevatedCreateCustomLoyaltyEarningRule(type,options); } ``` ### createCustomLoyaltyEarningRule (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 { earningRules } from '@wix/loyalty'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { earningRules }, // Include the auth strategy and host as relevant }); async function createCustomLoyaltyEarningRule(type,options) { const response = await myWixClient.earningRules.createCustomLoyaltyEarningRule(type,options); }; ``` ---