`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 $clerkStore to access the Clerk object, and then call the getPaymentAttempt() method.

React

Vue

Svelte

components/payment-attempt.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/payment-attempt.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const paymentAttempt = ref(null)

onMounted(async () => {
  paymentAttempt.value = await clerk.billing.getPaymentAttempt({
    id: 'payment_attempt_123',
  })
})
</script>

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

components/payment-attempt.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let paymentAttempt

  onMount(async () => {
    paymentAttempt = await clerk.billing.getPaymentAttempt({
      id: 'payment_attempt_123',
    })
  })
</script>

<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 $clerkStore to access the Clerk object, and then call the getPaymentAttempts() method.

React

Vue

Svelte

components/payment-attempts.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/payment-attempts.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const paymentAttempts = ref(null)

// Call the getPaymentAttempts() method
onMounted(async () => {
  paymentAttempts.value = await clerk.billing.getPaymentAttempts()
})
</script>

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

components/payment-attempts.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let paymentAttempts

  // Call the getPaymentAttempts() method
  onMount(async () => {
    paymentAttempts = await clerk.billing.getPaymentAttempts()
  })
</script>

<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 $clerkStore to access the Clerk object, and then call the getPlan() method.

React

Vue

Svelte

components/plan.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/plan.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const plan = ref(null)

// Call the getPlan() method
onMounted(async () => {
  plan.value = await clerk.billing.getPlan({
    id: 'plan_123',
  })
})
</script>

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

components/plan.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let plan

  // Call the getPlan() method
  onMount(async () => {
    plan = await clerk.billing.getPlan({
      id: 'plan_123',
    })
  })
</script>

<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
minSeats?
Type
number
Description
The minimum number of seats that the returned plans needs to support.
Name
orgId?
Type
string
Description
The organization ID to fetch plans for (needs to match the current Active Organization ID). Providing this parameter will populate the availablePrices field with the prices that are available to the authenticated organization.
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 $clerkStore to access the Clerk object, and then call the getPlans() method.

React

Vue

Svelte

components/plans.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/plans.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const plans = ref(null)

// Call the getPlans() method
onMounted(async () => {
  plans.value = await clerk.billing.getPlans()
})
</script>

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

components/plans.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let plans

  // Call the getPlans() method
  onMount(async () => {
    plans = await clerk.billing.getPlans()
  })
</script>

<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 $clerkStore to access the Clerk object, and then call the getStatement() method.

React

Vue

Svelte

components/statement.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/statement.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const statement = ref(null)

// Call the getStatement() method
onMounted(async () => {
  statement.value = await clerk.billing.getStatement({
    id: 'statement_123',
  })
})
</script>

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

components/statement.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let statement

  // Call the getStatement() method
  onMount(async () => {
    statement = await clerk.billing.getStatement({
      id: 'statement_123',
    })
  })
</script>

<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 $clerkStore to access the Clerk object, and then call the getStatements() method.

React

Vue

Svelte

components/statements.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/statements.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const statements = ref(null)

// Call the getStatements() method
onMounted(async () => {
  statements.value = await clerk.billing.getStatements()
})
</script>

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

components/statements.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let statements

  // Call the getStatements() method
  onMount(async () => {
    statements = await clerk.billing.getStatements()
  })
</script>

<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 $clerkStore to access the Clerk object, and then call the getSubscription() method.

React

Vue

Svelte

components/subscription.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/subscription.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const subscription = ref(null)

// Call the getSubscription() method
onMounted(async () => {
  subscription.value = await clerk.billing.getSubscription({
    orgId: 'org_123',
  })
})
</script>

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

components/subscription.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let subscription

  // Call the getSubscription() method
  onMount(async () => {
    subscription = await clerk.billing.getSubscription({
      orgId: 'org_123',
    })
  })
</script>

<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.
Name
priceId?
Type
string
Description
The specific price ID to check out for, used when the desired price ID is not the current default price
Name
seatsQuantity?
Type
number
Description
The number of total seats to check out for

Example

The Billing object is available on the Clerk object. Use the $clerkStore to access the Clerk object, and then call the startCheckout() method.

React

Vue

Svelte

components/checkout.tsx

import { useStore } from '@nanostores/react'
import { $clerkStore } from '@clerk/astro/client'

export default async function Client() {
  // Use the $clerkStore to access the Clerk object
  const clerk = useStore($clerkStore)

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

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

components/checkout.vue

<script setup>
import { ref, onMounted } from 'vue'
import { useStore } from '@nanostores/vue'
import { $clerkStore } from '@clerk/astro/client'

const clerk = useStore($clerkStore)
const checkout = ref(null)

// Call the startCheckout() method
onMounted(async () => {
  checkout.value = await clerk.billing.startCheckout({
    planId: 'plan_123',
    planPeriod: 'month',
  })
})
</script>

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

components/checkout.svelte

<script>
  // The $ prefix is reserved in Svelte for its own reactivity system.
  // Alias the imports to avoid conflicts.
  import { $clerkStore as clerk } from '@clerk/astro/client'
  import { onMount } from 'svelte'
  let checkout

  // Call the startCheckout() method
  onMount(async () => {
    checkout = await clerk.billing.startCheckout({
      planId: 'plan_123',
      planPeriod: 'month',
    })
  })
</script>

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

Last updated on Jun 9, 2026

Edit on GitHub

Billing object

Feedback

`Billing` object