# Introduction

The Earning Rules API allows you to manage earning rules for your loyalty program. Earning rules define how customers earn points through various activities, such as making purchases or registering for events.

With the Earning Rules API, you can:

+ [Create loyalty earning rules](fallback::https://dev.wix.com/docs/sdk/backend-modules/loyalty/earning-rules/create-loyalty-earning-rule) to set up new rules for earning points.
+ [List earning rules](fallback::https://dev.wix.com/docs/sdk/backend-modules/loyalty/earning-rules/list-earning-rules) to retrieve all earning rules in your loyalty program.
+ [Bulk create loyalty earning rules](fallback::https://dev.wix.com/docs/sdk/backend-modules/loyalty/earning-rules/bulk-create-loyalty-earning-rules) to set up multiple earning rules at once.
+ [Update loyalty earning rules](fallback::https://dev.wix.com/docs/sdk/backend-modules/loyalty/earning-rules/update-loyalty-earning-rule) to modify existing earning rules.
+ [Delete loyalty earning rules](fallback::https://dev.wix.com/docs/sdk/backend-modules/loyalty/earning-rules/delete-loyalty-earning-rule) to remove earning rules that are no longer needed.
+ [Delete automation earning rules](fallback::https://dev.wix.com/docs/sdk/backend-modules/loyalty/earning-rules/delete-automation-earning-rule) to remove automated earning rules.

To learn more about earning rules, see [Managing Your Loyalty Program](fallback::https://support.wix.com/en/article/wix-loyalty-program-managing-your-loyalty-program).

## Before you begin

It's important to note the following points before starting to code:

+ The API supports both automated and non-automated earning rules.
+ You must have the Wix Loyalty Program app installed on your site to use this API.


## Types of Earning Rules

The Wix Loyalty program supports two types of earning rules:

1. Automated earning rules
2. Non-automated earning rules

Both types allow customers to earn points for various actions, but differ in their creation, management, and customization options.

### Automated Earning Rules

Automated earning rules are enabled by Wix Automations. There are two subtypes:

1. Pre-installed earning rules
2. Custom earning rules

#### Pre-installed Rules

Pre-installed rules appear automatically when certain business solutions are installed. These rules can be disabled but not deleted.

| Earning Rule Name | Activity Type | Supported Types |
|-----------|---------------|-----------------|
| Order a plan (Wix Pricing Plans) | `wix_pricing_plans-plan_purchased` | Fixed amount, Conversion rate |
| Place a restaurant order (Legacy Wix Restaurants) | `wix_restaurants_orders-order_submitted` | Conversion rate only |
| Place a restaurant order (New Wix Restaurants) | `restaurants-order-is-pending` | Conversion rate only |

#### Custom Rules

Custom rules are created by users and don't come pre-installed. All automated earning rules not listed above fall into this category.

### Non-Automated Earning Rules

Non-automated earning rules can be created based on installed Wix business solutions. These rules are identified by their `sourceAppId`, which differs from automated earning rule `sourceAppId`.

Supported non-automated earning rules:

| Earning Rule Name | Activity Type | Supported Types |
|-----------|---------------|-----------------|
| Purchase a product (Wix Stores) | `stores/OrderPaid` | Fixed amount, Conversion rate |
| Book a session (Wix Bookings) | `bookings/BookingConfirmed` | Fixed amount only |
| Buy a ticket (Wix Events) | `events/OrderConfirmed` | Fixed amount, Conversion rate |
| RSVP to an event (Wix Events) | `events/Rsvp` | Not specified |

For example, if you have Wix Events installed, you can create an earning rule that is triggered when a customer buys a ticket or RSVPs to an event.


## Points Calculation

Earning rules can award points in two ways:

1. **Fixed Amount**: A set number of points is awarded for a specific action. For example, a customer might receive 10 points for purchasing a ticket through Wix Events.

2. **Conversion Rate**: Points are awarded based on a ratio of money spent to points earned. For example, a customer might receive 10 points for every $1 spent. The formula is: `(amount spent) / (moneyAmount * points)`.


## Terminology

+ __Earning Rule__: A condition that, when met, awards loyalty points to a customer. All earning rules allow customers to earn points for performing certain actions, without a minimum spending requirement.
+ __Non-Automated Earning Rule__: An earning rule set up for specific business solutions, identified by its `sourceAppId`.
+ __Automated Earning Rule__: An earning rule enabled by Wix Automations, which can be pre-installed or custom:
    - __Pre-Installed__: An automated earning rule that comes by default with certain services, which can be disabled but not deleted.
    - __Custom__: An automated earning rule created by the site owner, not pre-installed by default.
+ __Fixed Amount__: An earning rule type where a set number of points is awarded for a specific action. For example, a customer might receive 10 points for purchasing a ticket through Wix Events.
+ __Conversion Rate__: An earning rule type where points are awarded based on a ratio of money spent to points earned. The formula is: `[amount spent] / moneyAmount * points`.
+ __Trigger App ID__: The ID of the app that initiates the point assignment. For example: Stores, Bookings, Events.
+ __Trigger Activity Type__: The specific action that triggers point assignment. For example: `"auth/register"`, `"events/OrderConfirmed"`.
+ __Source App ID__: The ID of the app managing the rule, which can be either the Loyalty app ID or an Automations app ID.
+ __Tier__: A tier is a loyalty level that customers are assigned to based on the amount of points they earn. Customers in different tiers may earn points at different rates for the same activity. For example, a higher tier member might earn more points per purchase than a lower tier member.
+ __Status__: The current state of an earning rule (for example, `ACTIVE`, `PAUSED`).

@package_metadata:@wix/loyalty

To use the EarningRules API, install the `@wix/loyalty` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/loyalty` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/loyalty` or `yarn add @wix/loyalty`. |
| Headless sites and apps | Run `npm install @wix/loyalty` or `yarn add @wix/loyalty`. |

#### Import the package

To import the package in your code:

```js
import { earningRules } from '@wix/loyalty'
```

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)

listEarningRules( )