Credit Grants — Hypery Docs

Overview

Credit grants let your app give credits to its users, funded from your own Hypery balance. Use them to offer a free daily/weekly allowance (so users can try your app without their own card — like Claude Code's free tier) or to hand out one-time bonuses.

Because a user's AI usage is billed to their account, a grant moves credits from your team to the user's balance. Grants apply two ways:

Recurring allowance (a rule): every eligible user gets up to N credits per period, granted by a scheduled job that runs each period.
One-time grant (the API/UI): give a specific user credits right now.

Authentication: your personal API key (ak_...) or an OAuth token with the write scope (read for the GET endpoints). Only the app's owner or a billing admin may manage grants. Amounts are in credits (100 credits = $1).

Rules

List rules

Endpoint: GET /api/apps/{appId}/grants/rules

curl https://hypery.ai/api/apps/{appId}/grants/rules \
  -H "Authorization: Bearer ak_your_key"

Create a rule

Endpoint: POST /api/apps/{appId}/grants/rules

curl -X POST https://hypery.ai/api/apps/{appId}/grants/rules \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily free",
    "amount": 100,
    "refillStrategy": "topup_to",
    "cadence": "daily",
    "audiences": ["all_authorized"],
    "perPeriodBudget": 50000
  }'

Field	Type	Description
`name`	string	Label shown in your dashboard.
`amount`	int	Credits per grant.
`refillStrategy`	`topup_to` \| `add`	`topup_to`: refill the user up to `amount` each period (no hoarding). `add`: add `amount` each period.
`cadence`	`once` \| `hourly` \| `daily` \| `weekly` \| `monthly`	How often a user may receive the grant.
`audiences`	string[]	Any of `all_authorized`, `new_users`, `explicit`. A user matching any selected audience is eligible.
`newUserWindowHours`	int?	For `new_users`: hours since the user authorized your app (default 720 = 30 days).
`explicitUserIds`	string[]?	For `explicit`: the user ids allowed.
`perPeriodBudget`	int	Max credits granted per period across all users (0 = only your balance limits it). Grants pause for the period once hit.
`enabled`	boolean	Defaults to `true`.

Response: 201 { "success": true, "data": { "rule": { "_id": "...", ... } } }.

Update a rule

Endpoint: PATCH /api/apps/{appId}/grants/rules/{ruleId}

Send only the fields you want to change (same fields as create). Toggle a rule off with { "enabled": false }.

curl -X PATCH https://hypery.ai/api/apps/{appId}/grants/rules/{ruleId} \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 200, "enabled": true }'

Response: { "success": true, "data": { "rule": { ... } } } · 404 if the rule doesn't belong to this app.

Delete a rule

Endpoint: DELETE /api/apps/{appId}/grants/rules/{ruleId}

curl -X DELETE https://hypery.ai/api/apps/{appId}/grants/rules/{ruleId} \
  -H "Authorization: Bearer ak_your_key"

Response: { "success": true, "data": { "deleted": 1 } }.

Grant credits now

Give a specific user credits immediately (one-time). Funded from your balance.

Endpoint: POST /api/apps/{appId}/grants

curl -X POST https://hypery.ai/api/apps/{appId}/grants \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "amount": 500, "idempotencyKey": "welcome-user-42" }'

Field	Type	Description
`userId` or `email`	string	Who receives the credits (one required).
`amount`	int	Credits to grant.
`idempotencyKey`	string?	Supply a stable key to make retries safe — the same key never grants twice.
`description`	string?	Shows on the user's transaction.

Response: { "success": true, "data": { "granted": 500, "idempotencyKey": "..." } }. Returns 402 INSUFFICIENT_FUNDER_BALANCE if your balance can't cover it (add credits and retry).

Customer balance

Check a user's current credits and how much your app has granted them — e.g. to show "you have X free credits left" in your product.

Endpoint: GET /api/apps/{appId}/grants/customers/{userId}/balance

Response:

{ "success": true, "data": { "userId": "...", "availableCredits": 320, "grantedByAppTotal": 500 } }

List issued grants

GET /api/apps/{appId}/grants — the 100 most recent grant issuances for the app (audit trail: who, how much, when, which rule).