Skip to main content

Billing object

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

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

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

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

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

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

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.

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
    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.

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>
}

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub