# Billing object

> Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend [pinning](https://clerk.com/docs/pinning.md?sdk=astro) your SDK and `clerk-js` package versions.

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

> 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](https://clerk.com/docs/astro/reference/types/billing-payment-resource.md) object.

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

#### `GetPaymentAttemptParams`

| Property                                | Type     | Description                                                                                                                                                         |
| --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                    | `string` | The unique identifier for the payment attempt to get.                                                                                                               |
| <a id="initialpage"></a> `initialPage?` | `number` | 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`. |
| `orgId?`                                | `string` | The Organization ID to perform the request on.                                                                                                                      |
| <a id="pagesize"></a> `pageSize?`       | `number` | 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](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getPaymentAttempt()` method.

**React**

filename: components/payment-attempt.tsx
```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>
}
```

**Vue**

filename: components/payment-attempt.vue
```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>
```

**Svelte**

filename: components/payment-attempt.svelte
```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](https://clerk.com/docs/astro/reference/types/clerk-paginated-response.md) of [BillingPaymentResource](https://clerk.com/docs/astro/reference/types/billing-payment-resource.md) objects.

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

#### `GetPaymentAttemptsParams`

| Property                                | Type     | Description                                                                                                                                                         |
| --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="initialpage"></a> `initialPage?` | `number` | 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`. |
| `orgId?`                                | `string` | The Organization ID to perform the request on.                                                                                                                      |
| <a id="pagesize"></a> `pageSize?`       | `number` | 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](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getPaymentAttempts()` method.

**React**

filename: components/payment-attempts.tsx
```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>
}
```

**Vue**

filename: components/payment-attempts.vue
```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>
```

**Svelte**

filename: components/payment-attempts.svelte
```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](https://clerk.com/docs/astro/reference/types/billing-plan-resource.md) object.

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

#### `GetPlanParams`

| Property             | Type     | Description                        |
| -------------------- | -------- | ---------------------------------- |
| <a id="id"></a> `id` | `string` | The ID of the Billing Plan to get. |

#### Example

The `Billing` object is available on the [Clerk](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getPlan()` method.

**React**

filename: components/plan.tsx
```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>
}
```

**Vue**

filename: components/plan.vue
```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>
```

**Svelte**

filename: components/plan.svelte
```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](https://clerk.com/docs/astro/reference/types/clerk-paginated-response.md) of [BillingPlanResource](https://clerk.com/docs/astro/reference/types/billing-plan-resource.md) objects.

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

#### `GetPlansParams`

| Property                                | Type                                 | Description                                                                                                                                                                                                                          |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `for?`                                  | `"user" | "organization"` | The type of payer for the Plans.                                                                                                                                                                                                     |
| <a id="initialpage"></a> `initialPage?` | `number`                             | 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`.                                                                  |
| `minSeats?`                             | `number`                             | The minimum number of seats that the returned plans needs to support.                                                                                                                                                                |
| `orgId?`                                | `string`                             | 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. |
| <a id="pagesize"></a> `pageSize?`       | `number`                             | 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](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getPlans()` method.

**React**

filename: components/plans.tsx
```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>
}
```

**Vue**

filename: components/plans.vue
```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>
```

**Svelte**

filename: components/plans.svelte
```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](https://clerk.com/docs/astro/reference/types/billing-statement-resource.md) object.

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

#### `GetStatementParams`

| Property                                | Type     | Description                                                                                                                                                         |
| --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                    | `string` | The ID of the statement to get.                                                                                                                                     |
| <a id="initialpage"></a> `initialPage?` | `number` | 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`. |
| `orgId?`                                | `string` | The Organization ID to perform the request on.                                                                                                                      |
| <a id="pagesize"></a> `pageSize?`       | `number` | 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](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getStatement()` method.

**React**

filename: components/statement.tsx
```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>
}
```

**Vue**

filename: components/statement.vue
```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>
```

**Svelte**

filename: components/statement.svelte
```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](https://clerk.com/docs/astro/reference/types/clerk-paginated-response.md) of [BillingStatementResource](https://clerk.com/docs/astro/reference/types/billing-statement-resource.md) objects.

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

#### `GetStatementsParams`

| Property                                | Type     | Description                                                                                                                                                         |
| --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="initialpage"></a> `initialPage?` | `number` | 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`. |
| `orgId?`                                | `string` | The Organization ID to perform the request on.                                                                                                                      |
| <a id="pagesize"></a> `pageSize?`       | `number` | 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](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getStatements()` method.

**React**

filename: components/statements.tsx
```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>
}
```

**Vue**

filename: components/statements.vue
```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>
```

**Svelte**

filename: components/statements.svelte
```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](https://clerk.com/docs/astro/reference/types/billing-subscription-resource.md) object.

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

#### `GetSubscriptionParams`

| Property                    | Type     | Description                                                             |
| --------------------------- | -------- | ----------------------------------------------------------------------- |
| <a id="orgid"></a> `orgId?` | `string` | The unique identifier for the Organization to get the subscription for. |

#### Example

The `Billing` object is available on the [Clerk](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `getSubscription()` method.

**React**

filename: components/subscription.tsx
```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>
}
```

**Vue**

filename: components/subscription.vue
```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>
```

**Svelte**

filename: components/subscription.svelte
```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](https://clerk.com/docs/astro/reference/types/billing-checkout-resource.md) object.

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

#### `CreateCheckoutParams`

| Property         | Type                            | Description                                                                                             |
| ---------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `orgId?`         | `string`                        | The Organization ID to perform the request on.                                                          |
| `planId`         | `string`                        | The unique identifier for the Plan.                                                                     |
| `planPeriod`     | `"month" | "annual"` | The billing period for the Plan.                                                                        |
| `priceId?`       | `string`                        | The specific price ID to check out for, used when the desired price ID is not the current default price |
| `seatsQuantity?` | `number`                        | The number of total seats to check out for                                                              |

#### Example

The `Billing` object is available on the [Clerk](https://clerk.com/docs/astro/reference/objects/clerk.md) object. Use the [$clerkStore](https://clerk.com/docs/astro/reference/astro/client-side-helpers/clerk-store.md) to access the `Clerk` object, and then call the `startCheckout()` method.

**React**

filename: components/checkout.tsx
```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>
}
```

**Vue**

filename: components/checkout.vue
```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>
```

**Svelte**

filename: components/checkout.svelte
```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>
```

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)