> ## Documentation Index
> Fetch the complete documentation index at: https://afrizon-admin.tunzaa.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure rewards and referral programs in Meneja

> Set up a points-based rewards program and referral incentives to drive repeat purchases and customer acquisition across your marketplace.

Meneja's rewards system gives you a flexible, points-based loyalty program that you can tailor to your marketplace. Customers earn points through purchases, referrals, and bonuses, then redeem them for coupon codes at checkout. You control every aspect of the program — the earn rate, the redemption value, referral bonuses, and whether the program is active — all from the Rewards settings page.

## Rewards configuration

The rewards configuration holds the global settings for your program. There is one configuration per tenant.

| Field                   | Type    | Description                                                   |
| ----------------------- | ------- | ------------------------------------------------------------- |
| `points_per_tzs`        | number  | How many points a customer earns per Tanzanian Shilling spent |
| `redemption_points`     | number  | The number of points required to redeem a coupon              |
| `redemption_value_tzs`  | number  | The value in TZS that `redemption_points` converts to         |
| `referral_bonus_points` | number  | Points awarded to the referrer when a referral is completed   |
| `is_active`             | boolean | Enables or disables the entire rewards program                |

<Tip>
  Start with a conservative earn rate and adjust upward based on redemption patterns. A higher `points_per_tzs` value increases engagement but also raises your redemption liability.
</Tip>

### Configuring the rewards program

<Steps>
  <Step title="Open Rewards settings">
    Go to **Growth Tools → Rewards** in the sidebar, then select the **Settings** tab.
  </Step>

  <Step title="Set your earn rate">
    Enter a value for **Points per TZS**. For example, a value of `1` means a customer earns 1 point for every 1 TZS spent.
  </Step>

  <Step title="Define redemption thresholds">
    Set **Redemption points** (the minimum balance needed to redeem) and **Redemption value (TZS)** (what those points are worth at checkout).
  </Step>

  <Step title="Set the referral bonus">
    Enter the number of points to award a referrer when their referee completes a qualifying action. This value populates `referral_bonus_points`.
  </Step>

  <Step title="Activate the program">
    Toggle **Active** to enable the program. When `is_active` is `false`, no points are earned or redeemed regardless of other settings.
  </Step>
</Steps>

<Warning>
  Disabling the program (`is_active: false`) prevents new points from being earned, but does not clear existing point balances. Customers can still redeem previously accumulated points once you re-enable the program.
</Warning>

## Reward types

Every points transaction is classified by type. There are four reward types:

<CardGroup cols={2}>
  <Card title="purchase" icon="bag-shopping">
    Points earned when a customer completes a purchase. The amount is calculated using `points_per_tzs` multiplied by the order value.
  </Card>

  <Card title="referral" icon="user-plus">
    Points awarded to the referrer when a referred customer completes a qualifying action, as defined by `referral_bonus_points`.
  </Card>

  <Card title="redemption" icon="ticket">
    A debit entry recorded when a customer redeems points for a coupon code at checkout.
  </Card>

  <Card title="bonus" icon="gift">
    Discretionary points granted outside of purchases and referrals, such as promotional campaigns or manual adjustments.
  </Card>
</CardGroup>

## Reward history and balances

Each customer has a rewards balance that tracks their current points alongside their full transaction history.

### Balance fields

| Field     | Description                          |
| --------- | ------------------------------------ |
| `userId`  | The customer this balance belongs to |
| `balance` | Current redeemable points balance    |
| `history` | Array of transaction history entries |

### History entry fields

Each entry in the history represents a single points event:

| Field         | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `type`        | One of `purchase`, `redemption`, `referral`, or `bonus`        |
| `points`      | Points added (positive) or deducted (negative for redemptions) |
| `orderId`     | Associated order, if applicable                                |
| `description` | Human-readable description of the transaction                  |
| `date`        | Timestamp of the event                                         |

## Referral program

The referral program rewards customers for bringing new users to your marketplace. Each referral record links a referrer to a referee through a unique code.

| Field            | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| `code`           | The unique referral code shared by the referrer                                   |
| `referrerId`     | User ID of the customer who shared the code                                       |
| `refereeId`      | User ID of the customer who used the code                                         |
| `status`         | `pending` until the referee qualifies, then `completed`                           |
| `pointsCredited` | `true` once the `referral_bonus_points` have been added to the referrer's balance |
| `createdAt`      | When the referral was initiated                                                   |
| `completedAt`    | When the referral reached `completed` status                                      |

### Referral statistics

The referral statistics section gives you a program-level view of referral activity:

| Field                | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `totalReferrals`     | Total referral records across all statuses              |
| `pendingReferrals`   | Referrals awaiting completion                           |
| `completedReferrals` | Successfully completed referrals                        |
| `totalBonusPoints`   | Cumulative referral bonus points awarded                |
| `topReferrers`       | Ranked list of customers by referrals and points earned |

The **Top referrers** list includes each referrer's `userId`, `userName`, `referralsCount`, and `pointsEarned`, making it easy to identify your most active advocates.

## Redemptions

When a customer redeems points, Meneja generates a coupon code and records the redemption.

| Field        | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `userId`     | The customer who redeemed                                  |
| `points`     | Points deducted from the customer's balance                |
| `value`      | Monetary value of the redemption in TZS                    |
| `couponCode` | The generated coupon code the customer applies at checkout |
| `status`     | `active` (unused), `used`, or `expired`                    |
| `createdAt`  | When the redemption was initiated                          |
| `usedAt`     | When the coupon was applied to an order                    |
| `orderId`    | The order the coupon was applied to, if used               |

<AccordionGroup>
  <Accordion title="What happens when a coupon expires?">
    A redemption record moves to `expired` status when the coupon code has not been used within its validity window. The deducted points are not automatically refunded — you must issue a manual bonus adjustment if you wish to return them.
  </Accordion>

  <Accordion title="Can I view a single customer's point history?">
    Yes. Use the Rewards section to look up a customer by their user ID and view their full `RewardBalance`, including the complete `history` array with all point events sorted by date.
  </Accordion>

  <Accordion title="How do I grant bonus points manually?">
    Create a `RewardHistory` entry with `type: 'bonus'`, the relevant `points` value, and a `description` explaining the reason. This increments the customer's `balance` immediately.
  </Accordion>
</AccordionGroup>