`Billing` object

Methods

Available in other SDKs

Warning

Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend pinning your SDK and clerk-js package versions.

The Billing object provides methods for managing billing for a user or Organization.

Note

If an orgId parameter is not provided, the methods will automatically use the current user's ID.

Methods

`getPaymentAttempt()`

Gets details of a specific payment attempt for the current user or supplied Organization.

Returns a BillingPaymentResource object.

function getPaymentAttempt(params: GetPaymentAttemptParams): Promise<BillingPaymentResource>

`GetPaymentAttemptParams`

Name
id
Type
string
Description
The unique identifier for the payment attempt to get.
Name
initialPage?
Type
number
Description
A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page. Defaults to 10.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getPaymentAttempt() method.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getPaymentAttempt() method
  const paymentAttempt = await clerk.billing.getPaymentAttempt({
    id: 'payment_attempt_123',
  })

  return <pre>{JSON.stringify(paymentAttempt, null, 2)}</pre>
}

`getPaymentAttempts()`

Gets a list of payment attempts for the current user or supplied Organization.

Returns a ClerkPaginatedResponse of BillingPaymentResource objects.

function getPaymentAttempts(params: GetPaymentAttemptsParams): Promise<ClerkPaginatedResponse<BillingPaymentResource>>

`GetPaymentAttemptsParams`

Name
initialPage?
Type
number
Description
A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page. Defaults to 10.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getPaymentAttempts() method.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getPaymentAttempts() method
  const paymentAttempts = await clerk.billing.getPaymentAttempts()

  return <pre>{JSON.stringify(paymentAttempts, null, 2)}</pre>
}

You can also use the usePaymentAttempts() hook for a simpler way to get the payment attempts.

app/billing/payment-attempts/page.tsx

'use client'

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

export default function PaymentAttemptsList() {
  const { data, isLoading } = usePaymentAttempts({
    for: 'user',
    pageSize: 10,
  })

  if (isLoading) {
    return <div>Loading payment attempts...</div>
  }

  if (!data || data.length === 0) {
    return <div>No payment attempts found.</div>
  }

  return (
    <ul>
      {data?.map((attempt) => (
        <li key={attempt.id}>
          Payment #{attempt.id} - {attempt.status}
          <br />
          Amount: {attempt.amount.amountFormatted} on {new Date(attempt.updatedAt).toLocaleString()}
        </li>
      ))}
    </ul>
  )
}

`getPlan()`

Gets a given Billing Plan.

Returns a BillingPlanResource object.

function getPlan(params: GetPlanParams): Promise<BillingPlanResource>

`GetPlanParams`

Name
id
Type
string
Description
The ID of the Billing Plan to get.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getPlan() method.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getPlan() method
  const plan = await clerk.billing.getPlan({
    id: 'plan_123',
  })

  return <pre>{JSON.stringify(plan, null, 2)}</pre>
}

`getPlans()`

Gets a list of all publically visible Billing Plans.

Returns a ClerkPaginatedResponse of BillingPlanResource objects.

function getPlans(params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>>

`GetPlansParams`

Name
for?
Type
"user" | "organization"
Description
The type of payer for the Plans.
Name
initialPage?
Type
number
Description
A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page. Defaults to 10.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getPlans() method.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getPlans() method
  const plans = await clerk.billing.getPlans()

  return <pre>{JSON.stringify(plans, null, 2)}</pre>
}

You can also use the usePlans() hook for a simpler way to get the Plans.

app/billing/plans/page.tsx

'use client'

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

export default function PlansList() {
  const { data, isLoading, hasNextPage, fetchNext, hasPreviousPage, fetchPrevious } = usePlans({
    for: 'user',
    pageSize: 10,
  })

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

  return (
    <ul>
      {data?.map((plan) => (
        <li key={plan.id}>
          <h3>{plan.name}</h3>
          <p>{plan.description}</p>
          <p>Is free plan: {!plan.hasBaseFee ? 'Yes' : 'No'}</p>
          <p>
            Price per month: {plan.currency} {plan.amountFormatted}
          </p>
          <p>
            Price per year: {plan.currency} {plan.annualAmountFormatted} equivalent to{' '}
            {plan.currency} {plan.annualMonthlyAmountFormatted} per month
          </p>
          <h4>Features:</h4>
          <ul>
            {plan.features.map((feature) => (
              <li key={feature.id}>{feature.name}</li>
            ))}
          </ul>
        </li>
      ))}

      {hasNextPage && <button onClick={() => fetchNext()}>Next</button>}
      {hasPreviousPage && <button onClick={() => fetchPrevious()}>Previous</button>}
    </ul>
  )
}

`getStatement()`

Gets a given Billing Statement.

Returns a BillingStatementResource object.

function getStatement(params: GetStatementParams): Promise<BillingStatementResource>

`GetStatementParams`

Name
id
Type
string
Description
The ID of the statement to get.
Name
initialPage?
Type
number
Description
A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page. Defaults to 10.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getStatement() method.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getStatement() method
  const statement = await clerk.billing.getStatement({
    id: 'statement_123',
  })

  return <pre>{JSON.stringify(statement, null, 2)}</pre>
}

`getStatements()`

Gets a list of Billing Statements for the current user or supplied Organization.

Returns a ClerkPaginatedResponse of BillingStatementResource objects.

function getStatements(params: GetStatementsParams): Promise<ClerkPaginatedResponse<BillingStatementResource>>

`GetStatementsParams`

Name
initialPage?
Type
number
Description
A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page. Defaults to 10.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getStatements() method.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getStatements() method
  const statements = await clerk.billing.getStatements()

  return <pre>{JSON.stringify(statements, null, 2)}</pre>
}

You can also use the useStatements() hook for a simpler way to get the statements.

app/billing/statements/page.tsx

'use client'

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

export default function StatementsList() {
  const { data, isLoading } = useStatements({
    for: 'user',
    pageSize: 10,
  })

  if (isLoading) {
    return <div>Loading statements...</div>
  }

  if (!data || data.length === 0) {
    return <div>No statements found.</div>
  }

  return (
    <ul>
      {data?.map((statement) => (
        <li key={statement.id}>
          Statement ID: {statement.id} - {statement.status}
          <br />
          Date: {statement.timestamp.toLocaleDateString()}
        </li>
      ))}
    </ul>
  )
}

`getSubscription()`

Gets the main Billing Subscription for the current user or supplied Organization.

Returns a BillingSubscriptionResource object.

function getSubscription(params: GetSubscriptionParams): Promise<BillingSubscriptionResource>

`GetSubscriptionParams`

Name
orgId?
Type
string
Description
The unique identifier for the Organization to get the subscription for.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the getSubscription() method.

Important

You can also use the useSubscription() hook for a simpler way to manage subscriptions. See the reference documentation for more information.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the getSubscription() method
  const subscription = await clerk.billing.getSubscription({
    orgId: 'org_123',
  })

  return <pre>{JSON.stringify(subscription, null, 2)}</pre>
}

`startCheckout()`

Creates a new Billing checkout for the current user or supplied Organization.

Returns a BillingCheckoutResource object.

function startCheckout(params: CreateCheckoutParams): Promise<BillingCheckoutResource>

`CreateCheckoutParams`

Name
orgId?
Type
string
Description
The Organization ID to perform the request on.
Name
planId
Type
string
Description
The unique identifier for the Plan.
Name
planPeriod
Type
"month" | "annual"
Description
The billing period for the Plan.

Example

The Billing object is available on the Clerk object. Use the useClerk() hook to access the clerk.billing object, and then call the startCheckout() method.

Important

You can also use the useCheckout() hook for a simpler way to start a checkout. See the reference documentation for more information.

app/page.tsx

'use client'

import { useClerk } from '@clerk/nextjs'

export default async function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Call the startCheckout() method
  const checkout = await clerk.billing.startCheckout({
    planId: 'plan_123',
    planPeriod: 'month',
  })

  return <pre>{JSON.stringify(checkout, null, 2)}</pre>
}

Last updated on Jun 4, 2026

Edit on GitHub

Billing object

Feedback

`Billing` object