# Rewards System

This doc provides a comprehensive guide to the rewards system for developers maintaining the codebase.

## Overview

The rewards system manages loyalty benefits for Scandic Hotels members. It combines data from two sources:

1. **Scandic Profile API** - Provides reward availability, states, and coupon codes
2. **Contentstack CMS** - Provides reward content (labels, descriptions, redeem instructions)

Rewards are tied to **membership levels** (L1-L7, called "Friends") and come in different **types** (Tier, Surprise, Campaign, Member-voucher).

````

### Data Merging Process

Rewards are matched between API and CMS using the `reward_id` field:

```typescript
// From query.ts - merging API and CMS data
const rewards: BaseReward[] = cmsRewards.map((cmsReward) => {
  const apiReward = redeemableRewards.find(
    ({ rewardId }) => rewardId === cmsReward.reward_id
  )!
  return {
    ...apiReward,  // API data: status, coupon codes, redeem location
    ...cmsReward,  // CMS data: label, description, redeem_description
  }
})
````

## Reward Types

### 1. Tier Rewards (`rewardType: "Tier"`)

Permanent benefits tied to membership level. These are always available once a member reaches the required tier.

**Characteristics:**

- Linked to `rewardTierLevel` (e.g., "L1", "L2")
- No coupon codes required for most
- Examples: 10% food discount, early check-in, late checkout

**Redeem behavior:**

- `On-site`: Show membership number at hotel
- `Non-redeemable`: Display-only benefits (e.g., earn rate bonuses)

### 2. Surprise Rewards (`rewardType: "Surprise"`)

Special rewards that appear as wrapped gifts and need to be "unwrapped" before use.

**Characteristics:**

- Part of `coupons` array in API response
- Have `unwrapped: boolean` flag on each coupon
- Must call `unwrap` mutation before becoming redeemable
- After unwrapping, appear in regular rewards list

**Flow:**

1. User sees surprise modal with wrapped gift
2. User clicks to reveal/unwrap
3. Frontend calls `rewards.unwrap` mutation
4. Surprise moves to current rewards

### 3. Campaign Rewards (`rewardType: "Campaign"`)

Promotional rewards with promo codes for online use.

**Characteristics:**

- Part of `coupons` array
- Have `couponCode` for redemption
- Typically redeemed online
- May have expiration dates

**Redeem behavior:**

- Display promo code with copy-to-clipboard functionality

### 4. Member Voucher (`rewardType: "Member-voucher"`)

Voucher-based rewards similar to campaigns.

**Characteristics:**

- Part of `coupons` array
- Have coupon codes
- Similar flow to Campaign rewards

---

## Coupon States & Redemption

### Coupon States

| State      | Description                                    | Redeemable |
| ---------- | ---------------------------------------------- | ---------- |
| `claimed`  | Coupon has been claimed by user                | Yes        |
| `viewed`   | Coupon has been viewed (schema only, not used) | Yes        |
| `redeemed` | Coupon has been used                           | No         |

**Note:** Only `redeemed` state is actively filtered out in business logic. Both `claimed` and `viewed` are treated as redeemable.

### Redeem Locations

| Location         | Description                       | UI Behavior                   |
| ---------------- | --------------------------------- | ----------------------------- |
| `On-site`        | Redeem at hotel (show to staff)   | Shows membership number badge |
| `Online`         | Redeem digitally with promo code  | Shows copy-to-clipboard       |
| `Non-redeemable` | Display-only (automatic benefits) | No redeem button, info only   |