Billing, Wallets, and Metering
Understand personal and organization wallets, Stripe top-ups, model pricing, reservation settlement, and administrator credit operations.
UnieAI Studio uses USD wallets and fine-grained usage metering. A billable request reserves an estimated amount, settles against actual usage, and records data in the wallet ledger and request logs.
Personal and organization wallets
- A personal workspace uses the current user's personal wallet.
- An organization workspace can use its organization wallet; the billing target follows the request's workspace and authorization context.
- Organization creators and co-editors can perform permitted wallet operations. A regular organization user cannot top up the organization wallet or redeem a gift code into it.
- A
pendinguser cannot use some reward or payment flows.
Internally, balances use micro-USD, where 1,000,000 micro-USD = USD 1, avoiding floating-point loss on small token charges.
| Balance | Meaning |
|---|---|
| Available | Funds available for new requests |
| Reserved | Funds temporarily held for in-flight requests |
| Total | Available plus Reserved |
Stripe top-ups
Studio displays Top up only when the server has STRIPE_SECRET_KEY. Stripe credentials are deployment environment variables, not fields in an Admin Panel Payment Settings page.
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...Configure and validate STRIPE_WEBHOOK_SECRET in production. Never expose the Stripe secret key through a public environment variable, a real value in documentation, or version control.
User top-up flow
The dialog shows an existing pending Stripe order. If payment completed but Studio has not refreshed, use the order synchronization path rather than creating duplicate payments to fix a display delay.
Model pricing
Administrators set public input and output prices per base model under Admin Panel → Models, expressed per million tokens. A typical text-model calculation is:
Cost = (input tokens × input price + output tokens × output price) ÷ 1,000,000Final settlement also depends on the selected model, upstream connection, endpoint, and available usage data. Embedding, VLM, speech, parsing, and internal tool tasks can use their own metering dimensions and should not be estimated solely with chat output tokens.
Reservation and settlement
- Reserve estimates input and maximum output cost. Insufficient funds can return
402 Payment Required. - Capture charges measurable actual usage and returns unused reserved funds to Available.
- Release returns an outstanding reservation when the provider or runtime fails before settlement.
- Ledger records top-ups, usage, gifts, referrals, and administrator adjustments.
Billing response headers
A response with completed billing can include:
| Header | Meaning |
|---|---|
x-unieai-billing-amount-cents | Charge in cents |
x-unieai-billing-amount-micro-usd | Charge in micro-USD |
x-unieai-billing-currency | Billing currency, currently USD |
x-unieai-balance-after-cents | Available balance after settlement, in cents |
x-unieai-balance-after-micro-usd | Available balance after settlement, in micro-USD |
Failed, unbilled, or specific internal flows may omit some headers. Reconcile against the wallet ledger and platform records rather than treating client-captured headers as the accounting source of truth.
Review usage and request cost
- The sidebar wallet shows the current workspace's available balance.
- Usage provides usage and wallet-related records.
- A custom model's Operate → Request logs shows Request ID, tokens, status, latency, and available cost fields.
- Administrators use Admin Panel → Insights for platform rollups and request logs.
Live request logs, usage rollups, wallet capture, and Stripe webhooks can complete at different times. Short-lived differences do not necessarily indicate a duplicate charge.
Administrator credit and rewards
User wallets
Admin Panel → Users → Wallets shows free credit, card top-ups, current balance, and credit history. Setting a target balance records the difference as an administrator adjustment and does not create a Stripe order.
Rewards and gift codes
Admin Panel → Rewards configures signup, inviter and invitee rewards, invite-code limits, advanced referral conditions, and gift codes. A user redeems a code under Plan → Gift, crediting the selected wallet when they have permission to operate it.
Reconciliation guidance
- Correlate request logs and usage ledger entries by Request ID.
- Separate free credit, card top-ups, rewards, usage, and administrator adjustments.
- For Stripe discrepancies, inspect Checkout Session, webhook delivery, and the Studio order state.
- Wait for rollup refresh before comparing Insights totals with per-entry ledgers.
- Do not replace administrator wallet adjustments or formal refunds with direct database balance edits.