# Reward

Reward your customers for their loyalty with exclusive rewards and discounts. Create customized rewards based on your business requirements, set discount types as percentage or fixed amount, and manage coupon lifecycle rules.

:::tip
Rewards can be linked to milestones in streaks or challenges. When a user reaches a milestone, the platform automatically issues the associated reward along with a coupon code.
:::

## How it works

1. **Define a reward** — set a name, description, discount type (percentage or fixed amount), and discount value.
2. **Configure expiration** — specify whether the reward has no expiry, relative expiry (in days), or an absolute expiry date.
3. **Set coupon handling** — decide whether Gamopanda handles coupons manually (uploaded coupon pool) or via automatic generation.
4. **Attach to milestones** — link the reward to milestones in streaks or challenges so it is issued automatically upon progress completion.
5. **Issue & track** — when a user completes a milestone, a `Reward Log` is created, issuing the reward and coupon code to the user.

---

## Fields

### Basic information

| Field | Type | Required | Max length | Description |
|---|---|---|---|---|
| `name` | string | ✅ | 256 | The name of the reward |
| `description` | string | ✅ | 1 024 | A brief description of the reward |
| `discountType` | enum | ✅ | — | `percentage` · `fixed_amount` — The type of discount offered |
| `discountValue` | number | ✅ | — | The value of the discount |
| `rewardExpiryType` | enum | ✅ | — | `no_expiry` · `relative` · `absolute` — Expiration logic for the reward |
| `rewardExpiryInDays` | number | ❌* | — | Expiry duration in days. *Required when `rewardExpiryType` is `relative` |
| `rewardExpiryAt` | datetime | ❌* | — | Fixed expiry date and time. *Required when `rewardExpiryType` is `absolute` |
| `handleCoupon` | boolean | ❌ | — | `true` · `false` (default: `false`). Set to `true` if Gamopanda should handle coupons via uploaded pool or auto-generation |
| `handleCouponAutoGeneration` | boolean | ❌ | — | `true` · `false` (default: `false`). Set to `true` to enable automatic coupon code generation |

### Real-world examples

**🛍️ E-commerce — 10% Off Percentage Reward with 30-Day Expiry**

A percentage-based discount reward issued upon milestone achievement, valid for 30 days after issuance.

```json
{
  "name": "10% Off Coupon",
  "description": "Earn rewards for logging in every day for a week. Complete the week, unlock a special badge and bonus points!",
  "discountType": "percentage",
  "discountValue": 10,
  "rewardExpiryType": "relative",
  "rewardExpiryInDays": 30,
  "handleCoupon": true,
  "handleCouponAutoGeneration": true
}
```

---

**☕ Food & Beverage — $5 Off Fixed Amount Reward**

A fixed dollar amount discount that never expires.

```json
{
  "name": "Weekly Purchase Streak",
  "description": "Visit the store 5 days in a row to maintain your streak. Each day counts towards a bigger prize!",
  "discountType": "fixed_amount",
  "discountValue": 5,
  "rewardExpiryType": "no_expiry",
  "handleCoupon": true,
  "handleCouponAutoGeneration": false
}
```

---

**🏋️ Fitness & Activity — Fixed Expiry Date Reward**

An activity-based promotional reward that expires at a specific date and time.

```json
{
  "name": "Monthly Activity Streak",
  "description": "Engage with our content for 10 consecutive days to receive exclusive access to premium features.",
  "discountType": "percentage",
  "discountValue": 50,
  "rewardExpiryType": "absolute",
  "rewardExpiryAt": "2026-08-31T23:59:59+05:30",
  "handleCoupon": true,
  "handleCouponAutoGeneration": true
}
```

---

## End-user display (EUD)

All EUD fields are **localisable** — supply a `languageCode` query parameter when reading to receive the translated value.

### Labels

| Field | Default | Max length | Description |
|---|---|---|---|
| `eudTitle` | — | 48 | Title shown to the end user (e.g., `10% off`, `$20 off`) |

### Messages

Messages support **template variables** that are resolved at runtime. Available variables:

| Variable | Description | Example value |
|---|---|---|
| `{{$helpers.rewardValidTill}}` | Formatted expiry date and time of the issued reward | `2026-08-31 23:59:59` |

**Rendered example** — for a reward expiring on 31 August 2026:

| Variable | Resolved value | Remarks |
|---|---|---|
| `{{$helpers.rewardValidTill}}` | `2026-08-31 23:59:59` | Formatted based on user locale |

The default `eudRedeemInstructionMessage` would render as:

> *Use the offer code at checkout to redeem your reward! Valid till 2026-08-31 23:59:59.*

| Field | Default | Max length |
|---|---|---|
| `eudRedeemInstructionMessage` | `Use the offer code at checkout to redeem your reward! Valid till {{$helpers.rewardValidTill}}.` | 1 024 |

---

## Access & permissions

| Caller | Allowed operations |
|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE |
| End user | *(none)* |
| Guest (unauthenticated) | *(none)* |

---

## Related resources

A reward is linked to milestones, coupons, and reward logs:

| Resource | Description |
|---|---|
| [Milestone](/milestone) | Reward checkpoints that trigger issuance of rewards |
| [Reward Log](/reward-log) | System-generated records tracking issued rewards and expiration |

---

## API reference

See the [API Reference](/api/reward) for full request/response schemas and interactive examples for:

- `GET /schema/reward/record` — list rewards
- `POST /schema/reward/record` — create a reward
- `GET /schema/reward/record/{id}` — get a reward by ID
- `PATCH /schema/reward/record/{id}` — update a reward
- `DELETE /schema/reward/record/{id}` — delete a reward