> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit Allocation & Transfers

> How credits flow between Account, Instance, and User scope — pooling, manual transfers, auto top-up.

Once credits have been purchased, the next question is **where they sit and how they move**. Pria has a three-tier credit model with explicit rules for pooling, manual transfers, automatic top-up, and audit. This page is the reference for Admins managing those flows.

## Three-tier credit model

Credits live at three levels. Each level has its own balance, its own usage counter, and clear rules for how it can be funded.

<CardGroup cols={3}>
  <Card title="Account" icon="building">
    The master pool for organizations operating multiple Digital Twins. Funded by purchase. Distributes credits down to instances.
  </Card>

  <Card title="Digital Twin (Instance)" icon="layer-group">
    Per-instance balance. Funded by transfer from the parent Account. Drawn down by user interactions when pooling is enabled.
  </Card>

  <Card title="User" icon="user">
    Personal balance attached to each user. Funded by personal purchase or by an Admin awarding bonus credits. Drawn down whenever the user is acting outside a pooled instance.
  </Card>
</CardGroup>

## Credit pooling

Each Digital Twin has a **Pool Credits** flag that decides who pays for member activity.

<AccordionGroup>
  <Accordion title="Pool Credits ON (default)" icon="users">
    All members of the Digital Twin draw from the instance balance. A user with zero personal credits can still chat freely as long as the instance has credits. This is the standard setup for schools, classrooms, and corporate teams.
  </Accordion>

  <Accordion title="Pool Credits OFF" icon="user">
    Each member pays from their **personal** credit balance. The instance balance is not consumed by member chat. Use this when you want the Digital Twin to provide branding and configuration but each user is responsible for their own usage.
  </Accordion>
</AccordionGroup>

Toggle this in **Admin → Configuration** for the Digital Twin.

## Manual transfer

Admins can move credits between an Account and any Digital Twin owned by that Account at any time, in either direction.

<Steps>
  <Step title="Open the Account view">
    Go to **Admin → Account** (or the Accounts section if you manage multiple).
  </Step>

  <Step title="Choose the transfer">
    Select the source (Account or Instance) and destination, then enter the credit amount.
  </Step>

  <Step title="Confirm">
    The balances are updated immediately and a transfer record is written so the move shows up in the audit trail.
  </Step>
</Steps>

<Tip>
  Manual transfers can also pull credits **back** from an instance into the parent Account — useful at the end of a term or when winding down a Digital Twin.
</Tip>

## Automatic top-up — Transfer Modes

Each Account has a **Transfer Credits Mode** that decides whether the platform should automatically refill an instance when its balance drops.

<CardGroup cols={3}>
  <Card title="Never (0)" icon="ban">
    No automatic movement. Admins must initiate every transfer manually. Use this when you want strict per-instance budgeting.
  </Card>

  <Card title="Admin Only (1)" icon="user-shield">
    Automatic refill is disabled, but Admins can still initiate transfers from the Account → Instance manually. Equivalent to "Never" for the auto-refill engine.
  </Card>

  <Card title="Automatic (2)" icon="bolt">
    When an instance with **Pool Credits ON** falls below the low-balance threshold, Pria automatically pulls credits from the parent Account.
  </Card>
</CardGroup>

### How automatic top-up works

When **Transfer Credits Mode = Automatic** and a pooled instance hits the threshold:

<Steps>
  <Step title="Trigger">
    Instance balance falls to **500 credits or below** during an interaction.
  </Step>

  <Step title="Transfer amount">
    Pria pulls **up to 1,000 credits** from the parent Account — capped at whatever the Account currently has available.
  </Step>

  <Step title="Apply">
    The Account is debited, the instance is credited, and a transfer record is written with mode **Auto**.
  </Step>

  <Step title="Notify">
    A confirmation email is sent to the user whose interaction triggered the refill.
  </Step>
</Steps>

<Warning>
  If the parent Account does not have enough credits to refill, the interaction is denied with a "No credits left" message and a critical alert email is sent to the Account manager so they can top the Account up.
</Warning>

## When an instance is deleted

Deleting a Digital Twin does **not** burn its credits. Any remaining balance returns to the parent Account so it can be redistributed to other instances. If the deleted instance had no parent Account, the credits are written off — set up the Account relationship before deletion if you need to preserve them.

## Awarded credits

In addition to pooled funding, Admins can grant **bonus credits** to a specific user inside a Digital Twin. The award is recorded on the user's membership and reflected in their personal credit display.

<CardGroup cols={2}>
  <Card title="Use cases" icon="gift">
    Welcome bonus for early adopters, classroom-specific grants, contest prizes, manual goodwill replacements after a bad experience.
  </Card>

  <Card title="Audit" icon="clock-rotate-left">
    Each award is timestamped and tied to the membership record, so you can audit who gave what and when.
  </Card>
</CardGroup>

To award credits, open the user from **Admin → Users**, edit their membership, and enter the credit amount.

## Trial credits and conversion

New Accounts seed every user with **50 credits / 14 days** of trial access. Trial credits look and behave like purchased credits — they're spent on the same model, just with a clock attached.

<Info>
  When a trial expires or runs out, the user sees a prompt to add credits. Their account remains active; only chat is gated. Any credits subsequently purchased land on the same balance and clear the gate immediately.
</Info>

If you want to extend a trial for a specific user or Account, the Praxis AI team can issue a one-off bonus. Contact the Praxis AI team at [humans@praxis-ai.com](mailto:humans@praxis-ai.com).

## Low-balance alerts

When a pooled instance balance crosses below the configured threshold, Pria sends a courtesy email so the people responsible for the balance hear about it before the lights go out.

<CardGroup cols={2}>
  <Card title="Default threshold" icon="bell">
    **500 credits** — fires once per crossing (no spam if the balance hovers near the line).
  </Card>

  <Card title="Recipients" icon="envelope">
    The user whose interaction triggered the call, and — on the failure path — the Account **manager email**.
  </Card>
</CardGroup>

<Note>
  When Transfer Credits Mode is set to **Automatic** and the parent Account has enough credits, auto-refill handles the top-up before a low-balance email is needed.
</Note>

## Reading the audit trail

Every credit movement that involves an Account writes a transfer record. Together these form the canonical ledger for your organization's credit movements.

| Field        | Meaning                                                               |
| ------------ | --------------------------------------------------------------------- |
| **User**     | Who triggered the transfer (or who was active when auto-refill fired) |
| **Instance** | Destination Digital Twin                                              |
| **Credits**  | Amount moved                                                          |
| **Mode**     | Admin (manual) or Auto (automatic top-up)                             |
| **Date**     | Timestamp                                                             |

You can review transfer history in **Admin → Account → Transfers**. Filter by instance to investigate a specific Digital Twin's funding history.

## User quotas

Beyond pooling and balances, you can cap **how much any single member** is allowed to consume. User quotas protect a shared pool from a runaway user and give each member a predictable budget.

There are two per-user caps:

<CardGroup cols={2}>
  <Card title="Per-user lifetime" icon="infinity">
    The maximum credits a single user may consume in this Digital Twin, total. Once reached, that user is blocked until an Admin raises the cap. Leave blank (or `0`) for no cap.
  </Card>

  <Card title="Per-user 24-hour" icon="clock">
    The maximum credits a single user may consume in any rolling 24-hour window. This cap **recovers automatically** as recent usage ages out — no Admin action needed. Leave blank (or `0`) for no cap.
  </Card>
</CardGroup>

### Account vs. instance precedence

Quotas can be owned at two levels, and the rule is simple — **the Account always wins**:

<AccordionGroup>
  <Accordion title="Account owns the quotas" icon="building">
    When the parent Account has credit caps enabled, those caps apply to every Digital Twin under it. The instance shows the quotas **read-only** — you can see them but not change them. Account-level quotas also include an account-wide cumulative per-user cap that is not available at the instance level.
  </Accordion>

  <Accordion title="Instance self-configures" icon="layer-group">
    When the Account has **not** enabled caps, each Digital Twin can configure its own per-user lifetime and 24-hour quotas. This is the common case for a standalone instance that wants to budget its members.
  </Accordion>
</AccordionGroup>

### Who can edit and where

Quotas are no longer a back-office-only setting — any Admin or manager with the **institutions.edit** entitlement can configure them:

* **Instance Settings → Quotas tab** — the in-product panel for a Digital Twin's own Admins.
* **Admin → Configuration** (institution edit panel) — the same controls in the management console.

When the Account owns the quotas, both surfaces show them read-only with a note explaining that the Account is in charge.

## Per-member consumption

To see how much each member of a Digital Twin has actually consumed, open **Admin → Entitlements** — the membership list includes a **Credit Consumed** column per user. This is the fastest way to spot heavy consumers in a pooled instance before the balance runs low.

## Related

* [Billing & Subscriptions](/mdx/admin-guide/billing) — purchasing credits via Stripe
* [Accounts Overview](/mdx/admin-guide/accounts/overview) — Account structure and ownership
* [Credits](/mdx/user-guide/credits) — user-facing view of credit usage
* [Plans & Credits](/mdx/introduction/plans-and-credits) — package pricing and the credit math