Updates docs for new pricing and terminology changes (#3052)

SarahSoutoul · alexisintech · web-flow · commit 345af981e979 · 2026-02-09T14:48:49.000-05:00
Co-authored-by: Alexis Aguilar &lt;98043211+alexisintech@users.noreply.github.com&gt;
diff --git a/docs/_partials/user-impersonation-callout.mdx b/docs/_partials/user-impersonation-callout.mdx
@@ -0,0 +1,2 @@
+> [!IMPORTANT]
+> You can perform up to **5 user impersonations per month for free**. To increase this limit, refer to the [pricing page](/pricing){{ target: _blank }}.
diff --git a/docs/_tooltips/mru.mdx b/docs/_tooltips/mru.mdx
@@ -0,0 +1 @@
+A **Monthly Retained User (MRU)** is a user who visits your app in a given month at least **one day after signing up**. This free day avoids unwelcome fees from users who don't activate.
diff --git a/docs/guides/development/custom-flows/account-updates/user-impersonation.mdx b/docs/guides/development/custom-flows/account-updates/user-impersonation.mdx
@@ -9,6 +9,8 @@ description: Learn how to build a custom flow using the Clerk API that handles u
 
 This guide will walk you through how to build a custom flow that handles user impersonation.
 
+<Include src="_partials/user-impersonation-callout" />
+
 <Tabs items={["Next.js", "Expo"]}>
   <Tab>
     The following example builds a dashboard that is only accessible to users with the `org:admin:impersonate` permission. To use this example, you must first [create the custom `org:admin:impersonate` permission](/docs/guides/organizations/control-access/roles-and-permissions#custom-permissions). Or you can modify the [authorization checks](!authorization-check) to fit your use case.
diff --git a/docs/guides/development/migrating/overview.mdx b/docs/guides/development/migrating/overview.mdx
@@ -55,7 +55,9 @@ With a trickle migration, you are slowly migrating your users from your previous
 Because you'll need both systems available when doing a gradual migration, there is naturally additional short-term costs related to having both running systems at the same time.
 
 > [!NOTE]
-> It's important to note that Clerk only charges by _Monthly Active Users_ and never based on your total number of Users in the user table – so during this period you'll only be charged for users who create an active session within Clerk. Head to our [pricing page](/pricing) to get the full details on how Clerk charges.
+> It's important to note that Clerk only charges by [Monthly Retained Users (MRUs)](!mru) and never based on your total number of users in the user table.
+>
+> Free plans have a limit of 50,000 MRUs per application, and once you exceed this limit you will be required to upgrade to the Pro plan. Head to our [pricing page](/pricing) to get the full details on how Clerk charges.
 
 #### Determining the appropriate length of time
 
diff --git a/docs/guides/organizations/configure.mdx b/docs/guides/organizations/configure.mdx
@@ -27,7 +27,7 @@ To enable Organizations:
 1. In the modal, choose between **Membership required** or **Membership optional** based on your decision above.
 1. Select **Enable**.
 
-Clerk measures Organizations by Monthly Active Organizations (MAOs). Refer to the [overview page](/docs/guides/organizations/overview#how-do-organizations-work) for pricing details and limits.
+Clerk measures Organizations by Monthly Retained Organizations (MROs). Refer to the [overview page](/docs/guides/organizations/overview#how-do-organizations-work) for pricing details and limits.
 
 ## Organization settings
 
@@ -43,8 +43,8 @@ To change the membership limit for all Organizations in your application:
 
 1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page.
 1. In the **Default membership limit** section, update the membership limit.
-   - **Free plan**: Allows a maximum of 5 members in an Organization
-   - **Pro plan**: Allows unlimited members in an Organization
+   - **Without B2B Authentication add-on**: Allows a maximum of 5 members in an Organization
+   - **With B2B Authentication add-on**: Allows unlimited members in an Organization
 
 To change the membership limit for a specific Organization:
 
diff --git a/docs/guides/organizations/create-and-manage.mdx b/docs/guides/organizations/create-and-manage.mdx
@@ -9,7 +9,7 @@ Organizations can be created and managed either **in the Clerk Dashboard** or **
 
 ## Create an Organization
 
-Organizations can be created in the Clerk Dashboard or in your application. The number of Organizations you can create depends on your [Monthly Active Organization (MAO) limits](/docs/guides/organizations/overview#how-do-organizations-work).
+Organizations can be created in the Clerk Dashboard or in your application. The number of Organizations you can create depends on your [Monthly Retained Organization (MRO) limits](/docs/guides/organizations/overview#how-do-organizations-work).
 
 ### Create an Organization in the Clerk Dashboard
 
diff --git a/docs/guides/organizations/overview.mdx b/docs/guides/organizations/overview.mdx
@@ -20,7 +20,7 @@ Organizations live within your Clerk application. Each application can contain m
 
 The Organization that a user is currently viewing is called the **Active Organization**. The Active Organization determines which Organization-specific data the user can access and which Role and related Permissions they have within the Organization.
 
-Clerk measures Organization usage through **Monthly Active Organizations (MAOs)**. An MAO is an Organization with at least two users that have signed in that month, where at least one has interacted with the Organization during the current billing cycle. Free plans include up to 50 MAOs in development and 100 in production. Pro plans offer unlimited development MAOs and start at 100 free production MAOs, then $1 per additional MAO. Refer to the [pricing page](/pricing){{ target: '_blank' }} for complete details.
+Clerk measures Organization usage through **Monthly Retained Organizations (MROs)**. An MRO is an Organization with at least two members, where at least one member is a [Monthly Retained User](!mru). Free plans include up to 50 MROs in development and 100 in production. To increase these limits, refer to the [pricing page](/pricing){{ target: '_blank' }}.
 
 ## Core workflow
 
diff --git a/docs/guides/users/impersonation.mdx b/docs/guides/users/impersonation.mdx
@@ -5,6 +5,8 @@ description: Clerk's user impersonation feature allows you to sign in as differe
 
 Clerk's user impersonation feature allows you to sign in to your application as one of your users, enabling you to directly reproduce and remedy any issues they're experiencing. It's a helpful feature for customer support and debugging.
 
+<Include src="_partials/user-impersonation-callout" />
+
 ## Impersonate a user
 
 The easiest way to impersonate a user is from the [**Users**](https://dashboard.clerk.com/~/users) page in the Clerk Dashboard.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+> [!IMPORTANT]`
	`2`	`+> You can perform up to 5 user impersonations per month for free. To increase this limit, refer to the [pricing page](/pricing){{ target: _blank }}.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+A Monthly Retained User (MRU) is a user who visits your app in a given month at least one day after signing up. This free day avoids unwelcome fees from users who don't activate.`