> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-mk-earning-rule-builder.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Earning rule builder

> Create and manage rules that control how loyalty points are awarded

Earning rules define when customers receive points for selected activities and transactions.

<Note>
  Time-related settings in earning rule configuration use the time zone configured in **Project settings**. They are not calculated in UTC.
</Note>

Go to **Loyalty hub** > **Earning rules**.

From the **Earning rules** view, you can:

* View all existing earning rules and their status.
* Open earning rules to review their configuration and **Activate** or **Deactivate** them.
* Search earning rules with the search bar.
* Filter earning rules with **Add filter**.
* Create earning rules with **+ Create earning rule**.
* Edit, change status, or delete earning rules with the contextual actions menu (`⋮`).

## Create an earning rule

Earning rules are configured in a multi-step builder. Some settings depend on each other. If something is missing or incompatible, the builder displays an **Action required** status.

You can also use **Save draft** and complete the configuration later.

Go to **Loyalty hub** > **Earning rules** and use **+ Create earning rule**.

Enter the earning rule name in **Name earning rule**.

<Steps>
  <Step>
    ### Trigger

    Define the event that activates the earning rule.

    Configure:

    * **Trigger event**: Selects the event that activates the rule.
    * **Custom error message**: Optional message displayed when the earning rule cannot be applied.

    Supported trigger events:

    * **Order paid**: Triggers the earning rule after an order is successfully paid.
    * **Custom event**: Triggers the earning rule when a selected custom event is sent to Voucherify.
    * **Segment entered**: Triggers the earning rule when a customer enters a selected segment.

    Additional configuration depends on the selected trigger event.

    <Tabs>
      <Tab title="Order paid">
        No additional configuration is required.
      </Tab>

      <Tab title="Custom event">
        Select the event in **Custom event**.

        Use the search field to find existing custom events or use the **+** icon to create a new one directly from the builder.
      </Tab>

      <Tab title="Segment entered">
        Select the segment in **Segment**.

        Use the search field to find existing segments or use the **+** icon to create a new one directly from the builder.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Earnings

    Define the conditions and effects used to award points.

    Use **+ Add earning** to create additional earning configurations within the same earning rule.

    Earning configurations are evaluated in the order they appear in the builder. **Earning #1** has the highest priority.

    If the customer does not match the first earning configuration, Voucherify checks the next one in order until an earning is fulfilled. If no earning is fulfilled, no points or benefits are awarded.

    Each earning configuration contains:

    * **Earning name**: Internal name used to identify the earning configuration.
    * **Tier**: Loyalty tiers that the earning configuration applies to.
    * **When**: Conditions that must be matched.
    * **Then**: Effects applied after the conditions are matched.

    #### Tier

    Use the **Tier** section to select which loyalty tiers the earning configuration applies to. Members who don't belong to a selected loyalty tier won't earn points as defined in this earning.

    You can select one or more tiers from different tier structures.

    #### When

    Use the **When** section to define conditions for the earning configuration.

    Use **Add rule** to create conditions and **Add brackets** to group multiple conditions into logical expressions.

    Conditions are grouped by category.

    <Tabs>
      <Tab title="Audience">
        Audience rules define customer-based conditions.

        * **Customer segment**: Checks whether the customer belongs to a selected segment.
      </Tab>

      <Tab title="Products">
        Product rules define conditions related to items in the order.

        * **Any order item**: Checks whether at least one order item matches the condition.
        * **Every order item**: Checks whether all order items match the condition.
        * **None of the order items**: Checks whether no order items match the condition.
        * **Most expensive of the order items**: Checks the most expensive item in the order.
        * **Cheapest of the order items**: Checks the cheapest item in the order.
      </Tab>

      <Tab title="Prices & Quantities">
        Price and quantity rules define conditions related to order values and quantities.

        * **Total amount before discounts**: Checks the order value before discounts are applied.
        * **Total amount after discounts**: Checks the order value after discounts are applied.
        * **Initial amount**: Checks the original order amount.
        * **Items quantity**: Checks the number of items in the order.
        * **Price of each item**: Checks the price of every item in the order.
        * **Price of any item**: Checks the price of at least one item in the order.
      </Tab>

      <Tab title="Customer metadata">
        Customer metadata rules define conditions based on customer metadata values.

        Available metadata keys depend on the customer metadata schema configured in your project.

        Use **Add to schema** to create a new metadata key directly from the builder.
      </Tab>

      <Tab title="Order metadata">
        Order metadata rules define conditions based on order metadata values.

        Available metadata keys depend on the order metadata schema configured in your project.

        Use **Add to schema** to create a new metadata key directly from the builder.
      </Tab>
    </Tabs>

    The following actions are available when configuring rules and brackets:

    <AccordionGroup>
      <Accordion title="Rule actions">
        After adding a rule, use the three-dot menu next to the rule name to manage rule actions.

        Available rule actions:

        * **Error message**: Defines a custom validation message for the selected rule.
        * **Edit rule**: Updates the selected rule configuration.
        * **Duplicate rule**: Creates a copy of the selected rule.
        * **Add next rule**: Adds another rule after the selected rule.
        * **Add next brackets**: Adds a new bracket group after the selected rule.
        * **Remove rule**: Removes the selected rule from the earning configuration.
        * **Surround with brackets**: Groups the selected rule inside brackets.
      </Accordion>

      <Accordion title="Bracket actions">
        Use the three-dot menu on the right side of the bracket group to manage bracket actions.

        Available bracket actions:

        * **Add rule**: Adds a new rule inside the selected bracket group.
        * **Add next rule**: Adds a new rule after the selected bracket group.
        * **Add brackets**: Adds a nested bracket group inside the selected bracket group.
        * **Add next brackets**: Adds a new bracket group after the selected bracket group.
        * **Remove brackets and rules inside**: Removes the selected bracket group together with all rules inside it.
      </Accordion>
    </AccordionGroup>

    #### Then

    Use the **Then** section to define the effects applied when the earning conditions are matched.

    Each earning can contain multiple effects. Use **+ Add effect** to create additional effects within the same earning.

    Choose one of the following effect types:

    * **Fixed points**
    * **Proportional points**
    * **Incentive**

    <Tabs>
      <Tab title="Fixed points">
        Award a fixed number of points to the selected wallet.

        Configure the following fields:

        * **Point wallet**: Selects the point wallet that receives the points.
        * **Points**: Number of points awarded when the earning rule is triggered.

        You can create a new wallet directly from the builder using the **+** icon.
      </Tab>

      <Tab title="Proportional points">
        Award points proportionally based on order values, quantities, or metadata values.

        Configure the following fields:

        * **Calculation type**: Defines how the proportional points are calculated.
        * **Point wallet**: Selects the point wallet that receives the points.
        * **Points**: Number of points awarded.

        Calculation methods are grouped by type.

        <AccordionGroup>
          <Accordion title="Order amount calculations">
            Use order amount calculations to award points based on total order values:

            * **Pre-discount order amount**: Uses the total order amount before discounts are applied. Configure **Amount**.
            * **Post-discount order amount**: Uses the total order amount after discounts are applied. Configure **Amount**.
          </Accordion>

          <Accordion title="Order item calculations">
            Use order item calculations to award points based on selected order items:

            * **Pre-discount order items amount**: Uses selected order item values before discounts are applied. Configure **Amount** and **Applicable to**.
            * **Post-discount order items amount**: Uses selected order item values after discounts are applied. Configure **Amount** and **Applicable to**.
            * **Order items quantity**: Uses the quantity of selected order items. Configure **Quantity** and **Applicable to**.

            Use **Applicable to** to select products or product collections included in the calculation. You can select multiple products or collections.
          </Accordion>

          <Accordion title="Metadata calculations">
            Use metadata calculations to award points based on metadata values:

            * **Customer metadata value**: Uses a selected customer metadata property. Configure **Value** and **Metadata property**.
            * **Order metadata value**: Uses a selected order metadata property. Configure **Value** and **Metadata property**.

            You can create a new metadata property directly from the builder using the **+** icon.
          </Accordion>
        </AccordionGroup>

        You can create a new wallet directly from the builder using the **+** icon.
      </Tab>

      <Tab title="Incentive">
        Award incentives instead of loyalty points.

        Configure the following field:

        * **Incentive**: selects the incentive awarded when the earning rule is triggered.

        You can create a new incentive directly from the builder using the **+** icon.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Trigger limits

    Define cooldown and frequency limits for triggering the earning rule.

    #### Cooldown

    Control how often the earning rule can be triggered for the same customer.

    Available options:

    * **No cooldown**: The earning rule can be triggered at any time.
    * **Fixed cooldown**: Limits how often the earning rule can be triggered for the same customer.

    When **Fixed cooldown** is selected, configure the following fields:

    * **Period**: Cooldown duration value.
    * **Period unit**: Cooldown duration unit.

    Supported period units:

    * **Hour**
    * **Day**
    * **Week**
    * **Month**
    * **Year**

    Maximum values depend on the selected period unit.

    #### Frequency

    Limit how many times the earning rule can be triggered within a selected time period.

    Available options:

    * **No limit**: No restriction on how often the earning rule can be triggered.
    * **Limited**: Limits the number of eligible triggers within a selected time period.

    When **Limited** is selected, configure the following fields:

    * **Max triggers**: Maximum number of allowed triggers. The maximum supported value is `10,000`.
    * **Period**: Time period used for the frequency limit.

    Supported period units:

    * **Day**
    * **Week**
    * **Month**
    * **Quarter**
    * **Year**
  </Step>

  <Step>
    ### Timeframe

    Define when the earning rule becomes active and when it expires.

    #### Start date

    Define when the earning rule becomes active.

    Available options:

    * **Creation**: The earning rule becomes active immediately after it is created.
    * **Specific date**: The earning rule becomes active at a selected date and time.

    When **Specific date** is selected, configure:

    * **Date**: Activation date.
    * **Time**: Activation time.

    #### Expiration

    Define when the earning rule expires.

    Available options:

    * **Never**: The earning rule does not expire.
    * **On specific date**: The earning rule expires at a selected date and time.

    When **On specific date** is selected, configure:

    * **Date**: Expiration date.
    * **Time**: Expiration time.

    #### Valid hours per day

    Limit when the earning rule can be triggered during the week.

    By default, the earning rule is applicable all days of the week, all day long.

    Use **+ Add valid hours per day** to limit when the earning rule can be triggered during the week.

    When configuring valid hours, define:

    * **Start time**: Beginning of the valid time range.
    * **Expiration time**: End of the valid time range.
    * **Days of the week**: Days when the earning rule is active within the selected time range.

    Available days:

    * Sunday
    * Monday
    * Tuesday
    * Wednesday
    * Thursday
    * Friday
    * Saturday

    Multiple valid hour ranges can be configured.
  </Step>

  <Step>
    ### Metadata

    <MetaConfig />
  </Step>

  <Step>
    ### Summary

    Review the earning rule configuration before saving.

    The summary page displays all configured sections:

    * Trigger
    * Earnings
    * Trigger limits
    * Timeframe
    * Metadata

    Use **Go to step** to return to a selected section and make changes before saving the earning rule.

    After reviewing the configuration:

    * Use **Save draft** to save the earning rule without activating it
    * Use **Save** to create and activate the earning rule immediately
  </Step>
</Steps>

## Manage earning rules in the loyalty designer

Earning rules can be assigned and managed directly from the loyalty program designer.

The **Earning rules** section displays all earning rules currently assigned to the program and all earning rules to the added point wallets.

Earning rules award points to point wallets selected in the **Point wallet** field.

You can assign only the earning rules that are either assigned to the point wallets used in the loyalty program or that award benefits (meaning earning rules that do not give points).

To assign an earning rule from the loyalty designer:

1. In the **Earning rules** section, select:
   * The **+** button in the **Building blocks**,
   * Or the **No earning rules assigned** field.
2. In the assignment dialog:
   * Select an existing earning rule from the list,
   * Or select **+ Create new** to open the simplified earning rule builder.

The simplified earning rule builder supports:

* Defining the earning rule name
* Selecting the trigger event
* Configuring earning effects
* Assigning point wallets
* Multiple earning effects

Select **Advanced options** to open the full earning rule builder with additional configuration options, including earning conditions and trigger limits.

You can also assign earning rules from the **Building blocks** panel.

Earning rules can be assigned regardless of their current status. Assigning or unassigning earning rules does not change whether the earning rule is active or inactive.

Assigned earning rules can later be:

* Edited from the loyalty designer workspace.
* Unassigned from the loyalty program.
* Deleted from the **Building blocks** panel once the earning rule is unassigned from the loyalty program.

Deleting an earning rule removes it from all loyalty programs where it is currently assigned.

Selecting the edit icon from the loyalty designer opens the full earning rule builder.

## Related features

<AccordionGroup>
  <Accordion title="Point wallet builder">
    Learn how to create and manage wallets used in earning rules through the **Point wallet** configuration.
  </Accordion>

  <Accordion title="Loyalty designer">
    Learn how to configure loyalty programs and manage program building blocks.
  </Accordion>
</AccordionGroup>