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

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

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

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

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

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

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 $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
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 $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 Mar 19, 2026

Edit on GitHub

Billing object

Feedback

`Billing` object