snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/user-guide/billing/capabilities/credits.mdx

@@ -0,0 +1,84 @@
+---
+title: Credits
+description: One simple balance that powers your workflows, AI agents, and AI chat — what a credit is worth, how far it goes, and how to manage it.
+---
+
+## What are credits?
+
+Credits are a single balance that powers everything we run on your behalf that has a real cost: **workflow automations**, **AI agents**, and the **AI chat**. Instead of juggling separate quotas for "automation runs" and "AI tokens," you have one simple balance to keep an eye on.
+
+**1 credit = $1 of usage.** A credit is just a dollar of work, so your balance is easy to reason about — no abstract units to convert.
+
+## How far does a credit go?
+
+Cost scales with the work. Everyday automation and quick AI messages cost a tiny fraction of a credit; large, multi-step AI agent tasks cost more. Here's the rough shape:
+
+| What you do | Roughly costs | What that means |
+|-------------|---------------|-----------------|
+| Run a standard workflow step (search, create, or update records) | $0.0001 | **10,000 runs per credit** |
+| Trigger an app's logic function | $0.0001 + $0.0001 per second of runtime | **Thousands of runs per credit** |
+| Call an external API or run a code node | A small fraction of a credit | Thousands per credit |
+| Send a quick AI chat message or simple AI step | A fraction of a cent | Hundreds per credit |
+| Run a large AI agent task (e.g. "configure 10 workspace objects") | Can run to **~$1 or more** | A few per credit |
+| Run an AI web search | A fixed per-search cost | Hundreds of searches per credit |
+
+<Note>
+For most teams, standard automations are effectively free — you'll only make a noticeable dent in your balance when you lean on AI features or run heavy code nodes. That's by design: the included credits are meant to let you build without watching a meter.
+</Note>
+
+<Note>
+Not every app charges for its runs. Call Recorder, Last Contact and Fathom react to every email, calendar event and recording imported into your workspace, and Slack runs on every Slack event its bot subscribes to, so their logic function runs are free. You are still charged for the metered work they do, such as recorded call minutes or the AI credits behind Slack assistant answers.
+</Note>
+
+## How logic function runs are metered
+
+Logic function pricing mirrors AWS Lambda: a flat charge per invocation plus a duration charge for the time your code actually runs, billed per millisecond.
+
+- **Per invocation**: $0.0001
+- **Per duration**: $0.0001 per second of runtime ($0.0000001 per millisecond)
+
+A typical function that finishes in under a second costs at most double the flat invocation charge. Long-running functions pay for the compute they use: a function running for a full minute adds $0.006, and one hitting the 15-minute timeout adds $0.09. A function that times out is billed for its full elapsed time, just like on AWS.
+
+## How AI usage is metered
+
+When an action calls an AI model, we measure the exact tokens used and price them at **the model provider's published rates**, then convert that dollar amount straight into credits — so what you spend tracks the real cost of the work, not a marked-up internal rate. A short chat message costs a fraction of a cent. A large agent task — say, configuring 10 workspace objects — makes many model calls over a growing context, so it can add up to a dollar or more. You're billed for what you actually use, down to the token.
+
+Cost varies by model: a lightweight model is dramatically cheaper per message than a top-tier reasoning model. You can see the per-action breakdown — including which model was used — in **Settings → Billing**.
+
+## What's included
+
+Every subscription includes credits, and the amount depends on your **billing cycle**, not your plan:
+
+| Billing Cycle | Included Credits | Equivalent Usage |
+|---------------|------------------|------------------|
+| Monthly | 5 / month | ~$5 of usage each month |
+| Yearly | 50 / year | ~$50 of usage each year |
+
+These credits are designed to cover everyday automation comfortably. Five credits cover tens of thousands of standard automation steps or hundreds of quick AI messages — though a handful of large, multi-step agent tasks can use them up faster. You can top up at any time (see below).
+
+## Credit rollover
+
+Unused credits roll over automatically to the next billing period.
+
+- **Cap**: Rollover is capped at one period's full allocation, so you'll never carry over more than your billing cycle provides per period.
+- **Visibility**: When you have rollover credits, they appear as a separate **Rollover Credits** line in **Settings → Billing**, alongside your **Total Available** balance.
+
+## Monitoring usage
+
+Keep track of your balance and where it's going:
+
+1. Go to **Settings → Billing**
+2. See your **remaining credits** and **usage for the current period**
+3. Drill into the breakdown to see which workflows and AI actions are consuming credits — and which models AI actions used
+
+Reviewing this regularly makes it easy to spot a heavy workflow early and decide whether to optimize it or top up.
+
+## Need more credits?
+
+If you run out — or want a buffer before a big automation push — you can buy additional credit packs at any time:
+
+1. Go to **Settings → Billing**
+2. Click the **Increase** button
+3. Select the amount you need and accept the changes
+
+Purchased credits are added to your available balance immediately.

packages/twenty-docs/user-guide/billing/capabilities/pricing-plans.mdx

@@ -0,0 +1,90 @@
+---
+title: Pricing Plans
+description: Learn about Twenty's pricing plans and how to switch between them.
+---
+
+## Overview
+
+Twenty offers flexible pricing to fit teams of all sizes, whether you prefer cloud hosting or self-hosting.
+
+## Cloud Plans
+
+### Pro (Cloud)
+For teams ready to scale:
+- All core CRM features
+- Email and calendar sync
+- Workflows and automations
+- Standard support
+
+<Note>
+Premium features (SSO, row-level permissions, AI usage data and more) are not included in the Pro plan.
+</Note>
+
+### Organization (Cloud)
+For larger teams with advanced needs:
+- Everything in Pro
+- **Premium features**: SSO integration, row-level permissions, AI usage data and more
+- Priority support
+
+## Self-Hosted Plans
+
+### Free (Self-Hosted)
+Host Twenty on your own infrastructure at no cost:
+- All Pro features included
+- Community support via Discord
+- Full control over your data
+
+### Organization (Self-Hosted)
+For teams who need premium features while self-hosting:
+- All Pro features
+- **Premium features**: SSO integration, row-level permissions, AI usage data and more
+- Twenty team support
+- No requirement to publish custom code as open-source before distributing
+
+## Premium Features
+
+Premium features are only available on the Organization plans (Cloud or Self-Hosted):
+- **SSO integration**: Single Sign-On with your identity provider
+- **Row-level permissions**: Fine-grained access control at the record level
+- **AI usage data**: Track AI consumption across the workspace
+- **Audit logs**: Check what each workspace member has been doing
+- **Email campaigns**: Plan which emails should be sent (available soon)
+- **Unlimited workspaces**: Create as many workspaces as you want (self-hosted only)
+- **Private source code**: No requirement to publish changes to a publicly available repository (self-hosted only)
+
+## Switching Plans
+
+### Upgrade to Organization
+1. Go to **Settings → Billing → Plans**
+2. Click **Switch to Organization**
+3. Confirm your upgrade
+
+### Downgrade to Pro
+1. Go to **Settings → Billing → Plans**
+2. Click **Switch to Pro**
+3. Confirm your downgrade
+
+### Switch to Yearly Billing
+1. Go to **Settings → Billing**
+2. Click **Upgrade to Yearly**
+3. Save with annual billing
+
+### Switch to Monthly Billing
+1. Go to **Settings → Billing**
+2. Click **Downgrade to Monthly**
+3. Save with monthly billing
+
+## Get an Organization Key
+
+The Organization (Self-Hosted) plan runs on your own infrastructure. To get started, [install Twenty with Docker Compose](/developers/self-host/capabilities/docker-compose), then follow the steps below to activate your Organization license.
+
+If you already have a self-hosted Twenty instance, you can get your Organization key directly from its settings:
+
+1. Go to **Settings → Admin Panel → Organization**
+
+<img src="/images/user-guide/billing/organization-key.png" alt="Organization key" />
+
+2. Click **Get Organization Key**
+3. When you are redirected to Stripe, enter your payment details and confirm
+4. When your Organization key is displayed, paste it into the Organization settings page and activate the Organization license
+