`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()`

Returns 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 ID of the payment attempt to fetch.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.

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/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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()`

Returns 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.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.

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/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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>
}

`getPlan()`

Returns a Billing Plan by ID. Returns a BillingPlanResource object.

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

`GetPlanParams`

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

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/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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()`

Returns a list of all publicly 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.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page.

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/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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>
}

`getStatement()`

Returns a billing statement by ID. Returns a BillingStatementResource object.

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

`GetStatementParams`

Name
id
Type
string
Description
The ID of the statement to fetch.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.

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/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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()`

Returns 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.
Name
pageSize?
Type
number
Description
A number that specifies the maximum number of results to return per page.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.

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/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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>
}

`getSubscription()`

Returns 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 Organization ID to perform the request on.

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.

app/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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
planId
Type
string
Description
The unique identifier for the Plan.
Name
planPeriod
Type
"month" | "annual"
Description
The billing period for the Plan.
Name
orgId?
Type
string
Description
The Organization ID to perform the request on.

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.

app/routes/index.tsx

import { useClerk } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

export default function Home() {
  // 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 Mar 19, 2026

Edit on GitHub

Billing object

Feedback

`Billing` object