# Coupon

Coupons are specific promotional codes linked to a parent **Reward**. They represent the claimable codes issued to end users when milestones or campaign goals are achieved.

:::tip
You can upload a pool of pre-generated coupon codes for Gamopanda to assign automatically, or enable auto-generation on the parent Reward configuration.
:::

## How it works

1. **Create a reward** — define a `Reward` record specifying the discount type, discount value, and expiry rules.
2. **Add coupons** — create `Coupon` entries linked to the reward's `rewardId` with unique `couponCode` values.
3. **Issue to user** — when a user completes a milestone, the platform selects an unissued coupon (`isCouponIssued: false`), marks `isCouponIssued: true`, and attaches it to the user's `Reward Log`.
4. **Redeem** — the user copies the `couponCode` from their widget or dashboard to redeem at checkout.

---

## Fields

### Basic information

| Field | Type | Required | Max length | Description |
|---|---|---|---|---|
| `rewardId` | UUID | ✅ | — | The ID of the parent reward associated with this coupon |
| `couponCode` | string | ✅ | 256 | The unique promotional code (e.g., `OFF2026`, `WEEKDAYSPECIAL`) |
| `isCouponIssued` | boolean | ✅ | — | `true` · `false` (default: `false`). Indicates whether this coupon has been issued to a user |
| `status` | enum | ✅ | — | `draft` · `live` · `paused` — Current status of the coupon |

---

## Real-world examples

**🛍️ E-commerce — 20% Off Campaign Coupon**

An unissued promotional coupon ready for milestone assignment:

```json
{
  "rewardId": "123e4567-e89b-12d3-a456-426614174000",
  "couponCode": "OFF2026",
  "isCouponIssued": false,
  "status": "live"
}
```

---

**☕ Food & Beverage — Weekday Special Coupon**

A coupon that has already been issued to a user upon milestone completion:

```json
{
  "rewardId": "123e4567-e89b-12d3-a456-426614174001",
  "couponCode": "WEEKDAYSPECIAL",
  "isCouponIssued": true,
  "status": "live"
}
```

---

## Access & permissions

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

---

## Related resources

| Resource | Description |
|---|---|
| [Reward](/reward) | Parent reward that defines the discount benefit for this coupon |
| [Reward Log](/reward-log) | Logs generated when a coupon is issued to an end user |
| [Milestone](/milestone) | Checkpoints that trigger reward and coupon issuance |

---

## API reference

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

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