Billing and Credits

The XAI XAPI billing system is designed to provide a transparent, flexible, and controllable consumption management experience.

Credit Balance (CreditBalance)

Each user's balance is not a single value but an array of "credit entries" or "balance cards," known as CreditBalance.

Each card contains the following information:

amount: The initial face value of this card.
balance: The current remaining balance of this card.
granted_at: The time this card was granted (topped up).
expires_at: The expiration time of this card.
reference: A note, such as "Initial Funding" or "Recharge".

Consumption Deduction Rule: The system prioritizes deducting from the card with the earliest expiration date that still has a balance. This "First-In, First-Out" (FIFO) strategy maximizes the efficiency of your funds.

Balance Card Consolidation Strategy: To prevent an excessive number of balance cards from causing management confusion, the system automatically executes a consolidation strategy:

When a user has more than 12 cards, the system will attempt to merge cards that expire on the same day.
If the number of cards is still too high, it will further merge cards with similar expiration dates (e.g., within 60 days).
The expiration date of the new, merged card will be the latest expiration date among the consolidated cards.

Rates and Price Factor (Factor)

The final consumption cost is determined by a simple formula:

Final Consumption = Base Consumption × User Rate (Rates) × Price Factor (Factor)

Base Consumption: This is the original cost calculated based on the official model pricing. For example, the cost for prompt_tokens of gpt-4o.
User Rate (Rates): This is the billing multiplier set by a parent user for their child user.
- The default value is 1, meaning billing is at the standard rate.
- If a parent sets Rates = 1.2 for a child, all of that child's consumption will be multiplied by 1.2. The parent can thus earn a 20% profit margin.
- A child user's Rates cannot be lower than its parent's Rates.
Price Factor (Factor): This is a system-level global price coefficient set by the root administrator for global price adjustments. Regular users typically do not need to be concerned with this.

Top-up and Deduction Logic

When a parent user tops up a child user's account, the fund transfer follows this principle:

Parent's Deduction = Child's Top-up Amount / Child's Rate × Parent's Rate

Example:

Parent User A (Rates=1.0)
Child User B (Rates=1.2)

If User A tops up User B with \$120:

Child User B's CreditBalance increases by \$120.
Parent User A's CreditBalance will be deducted by \$120 / 1.2 × 1.0 = \$100.
The \$20 difference is Parent User A's potential profit, which is realized as Child User B consumes the credit.

When you modify the `Rates` of a child user that already has a balance, the `amount` and `balance` of all cards in their existing `CreditBalance` will be recalculated based on the ratio of the old and new rates. This ensures that their actual purchasing power remains unchanged.

Spending Limits (HardLimit & SoftLimit)

HardLimit: A monthly hard spending cap. API requests will be rejected if this limit is exceeded for the month.
SoftLimit: A monthly soft spending cap. An email notification will be sent if this limit is exceeded for the month.

`HardLimit` and `SoftLimit` are only effective when a user sets `AutoQuota = false`. By default, `AutoQuota = true`, and the system automatically adjusts your spending quota based on your balance, eliminating the need for manual management.