Skip to main content
Docs

Billing object

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

await clerk.billing.getPaymentAttempt({
  id: 'payment_attempt_123',
})

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

await clerk.billing.getPaymentAttempts()

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

await clerk.billing.getPlan({
  id: 'plan_123',
})

getPlans()

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

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page.

Example

await clerk.billing.getPlans()

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

await clerk.billing.getStatement({
  id: 'statement_123',
})

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

await clerk.billing.getStatements()

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

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

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

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub