Skip to main content

Clerk Changelog

Five new React hooks that give developers complete control over building custom billing experiences, from plan selection to checkout completion.

Building on our recent billing button components, we're introducing a set of React hooks that enable you to build fully custom billing flows. These hooks provide direct access to billing data and functionality, giving you complete control over the user experience.

Control the checkout flow

You can now build your own checkout flow with Clerk Billing for both users and organizations. Leverage the useCheckout() hook to create a custom checkout experience. Choose between prompting users to enter their payment details or pay with a saved payment method.

Below you can see a simple example of a custom checkout flow that is using the <PaymentElement /> component where users can enter their payment details.

'use client'
import {
  CheckoutProvider,
  useCheckout,
  PaymentElementProvider,
  PaymentElement,
  usePaymentElement,
} from '@clerk/nextjs/experimental'

export default function CheckoutPage() {
  return (
    <CheckoutProvider for="user" planId="cplan_xxx" planPeriod="month">
      <CustomCheckout />
    </CheckoutProvider>
  )
}

function CustomCheckout() {
  const { checkout } = useCheckout()
  const { plan } = checkout

  return (
    <div className="checkout-container">
      <span>Subscribe to {plan.name}</span>

      <PaymentElementProvider checkout={checkout}>
        <PaymentSection />
      </PaymentElementProvider>
    </div>
  )
}

function PaymentSection() {
  const { checkout } = useCheckout()
  const { isConfirming, confirm } = checkout
  const { isFormReady, submit } = usePaymentElement()
  const isButtonDisabled = !isFormReady || isConfirming

  const subscribe = async () => {
    const { data } = await submit()
    await confirm(data)
  }

  return (
    <>
      <PaymentElement fallback={<div>Loading payment element...</div>} />
      <button disabled={isButtonDisabled} onClick={subscribe}>
        {isConfirming ? 'Processing...' : 'Complete Purchase'}
      </button>
    </>
  )
}

To enable users to pay with a saved payment method, you can use the usePaymentMethods() hook to display a list of saved payment methods.

import { usePaymentMethods } from '@clerk/nextjs/experimental'

function PaymentMethodSelector() {
  const { data: methods, isLoading } = usePaymentMethods()

  return (
    <div className="payment-methods">
      <h3>Select Payment Method</h3>
      {methods?.map((method) => (
        <button key={method.id} className="payment-method-option">
          {method.cardType} ending in {method.last4}
        </button>
      ))}
    </div>
  )
}

Design your own pricing table

usePlans() fetches your instance's configured plans, perfect for building custom pricing tables or plan selection interfaces.

import { usePlans } from '@clerk/nextjs/experimental'

function CustomPricingTable() {
  const { data: plans, isLoading } = usePlans({
    for: 'user',
    pageSize: 10,
  })

  if (isLoading) return <div>Loading plans...</div>

  return (
    <div className="pricing-grid">
      {plans?.map((plan) => (
        <div key={plan.id} className="plan-card">
          <h3>{plan.name}</h3>
          <p>{plan.description}</p>
          <p>
            {plan.currency} {plan.amountFormatted}/month
          </p>
          <ul>
            {plan.features.map((feature) => (
              <li key={feature.id}>{feature.name}</li>
            ))}
          </ul>
        </div>
      ))}
    </div>
  )
}

Display subscription details

Usage of the useSubscription hook

Access current subscription details to build custom account management interfaces and display billing status.

import { useSubscription } from '@clerk/nextjs/experimental'

function SubscriptionStatus() {
  const { data: subscription, isLoading } = useSubscription()

  if (!subscription) return <div>No active subscription</div>

  return (
    <div className="subscription-status">
      <h3>Current Plan: {subscription.plan.name}</h3>
      <p>Status: {subscription.status}</p>
      <p>Next billing: {subscription.nextPayment.date.toLocaleDateString()}</p>
    </div>
  )
}

Note

These hooks are currently exported as experimental while we continue to refine the API based on developer feedback.

Contributor
Pantelis Eleftheriadis

Share this article

Organization permissions are now unlimited

Category
Dashboard
Published

Create unlimited permissions within organizations for enhanced flexibility and control over resource access.

Previously, organizations were limited to a maximum of 50 permissions, which could be restrictive for complex applications requiring granular access control. This limitation often forced developers to consolidate permissions or find workarounds when building sophisticated authorization systems.

Organizations can now have unlimited permissions, giving you complete flexibility to model your application's access control exactly as needed. Whether you're building a complex enterprise application with hundreds of different resource types or a multi-tenant SaaS with intricate permission structures, you're no longer constrained by arbitrary limits.

Contributor
Lamone Armstrong

Share this article

Automatic regional failover now protects Clerk from major infrastructure disruptions

We’ve made significant improvements to Clerk’s infrastructure to better withstand outages and regional disruptions.

As part of our ongoing commitment to reliability and in response to the June 26th service outage, we’ve implemented automatic regional failover for critical parts of our system. This enhancement ensures that, in the event of a major disruption in one region, traffic is rerouted to healthy infrastructure in real time, without any manual intervention. This change reduces the risk of widespread service impact during provider-level incidents and brings us closer to our long-term goal of platform-level fault tolerance.

We’re not stopping here. We’re actively working on improving the resilience of stateful systems and are exploring strategies for increased redundancy across providers.

Our goal is simple: to keep Clerk highly available and dependable even when the unexpected happens.

Contributors
Agis Anastasopoulos
Alex Ntousias
Alexis Polyzos
Georgios Komninos

Share this article

MCP Server Support for Express

Category
Product
Published

Build an MCP service into your application with Clerk and Express.js in 5 minutes

We're excited to announce server-side support for the Model Context Protocol (MCP) in Express.js applications using Clerk authentication. This enables your users to securely grant AI applications like Claude, Cursor, and others access to their data within your app.

Getting Started

Setting up an MCP server in your Express app is straightforward with Clerk's modern OAuth provider implementation. Here's the entire implementation, within a single file in about 50 lines of code:

import 'dotenv/config'
import { clerkClient, clerkMiddleware } from '@clerk/express'
import {
  mcpAuthClerk,
  protectedResourceHandlerClerk,
  streamableHttpHandler,
  authServerMetadataHandlerClerk,
} from '@clerk/mcp-tools/express'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import cors from 'cors'
import express from 'express'

const app = express()
app.use(cors({ exposedHeaders: ['WWW-Authenticate'] }))
app.use(clerkMiddleware())
app.use(express.json())

const server = new McpServer({
  name: 'test-server',
  version: '0.0.1',
})

server.tool(
  'get_clerk_user_data',
  'Gets data about the Clerk user that authorized this request',
  {},
  async (_, { authInfo }) => {
    const userId = authInfo!.extra!.userId! as string
    const userData = await clerkClient.users.getUser(userId)

    return {
      content: [{ type: 'text', text: JSON.stringify(userData) }],
    }
  },
)

app.post('/mcp', mcpAuthClerk, streamableHttpHandler(server))

app.get(
  '/.well-known/oauth-protected-resource/mcp',
  protectedResourceHandlerClerk({ scopes_supported: ['email', 'profile'] }),
)

app.get('/.well-known/oauth-authorization-server', authServerMetadataHandlerClerk)

app.listen(3000, () => {
  console.log('Server running on port 3000')
})

A full reference implementation is available and open source on GitHub if you'd like to test it out.

Note

OAuth tokens are machine tokens. Machine token usage is free during our public beta period but will be subject to pricing once generally available. Pricing is expected to be competitive and below market averages.

Connecting AI Tools

Once your MCP server is running, connecting it to AI tools is straightforward. For example, with Cursor, you can add this configuration:

{
  "mcpServers": {
    "clerk-mcp-example": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

That's it — no stdio tools, command execution, or additional software installation required. Just provide the URL and authentication is handled automatically through the MCP protocol.

For a complete guide on testing your MCP server with various AI clients, check out our MCP client integration guide.

What's Next

Clerk's OAuth provider offers support for the MCP protocol with any framework, but MCP is still a new standard, it's changing quickly, and support and implementation can vary across different clients and frameworks, which often makes implementation tricky.

For this reason, we are creating end-to-end working examples and helpful utilities for each framework that we plan to steadily release over time. We recently released an MCP implementation for Next.js, and we will continue to roll out examples and guides for other frameworks in the coming months.

We're excited to see what new AI-powered experiences you'll build with MCP and Clerk. If you have feedback or questions, we'd love to hear from you!

Contributor
Jeff Escalante

Share this article

New simple theme for easier customization

Category
Product
Published

A minimal theme with stripped-down styling that provides a clean foundation for custom designs.

You can now opt into a simpler theme for customizing Clerk components. This theme is a stripped down version of the default Clerk theme that removes advanced styling techniques, making it easier to apply your own custom styles without complex overrides.

To use the simple theme, set theme to simple:

<ClerkProvider
  appearance={{
    theme: 'simple',
  }}
/>

To learn more about themes and how to customize Clerk components, check out our theme documentation.

Contributor
Alex Carpenter

Share this article

Immediately terminate subscriptions and revoke feature access with the new End button in the Dashboard

We've added a new End button to subscription management in the Clerk Dashboard, giving you the ability to immediately end subscriptions and revoke user access to features.

Previously, you could only Cancel subscriptions, which would stop recurring charges but allow users to retain access until the end of their current billing cycle. The new End button goes further by immediately terminating the subscription and revoking access to all associated features.

This is particularly useful when processing refunds - you can immediately remove access to prevent further usage after issuing a refund.

You can find the End button alongside the existing Cancel button in the subscription details page of any user or organization in the Clerk Dashboard. The Cancel button remains available for standard subscription cancellations where you want to honor the user's paid period.

At the moment, ending a subscription is only available in the Dashboard but we'll be supporting this via the Backend API in the future.

Contributors
Iago Dahlem
Maurício Antunes

Share this article