Skip to content
Docs

Learning & Credits

Merits & Coupons

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

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": "[email protected]",
  "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.

PreviousAlpha LearningNextOverview