# 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=react-router) 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/react-router/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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getPaymentAttempt()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/reference/types/clerk-paginated-response.md) of [BillingPaymentResource](https://clerk.com/docs/react-router/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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getPaymentAttempts()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getPlan()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/reference/types/clerk-paginated-response.md) of [BillingPlanResource](https://clerk.com/docs/react-router/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`. |
| <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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getPlans()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getStatement()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/reference/types/clerk-paginated-response.md) of [BillingStatementResource](https://clerk.com/docs/react-router/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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getStatements()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/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/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `getSubscription()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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](https://clerk.com/docs/react-router/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.               |

#### Example

The `Billing` object is available on the [Clerk](https://clerk.com/docs/react-router/reference/objects/clerk.md) object. Use the [useClerk()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk.billing` object, and then call the `startCheckout()` method.

filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'

export default async 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>
}
```

---

## Sitemap

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