Check available allowance

Use this guide when your backend needs to check a customer's allowance before accepting work or after an allowance rejection.

Read the product-user profile

Create a service key with product-user read permission. Call GET /product-users/by-external-id with your Zorveus app_id and the customer's external_user_id.

from zorveus import AsyncZorveusServiceClient

async def read_allowance(service_key: str, app_id: str, user_id: str):
	service = AsyncZorveusServiceClient(api_key=service_key)
	try:
		profile = await service.product_users.get_by_external_id(
			app_id=app_id,
			external_user_id=user_id,
		)
		return profile
	finally:
		await service.close()

Reuse process-owned clients where your application supports that lifecycle. Do not call a synchronous network client from an async request handler.

Check whether the user has any amount to spend

For an active product user with a known enforced cap, check whether total available allowance is greater than zero. This answers whether the user has any amount to spend, not whether a particular request will fit.

available_to_spend = profile.get_total_available_to_spend_decimal()
can_spend = available_to_spend > 0

# The SDK shortcut returns the same boolean.
can_spend = profile.has_available_allowance()

Use the shortcut when you only need a boolean. Use the amount getter when you also need to display the remaining allowance. These methods use the profile already retrieved; they do not make another API request.

A zero result means no reported spendable allowance. It is not a universal access decision: check the user's status and connection policy, and apply the missing-allowance and uncapped-key rules below.

Interpret the response

For a configured cap, Zorveus calculates:

remaining_base_allowance = max(0, cap_amount - spent_this_period)
available_allowance = remaining_base_allowance + available_credits

For example, a $20 cap with $15 spent and $10 in active credits reports $15 available. Use the returned amount. Do not rebuild the calculation from usage records in your application.

The Python and TypeScript helpers read allowance.available_allowance. If that value is absent, the helpers fall back to credits. If both values are absent, the helpers return zero.

Handle exhaustion and recovery

For an active user under an enforced cap, profile.get_total_available_to_spend_decimal() > 0 or profile.hasAvailableAllowance() permits an inference attempt. A positive balance does not guarantee funding for that request. The gateway still checks estimated cost, reservations, and other limits.

If the gateway rejects a request for allowance, record an observed exhausted state and return a clear failure to the user. Recheck the profile before rejecting later requests from that state. Credits or a new allowance period can restore access without a local billing event.

A missing profile is not an exhausted profile. Inline attribution creates new users on their first inference request. Handle lookup failures separately from allowance failures.

The profile uses an active direct product-user cap, or the user's last applicable connection cap. If a plan change selects a different key, do not reject the new request using an allowance from the old connection.

Continue with allowance periods, credit grants, and webhook processing.