# Merits & Coupons

> Fund students' AI usage from an institution allowance, and request coupon batches.

Canonical: https://grout.app/developer/documentation/learning/merits/

**Merits** are AI credits: 1 merit = ₹1 (100 cents) of model spend inside the apps. Each user has a wallet. Institutions receive a **merit allowance** they can distribute through the API.

## Allowance

```bash
curl $API/merits/allowance -H "Authorization: Bearer $KEY"
```

Contact Grout to top the allowance up. Credits are refused with `409 insufficient_allowance` when it runs out.

## Credit a wallet

```bash
curl -X POST $API/merits/credits -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "email": "student143.4f9a2b1c@grout.user",
  "amount_cents": 500,
  "reason": "semester_grant",
  "ref": "2026-S2:S-2026-0142"
}'
```

Idempotent on `ref`: repeating the call returns `applied: false` and does not charge the allowance twice. The apps pick up the new limit on their next sync.

## Read

```bash
curl $API/merits/wallets/student143.4f9a2b1c@grout.user -H "Authorization: Bearer $KEY"    # balance + last 50 moves
curl "$API/merits/ledger?since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $KEY"     # institution-wide
```

## Coupons

Coupons are redeemable codes that credit merits. The API files a **request**; a Grout admin approves it, after which codes appear on the batch.

```bash
curl -X POST $API/coupons/batches -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "name": "Hackathon 2026", "total_coupons": 100, "value_cents": 500, "expiry_date": "2026-12-31T00:00:00Z" }'
curl $API/coupons/batches -H "Authorization: Bearer $KEY"
curl $API/coupons/batches/cb_… -H "Authorization: Bearer $KEY"        # codes once approved
curl "$API/coupons/redemptions?since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $KEY"
```

## Events

`merits.credited` (any source), `coupon.batch_requested`, `coupon.batch_approved`, `coupon.redeemed`.