Skip to main content

Billing object

Important

Billing regularly introduces new features and UI changes to Clerk's components. If you'd like to remain on a specific version of Clerk's components or SDK, you can follow the steps in the pinning documentation.

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

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

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

// Call the getPaymentAttempts() method
await clerk.billing.getPaymentAttempts()

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

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

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

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

// Call the getPlans() method
await clerk.billing.getPlans()

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

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

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

// Call the getStatements() method
await clerk.billing.getStatements()

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

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

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.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

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

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub