Configure product-user allowances
Choose model access, caps, enforcement, and overrun settings with practical examples.
Use this guide when your product pays for customers' AI usage. Configure the API key's connection in the dashboard. Your backend selects the key for the customer's plan and sends the customer's external user ID on every request.
Start with this configuration
For a product with finite customer allowances:
| Setting | Starting choice | Why |
|---|---|---|
| Allowed models | The models your product uses | Avoid unintended model access. |
| Cap amount and period | Your plan's AI allowance, such as $10 monthly | Establish a finite base allowance. |
credit_mode | enforce | Enforce configured allowance even when attribution is missing. |
overrun_policy | limit_output | Reduce the output limit to the affordable amount. |
| External user ID | Your stable customer ID on every request | Attribute usage and apply product-user credits. |
| Allowance anchor | Subscription start time, or no anchor for UTC calendar periods | Align resets with your billing cycle. |
Which settings belong where?
- Your backend selects a planChoose the API key for Free or Pro. Do not let the customer choose the key.
- The connection supplies rulesAllowed models, cap amount and period, credit mode, and overrun policy.
- The user ID supplies attributionZorveus applies the customer's usage, credits, and allowance anchor.
| Connection settings, configured in the dashboard | Product-user settings |
|---|---|
Allowed models, cap amount and period, credit_mode, overrun_policy | External user ID, profile metadata, allowance anchor, and credit grants |
An active direct product-user cap can override the connection cap used to resolve that user's allowance. Manage caps in the dashboard. Set profile details and the anchor through supported product-user operations or inference metadata. Grant credits through the service-key API.
Choose the credit mode
These behaviors assume a configured cap. This table describes allowance enforcement, not every possible request rejection.
credit_mode | With external user ID | Without external user ID | Choose it when |
|---|---|---|---|
enforce_if_present, default | Enforces base allowance plus eligible credits | Bypasses virtual allowance checks | Unattributed internal work intentionally shares a key with customer traffic. |
enforce | Enforces base allowance plus eligible credits | Enforces key-level allowance | Missing attribution must not bypass allowance enforcement. |
track_only | Tracks base allowance, credit use, and uncovered spend without blocking for allowance | Tracks usage without blocking for allowance | You want to observe spend before enforcing limits. |
disabled | Skips allowance checks and credit consumption | Skips allowance checks | You want usage reporting without virtual quotas. |
enforce does not require a user ID. Your backend must require the ID if every request must be attributed. OAuth user connections always use enforce.
Request arrives
├─ No cap → unlimited virtual allowance; no credits consumed
└─ Cap configured
├─ disabled → skip allowance checks and credits
├─ track_only → account for allowance; do not block for it
├─ enforce_if_present + no user ID → bypass virtual allowance checks
└─ enforced request → check applicable base allowance + eligible credits
Model access and funding checks still apply on every path.Choose the overrun policy
The credit mode controls allowance enforcement. The overrun policy controls how a request handles output that could exceed the remaining allowance.
overrun_policy | What happens | Choose it when |
|---|---|---|
limit_output, default | Lowers the provider output limit to the affordable amount. Unexpected variance can still be recorded as uncovered spend. | Limiting spend matters more than a longer answer. |
allow_overrun | Allows output up to the declared or safe limit. Records excess as uncovered spend, without carrying debt into future allowance. | Finishing an admitted response matters more than staying within its remaining allowance. |
carry_overrun_forward | Allows output up to the declared or safe limit. Records excess as debt repaid from later credits or base allowance resets. | A longer answer is allowed, but future allowance must cover the excess. |
Overrun policies do not supply wallet funds or guarantee admission when allowance is already exhausted. They do not override model access or funding checks.
Scenarios
Free and Pro customers use different keys
Configure two connections in the dashboard:
| Plan | Monthly base allowance | Models | Credit mode | Overrun policy |
|---|---|---|---|---|
| Free | $2 | Your selected lower-cost models | enforce | limit_output |
| Pro | $20 | Your selected Pro models | enforce | limit_output |
The amounts are examples, not Zorveus subscription prices. Your backend looks up the customer's plan, selects its key, and sends the same external user ID. Keep both keys on your server.
If a customer upgrades, select the Pro key. Do not assume a new key resets their usage. The product-user allowance window can include usage across connections. A profile lookup can still reflect the previous connection, so do not reject a Pro request using a stale Free allowance.
A request accidentally omits the user ID
With enforce_if_present, missing attribution bypasses virtual allowance enforcement. With enforce, the request still faces key-level allowance, but it is not attributed to your customer and cannot use that customer's credits.
Validate the external user ID in your backend before sending customer requests. Neither mode repairs missing attribution.
A customer buys extra credits
The customer has a $10 monthly base allowance, has used $8, and holds a $5 credit grant. Assume no active reservations or carried debt:
Base allowance remaining: $10 - $8 = $2
Eligible credits: $5
Total available allowance: $7
A request reserves $3:
$2 from base allowance → $1 from creditsBase allowance is consumed first, then eligible credits by earliest expiry. Credits do not pay the provider. Your wallet or BYOK account must still fund the request. See Credit grants and Billing integration.
A longer answer costs more than the remaining allowance
Suppose an admitted request has $1 of allowance left but its completed response costs $1.50:
limit_outputattempts to keep output within the affordable amount. Unexpected variance is still possible.allow_overrunrecords the extra $0.50 as uncovered spend without future debt.carry_overrun_forwardrecords $0.50 of debt. Later credits or the next base reset repay that debt before restoring spendable allowance.
A subscription renews on the 17th
Use a monthly cap and a stored allowance anchor of July 17. On September 30, the active window is September 17 to October 17:
Jul 17 Aug 17 Sep 17 Sep 30 Oct 17
|---------------|---------------|-----------●---------------|
current allowance windowDo not send the current time as a new anchor on every request. The anchor belongs to the product user within the app, not separately to each plan key. Without an anchor, monthly periods follow UTC calendar months. See Allowance periods and anchors.
Check your setup before launch
- Make an attributed request and confirm the customer appears in usage.
- Test a disallowed model and confirm rejection.
- Test exhausted allowance with your chosen credit mode.
- Add credits and confirm that eligible credits restore allowance.
- Omit the user ID and verify the behavior you intended.
- Test a plan change without assuming usage resets.
- Test allowance exhaustion separately from insufficient wallet funding.
Use Check available allowance for admission checks. The reported amount is a snapshot, not a reservation or a guarantee that the next request fits.