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
+

packages/twenty-docs/user-guide/billing/how-tos/billing-faq.mdx

@@ -0,0 +1,105 @@
+---
+title: Billing FAQ
+description: Frequently asked questions about Twenty pricing and billing.
+---
+
+## Pricing
+
+<AccordionGroup>
+<Accordion title="Can I use Twenty for free while self-hosting?">
+Yes, you can use Twenty for free while self-hosting. You will get access to everything included in the Pro (Cloud) plan, except the support from our core team. Support is accessible via our Discord community.
+
+If you want to self-host and need the Premium features (SSO, row-level permissions and more), you can choose the paid Organization (Self-Hosted) license. This also includes support from the Twenty team and removes the requirement to publish custom code as open-source before distributing.
+</Accordion>
+
+<Accordion title="What are the 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)
+</Accordion>
+
+<Accordion title="Are the Cloud and Self-Hosted Organization plans the same?">
+They offer the same premium features. However, a cloud subscription cannot be used for self-hosted deployments. Self-hosted requires an Organization key.
+</Accordion>
+
+<Accordion title="Do you offer free seats for view-only users?">
+We do not offer free seats. Pricing is per user and each user needs a license to access Twenty.
+</Accordion>
+
+<Accordion title="Where can I switch my subscription to the Organization plan?">
+You can do so under `Settings → Billing → Plans`. Then click on `Switch to Organization`.
+</Accordion>
+
+<Accordion title="Where can I switch my subscription to the Pro plan?">
+You can do so under `Settings → Billing → Plans`. Then click on `Switch to Pro`.
+</Accordion>
+
+<Accordion title="Where can I switch my subscription to yearly?">
+You can do so under `Settings → Billing`. Then click on `Upgrade to yearly`.
+</Accordion>
+
+<Accordion title="Where can I switch my subscription to monthly?">
+You can do so under `Settings → Billing`. Then click on `Downgrade to monthly`.
+</Accordion>
+
+<Accordion title="Where can I see my credit usage?">
+You will find this under `Settings → Billing`.
+</Accordion>
+
+<Accordion title="How many workflow credits do we have?">
+The number of credits depends on your billing cycle, not your plan:
+- **Monthly subscriptions**: 5 credits per month
+- **Yearly subscriptions**: 50 credits per year
+</Accordion>
+
+<Accordion title="How does workflow credit consumption work?">
+Each workflow action consumes credits based on its complexity:
+- **Basic internal operations** (such as search, update, or create records) consume very few credits
+- **More complex operations** like code nodes and requests to external services consume more credits
+- **AI prompts** also consume more credits based on usage
+- **Apps** also consume more credits similarly to code nodes
+
+Credits are deducted in real-time when workflows or apps execute. You can monitor your usage in **Settings → Billing** to track consumption and remaining credits.
+</Accordion>
+
+<Accordion title="Can I buy more workflow credits?">
+You can buy additional credits under `Settings → Billing`.
+</Accordion>
+
+<Accordion title="Can I buy more workflow credits only for 1 month?">
+Yes, go to `Settings → Billing`, click the `Increase` button, choose how many credits you want, and confirm. They'll be applied for the current billing period. Then click the `Increase` button again, change the value back to the original, and confirm — the downgrade will be applied starting the next billing period.
+</Accordion>
+</AccordionGroup>
+
+## Billing
+
+<AccordionGroup>
+<Accordion title="Where can I manage the Billing details?">
+You can do so under `Settings → Billing`.
+</Accordion>
+
+<Accordion title="Where can I update my payment method?">
+You can do so under `Settings → Billing`. Then click on `View billing details`. You'll be able to add a new payment method there.
+</Accordion>
+
+<Accordion title="Where can I update my billing information?">
+You can do so under `Settings → Billing`. Then click on `View billing details`. You'll be able to edit the billing information there.
+</Accordion>
+
+<Accordion title="Where can I access my invoices?">
+You can do so under `Settings → Billing`. Then click on `View billing details`. You'll see all your invoices at the bottom of the screen.
+</Accordion>
+
+<Accordion title="Why are my seats different from the number of users in my workspace?">
+Workspace seat counts are synchronized with the payment system every 6 hours; invoices are adjusted based on the difference.
+</Accordion>
+
+<Accordion title="Why did I get an invoice for a new workspace member?">
+When a new workspace member is added to the workspace, an invoice is sent to cover the difference. When a workspace member is removed, the change is applied in the next standard monthly/yearly invoice.
+</Accordion>
+</AccordionGroup>

packages/twenty-docs/user-guide/billing/overview.mdx

@@ -0,0 +1,39 @@
+---
+title: Billing
+description: Understand Twenty pricing and manage your subscription.
+---
+
+Twenty offers flexible pricing plans to fit your team's needs. Manage your subscription, track workflow credits, and access invoices all from **Settings → Billing**.
+
+## What's in this section
+
+<CardGroup cols={2}>
+  <Card title="Pricing Plans" icon="tags" href="/user-guide/billing/capabilities/pricing-plans">
+    Learn about Twenty's pricing plans and what's included.
+  </Card>
+  <Card title="FAQ" icon="circle-question" href="/user-guide/billing/how-tos/billing-faq">
+    Frequently asked questions about pricing and billing.
+  </Card>
+</CardGroup>
+
+## At a glance
+
+| Plan  | Key Features |
+|------|--------------|
+| **Free (Self-Hosted)** | All Pro features, community support |
+| **Pro (Cloud)** | Everything apart from the Premium features (SSO, row-level permissions and more), standard support |
+| **Organization (Cloud)** | All from Pro + the Premium features (SSO, row-level permissions and more), priority support |
+| **Organization (Self-Hosted)** | All from Pro + the Premium features (SSO, row-level permissions and more), Twenty team support, not required to publish your custom code as open-source before distributing |
+
+## Quick answers
+
+**Where do I manage billing?**
+Go to **Settings → Billing** to view your plan, update payment methods, and access invoices.
+
+**Can I use Twenty for free?**
+Yes! Self-host Twenty and get all Pro features at no cost.
+
+**How do I upgrade?**
+Go to **Settings → Billing** and click **Switch to Organization** or **Switch to Yearly**.
+
+For more questions, see the [Billing FAQ](/user-guide/billing/how-tos/billing-faq).