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

# Billing & credits overview

> How ModuleX bills in one picture: your plan gives a monthly credit allowance, credits meter managed usage, a prepaid wallet covers overage, and a usage gate enforces it all. Managed usage costs credits; bring-your-own-key usage does not.

export const MediaEmbed = ({id, type = 'screenshot', caption = '', ext, ratio = '16 / 9'}) => {
  const isVideo = type === 'video' || type === 'app_video';
  const resolvedExt = ext || (isVideo ? 'mp4' : type === 'screenshot' ? 'webp' : 'svg');
  const src = 'https://media.modulex.dev/' + id + '.' + resolvedExt;
  const [status, setStatus] = useState('loading');
  const [isDev, setIsDev] = useState(false);
  const [inView, setInView] = useState(false);
  const boxRef = useRef(null);
  useEffect(() => {
    if (typeof window === 'undefined') return;
    const h = window.location.hostname;
    setIsDev(h === 'localhost' || h === '127.0.0.1' || h.endsWith('.mintlify.app'));
  }, []);
  useEffect(() => {
    if (inView) return;
    if (typeof IntersectionObserver === 'undefined') {
      setInView(true);
      return;
    }
    const el = boxRef.current;
    if (!el) return;
    const io = new IntersectionObserver(entries => {
      if (entries.some(e => e.isIntersecting)) {
        setInView(true);
        io.disconnect();
      }
    }, {
      rootMargin: '300px'
    });
    io.observe(el);
    return () => io.disconnect();
  }, [inView]);
  if (status === 'missing') {
    if (!isDev) return null;
    return <div style={{
      display: 'flex',
      flexDirection: 'column',
      justifyContent: 'center',
      gap: '0.4rem',
      padding: '1rem 1.25rem',
      margin: '1.25rem 0',
      width: '100%',
      aspectRatio: ratio,
      boxSizing: 'border-box',
      border: '1px dashed rgba(128,128,128,0.45)',
      borderRadius: '0.75rem',
      background: 'rgba(128,128,128,0.06)',
      color: 'currentColor',
      fontSize: '0.85rem',
      lineHeight: 1.45
    }}>
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '0.5rem',
      opacity: 0.75
    }}>
          <span aria-hidden="true">🎬</span>
          <code style={{
      fontSize: '0.75rem'
    }}>{id}</code>
          <span style={{
      fontSize: '0.65rem',
      textTransform: 'uppercase',
      letterSpacing: '0.04em',
      padding: '0.1rem 0.4rem',
      borderRadius: '0.4rem',
      background: 'rgba(128,128,128,0.18)'
    }}>
            {type}
          </span>
        </div>
        <div style={{
      opacity: 0.9
    }}>{caption || 'Media not uploaded yet.'}</div>
        <div style={{
      fontSize: '0.7rem',
      opacity: 0.5
    }}>
          Upload to R2 as <code>{id}.{resolvedExt}</code> — preview only, hidden in production.
        </div>
      </div>;
  }
  const mediaStyle = {
    display: status === 'loaded' ? 'block' : 'none',
    width: '100%',
    height: 'auto',
    borderRadius: '0.75rem'
  };
  const media = isVideo ? <video src={inView ? src : undefined} autoPlay loop muted playsInline preload="metadata" onLoadedData={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} /> : <img src={inView ? src : undefined} alt={caption} onLoad={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} />;
  return <figure style={{
    margin: '1.25rem 0'
  }}>
      <div ref={boxRef} style={status === 'loaded' ? {
    width: '100%'
  } : {
    width: '100%',
    aspectRatio: ratio,
    borderRadius: '0.75rem',
    background: 'rgba(128,128,128,0.06)'
  }}>
        {media}
      </div>
      {status === 'loaded' && caption ? <figcaption style={{
    marginTop: '0.5rem',
    textAlign: 'center',
    fontSize: '0.85rem',
    opacity: 0.7
  }}>
          {caption}
        </figcaption> : null}
    </figure>;
};

ModuleX billing fits into four ideas. Your **plan** gives your [organization](/concepts/organizations-roles) a monthly **credit** allowance. Credits meter the usage ModuleX runs for you. When the allowance runs out, a prepaid **wallet** can cover the difference. And a **usage gate** checks all of this before each piece of managed work begins.

This page gives you the whole picture at a glance. Each part links to a page with the full detail when you need it.

## The four parts of billing

<CardGroup cols={2}>
  <Card title="Plans" icon="layer-group" href="/billing/plans">
    Free, Pro, Max, and Enterprise. Your plan sets your monthly credit allowance and your limits.
  </Card>

  <Card title="Credits" icon="coins" href="/billing/credits">
    The unit ModuleX bills in. Credits meter managed runs, tool calls, model usage, and knowledge retrieval.
  </Card>

  <Card title="Wallet" icon="wallet" href="/billing/wallet">
    A prepaid balance that covers usage beyond your plan allowance, with manual top-ups and auto top-up.
  </Card>

  <Card title="Usage gate" icon="shield-check" href="/billing/usage-gating">
    The check that runs before each piece of managed work, so you are never billed for work that could not be admitted.
  </Card>
</CardGroup>

<MediaEmbed id="MX-MEDIA-1240" type="image" caption={"A single diagram showing how a plan, credits, the wallet, and the usage gate fit together for one organization."} />

## How it works in one paragraph

Managed usage is priced in **credits**, where \*\*100 credits cost $1.00** (one credit is $0.01). Each [plan](/billing/plans) gives your organization a monthly credit allowance. As you use ModuleX, that allowance is drawn down. If you are on a paid plan and you turn on overage, work that goes beyond the allowance is paid for from your prepaid [wallet](/billing/wallet). Before any managed run, tool call, model call, or knowledge retrieval starts, the [usage gate](/billing/usage-gating) confirms you have budget — so you are never charged for work that was not admitted.

## Credits at a glance

A **credit** is the single unit ModuleX bills in for managed usage. It maps to money at a fixed rate, so a credit balance is easy to reason about.

<CardGroup cols={3}>
  <Card title="100 credits = $1.00" icon="dollar-sign">
    Credits convert to dollars at a fixed rate of \$0.01 per credit, the same rate for your plan allowance and your wallet.
  </Card>

  <Card title="One run = one credit" icon="circle-play">
    A single workflow run or one Assistant turn costs one credit, separate from any model or tool usage inside it.
  </Card>

  <Card title="Usage is metered" icon="gauge">
    Model usage is metered by tokens, tool calls have a base cost, and each knowledge retrieval or document ingest costs a credit.
  </Card>
</CardGroup>

For exactly what consumes credits and how token usage is converted, see [Credits & metering](/billing/credits).

## Plans and your allowance

Your plan decides your monthly credit allowance and your limits. The credit allowances below are the values ModuleX runs against.

| Plan           | Monthly credit allowance               | Best for                                             |
| -------------- | -------------------------------------- | ---------------------------------------------------- |
| **Free**       | 300 credits (one-time, to get started) | Trying ModuleX on your own                           |
| **Pro**        | 5,000 credits per month                | Individuals and small teams                          |
| **Max**        | 20,000 credits per month               | Heavy or team-wide usage                             |
| **Enterprise** | Custom                                 | Organizations that need scale, SSO, and self-hosting |

<Note>
  At the $0.01-per-credit rate, Pro's 5,000 credits is worth $50 of managed usage and Max's 20,000 credits is worth \$200. The Free allowance is a one-time grant to get you started, not a recurring monthly reset.
</Note>

<Warning>
  ModuleX's marketing site and its backend pricing configuration currently list **two different annual prices** for Pro and Max, and which one is authoritative is being confirmed. Always check the price shown at checkout before you subscribe to an annual plan. The credit allowances above are not affected by this — they are the same everywhere. See [Plans & pricing](/billing/plans) for the full comparison and both annual figures.
</Warning>

## Managed vs bring-your-own-key (BYOK)

ModuleX gives you two ways to use models, tools, and knowledge. The difference is who runs the work and who bills for it.

<CardGroup cols={2}>
  <Card title="Managed usage" icon="server">
    ModuleX provisions the model, tool, or vector store for you. This usage is **metered in credits** against your plan allowance and wallet. It is the default when you do not connect your own provider.
  </Card>

  <Card title="Bring your own key (BYOK)" icon="key">
    You connect your own provider account. That usage is billed directly by the provider with **no ModuleX credits charged** — ModuleX records it for analytics only.
  </Card>
</CardGroup>

<Note>
  A simple way to remember it: **if ModuleX runs it, it costs credits; if your own key runs it, it does not.** You can mix the two — for example, use a ModuleX-managed model in one workflow and your own [OpenAI](/integrations/llm-providers/openai) or [Anthropic](/integrations/llm-providers/anthropic) key in another. Connecting your own providers is covered in [LLM providers](/integrations/llm-providers/overview) and [Knowledge providers](/integrations/knowledge-providers/overview).
</Note>

## The wallet: covering work beyond your allowance

When your monthly allowance is used up, a paid organization can keep working by spending down a prepaid **wallet**.

<Steps>
  <Step title="Turn on overage">
    On a paid plan, an owner or admin enables overage for the organization. Until it is on, work stops once the allowance is empty rather than spending the wallet.
  </Step>

  <Step title="Top up the wallet">
    Add a prepaid balance. A $10 top-up adds 1,000 credits, at the same $0.01-per-credit rate as your plan.
  </Step>

  <Step title="Let auto top-up keep it funded (optional)">
    Auto top-up can refill the wallet automatically when the balance gets low, so usage is not interrupted.
  </Step>
</Steps>

<Note>
  Overage and the wallet are paid-plan features. The wallet only comes into play **after** your plan allowance is exhausted — your monthly credits are always spent first. The exact top-up limits, the auto top-up defaults, and how a balance is reconciled are in [Wallet & top-ups](/billing/wallet).
</Note>

## The usage gate: checked before work begins

Every piece of managed work passes through a **usage gate** before it starts. The gate confirms your organization can pay for the work — checking your plan allowance, your wallet, and your limits — and only then does the work run. This is why you are never billed for work that could not be admitted.

The gate applies to ModuleX's managed-usage surfaces:

<CardGroup cols={2}>
  <Card title="Running workflows" icon="diagram-project" href="/workflow-builder/execution/running">
    Each managed workflow run is checked and metered before it executes.
  </Card>

  <Card title="The AI Composer" icon="wand-magic-sparkles" href="/concepts/ai-composer">
    Turning plain English into a workflow runs through the gate per turn.
  </Card>

  <Card title="The Assistant" icon="robot" href="/concepts/assistant">
    Each Assistant turn is admitted and metered before the agent acts.
  </Card>

  <Card title="Managed knowledge" icon="book-open" href="/platform/knowledge/managed">
    Retrieval and document ingest on ModuleX-managed knowledge are metered.
  </Card>
</CardGroup>

<Warning>
  When the gate declines work, the request comes back with a clear status: a **402** if your credits are exhausted or your wallet cannot cover it, a **403** if you have hit a plan quota, or a **429** if you have hit a rate limit. Everyday actions that do not run managed work — such as browsing your workflows or editing organization settings — are **not** gated and never return these billing responses. For the full response shapes and how to handle them, see [Usage gating & limits](/billing/usage-gating) and [Errors & status codes](/api-reference/errors).
</Warning>

## Where billing lives

Billing belongs to the **organization**, not to an individual. The plan, the credit allowance, and the wallet are shared by everyone in the organization, and every run is metered against the organization it runs in. Managing the plan and the wallet is reserved for owners and admins — see [Organizations, roles & membership](/concepts/organizations-roles).

## Keep going

<CardGroup cols={2}>
  <Card title="Plans & pricing" icon="layer-group" href="/billing/plans">
    Compare Free, Pro, Max, and Enterprise — allowances, limits, and pricing.
  </Card>

  <Card title="Credits & metering" icon="coins" href="/billing/credits">
    Exactly what a credit is and what consumes credits.
  </Card>

  <Card title="Usage gating & limits" icon="shield-check" href="/billing/usage-gating">
    The gate and its 402, 403, and 429 responses, in detail.
  </Card>

  <Card title="Wallet & top-ups" icon="wallet" href="/billing/wallet">
    The prepaid wallet, manual top-ups, and auto top-up.
  </Card>

  <Card title="Credits & the billing model" icon="circle-info" href="/concepts/credits-billing">
    The concept behind it all — how managed usage is metered and where the gate applies.
  </Card>

  <Card title="Trials & dunning" icon="hourglass-half" href="/billing/trials-dunning">
    Free trials, grace periods, and what happens if a payment fails.
  </Card>
</CardGroup>