Product-user credit grants
Allocate consumable credit to one product user and configure connection credit modes.
Credit grants allocate spendable virtual credit to a product user in your application. They are distinct from organization wallet balances and spending caps.
For admission checks, read total available allowance. For purchased credits, follow Grant credits after a payment.
Create or resolve the user and grant credit in one service key request:
curl -X POST https://api.zorveus.com/product-users/by-external-id/credit-grants \
-H "Authorization: Bearer zrv_svc_your_service_key" \
-H "Content-Type: application/json" \
-d '{
"app_id": "app_123",
"external_user_id": "customer_42",
"amount": "10.00",
"currency": "USD",
"source": "promotion",
"reason": "Welcome credit",
"expires_at": "2026-12-31T23:59:59Z"
}'Connection credit enforcement modes
The app connection defines a credit_mode that governs allowance enforcement:
| Mode | Request with product user | Request without product user | Behavior |
|---|---|---|---|
enforce_if_present (default) | Enforces base cap plus credits | Bypasses cap checks, records virtual spend | Recommended for keys serving both user traffic and internal jobs. |
enforce | Enforces base cap plus credits | Enforces key-level cap | Strict enforcement across all traffic. |
track_only | Allocates cap and credits without blocking | Allocates cap without blocking | Never rejects for allowance. Records uncovered_virtual_spend. |
disabled | Bypasses cap checks and credits | Bypasses cap checks | Records virtual spend for reporting without quota limits. |
User OAuth app connections always return credit_mode: "enforce". The update endpoint rejects any other value for user OAuth connections.
Allowance formula and deduction order
When a product user sends an inference request on a capped key, Zorveus consumes allowance in this order:
- Remaining base allowance: Zorveus checks the inference key spending cap. If base allowance remains, usage is applied to the cap first.
- Active credit grants (earliest expiration first): If the request exceeds remaining base allowance, the excess is deducted from active unexpired credit grants.
- Uncovered virtual spend: In non-blocking
track_onlymode or when overruns occur, spend beyond the cap and credits is recorded as uncovered virtual spend.
If an inference key has no cap rule, virtual allowance is unlimited across all credit modes. The request succeeds, virtual spend is recorded, and zero product-user credits are consumed. Credits extend an existing cap; they do not enforce a quota where no cap is configured.
When the configured policy blocks an unfunded request, the gateway rejects the request with HTTP 403 Forbidden (zorveus_product_user_allowance_insufficient). Overrun behavior also depends on the connection's policy.