Billing

Overview

Available Operations

list_plans - List all billing plans
list_prices - List all billing prices
create_price - Create a custom billing price
list_subscription_items - List all subscription items
cancel_subscription_item - Cancel a subscription item
extend_subscription_item_free_trial - Extend free trial for a subscription item
create_price_transition - Create a price transition for a subscription item
list_statements - List all billing statements
get_statement - Retrieve a billing statement
get_statement_payment_attempts - List payment attempts for a billing statement

list_plans

Returns a list of all billing plans for the instance. The plans are returned sorted by creation date, with the newest plans appearing first. This includes both free and paid plans. Pagination is supported.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.list_plans(paginated=True, limit=20, offset=10, payer_type=clerk_backend_api.PayerType.ORG)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`paginated`	Optional[bool]	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`payer_type`	Optional[models.PayerType]	➖	Filter plans by payer type
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PaginatedCommercePlanResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

list_prices

Returns a list of all prices for the instance. The prices are returned sorted by amount ascending, then by creation date descending. This includes both default and custom prices. Pagination is supported.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.list_prices(paginated=True, limit=20, offset=10, plan_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`paginated`	Optional[bool]	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`plan_id`	Optional[str]	➖	Filter prices by plan ID
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PaginatedBillingPriceResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

create_price

Creates a custom price for a billing plan. Custom prices allow you to offer different pricing to specific customers while maintaining the same plan structure.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.create_price(plan_id="<id>", amount=826545, currency="USD", annual_monthly_amount=565484, description="why whoa remarkable properly freely at creative following inspect woot", supported_billing_periods=clerk_backend_api.CreateBillingPriceRequestSupportedBillingPeriods.BOTH)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`plan_id`	str	✔️	The ID of the plan this price belongs to.
`amount`	Nullable[int]	✔️	The monthly amount in cents. Must be at least $1 (100 cents) if not null.
`currency`	Optional[str]	➖	The currency code (e.g., "USD"). Defaults to USD.
`annual_monthly_amount`	OptionalNullable[int]	➖	The monthly amount in cents when billed annually. Must be at least $1 (100 cents) if not null.
`description`	Optional[str]	➖	An optional description for this custom price.
`supported_billing_periods`	Optional[models.CreateBillingPriceRequestSupportedBillingPeriods]	➖	Which billing periods this price supports. Inferred from amounts if omitted.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.BillingPriceResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

list_subscription_items

Returns a list of all subscription items for the instance. The subscription items are returned sorted by creation date, with the newest appearing first. This includes subscriptions for both users and organizations. Pagination is supported.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.list_subscription_items(paginated=False, limit=20, offset=10, status=clerk_backend_api.GetCommerceSubscriptionItemListQueryParamStatus.FREE_TRIAL, payer_type=clerk_backend_api.QueryParamPayerType.ORG, plan_id="<id>", include_free=False, query="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`paginated`	Optional[bool]	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`status`	Optional[models.GetCommerceSubscriptionItemListQueryParamStatus]	➖	Filter subscription items by status
`payer_type`	Optional[models.QueryParamPayerType]	➖	Filter subscription items by payer type
`plan_id`	Optional[str]	➖	Filter subscription items by plan ID
`include_free`	Optional[bool]	➖	Whether to include free plan subscription items
`query`	Optional[str]	➖	Search query to filter subscription items
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PaginatedCommerceSubscriptionItemResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

cancel_subscription_item

Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.cancel_subscription_item(subscription_item_id="<id>", end_now=False)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscription_item_id`	str	✔️	The ID of the subscription item to cancel
`end_now`	Optional[bool]	➖	Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CommerceSubscriptionItem

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

extend_subscription_item_free_trial

Extends the free trial period for a specific subscription item to the specified timestamp. The subscription item must be currently in a free trial period, and the plan must support free trials. The timestamp must be in the future and not more than 365 days from the end of the current trial period This operation is idempotent - repeated requests with the same timestamp will not change the trial period.

Example Usage

from clerk_backend_api import Clerk
from clerk_backend_api.utils import parse_datetime


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.extend_subscription_item_free_trial(subscription_item_id="<id>", extend_to=parse_datetime("2026-01-08T00:00:00Z"))

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`subscription_item_id`	str	✔️	The ID of the subscription item to extend the free trial for
`extend_to`	date	✔️	RFC3339 timestamp to extend the free trial to. Must be in the future and not more than 365 days from now.	2026-01-08T00:00:00Z
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CommerceSubscriptionItem2

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

create_price_transition

Creates a price transition for the specified subscription item. This may create an upcoming subscription item or activate immediately depending on plan and payer rules.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.create_price_transition(subscription_item_id="<id>", from_price_id="<id>", to_price_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscription_item_id`	str	✔️	The ID of the subscription item to transition
`from_price_id`	str	✔️	The current price ID of the subscription item.
`to_price_id`	str	✔️	The target price ID to transition to.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CommercePriceTransitionResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 409, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

list_statements

Returns a list of all billing statements for the instance. The statements are returned sorted by creation date, with the newest statements appearing first. Pagination is supported.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.list_statements(paginated=False, limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`paginated`	Optional[bool]	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PaginatedBillingStatementResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

get_statement

Retrieves the details of a billing statement.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.get_statement(statement_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`statement_id`	str	✔️	The ID of the statement to retrieve.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.BillingStatement

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

get_statement_payment_attempts

Returns a list of all payment attempts for a specific billing statement. The payment attempts are returned sorted by creation date, with the newest payment attempts appearing first. Pagination is supported.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.billing.get_statement_payment_attempts(statement_id="<id>", paginated=True, limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`statement_id`	str	✔️	The ID of the statement to retrieve payment attempts for.
`paginated`	Optional[bool]	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PaginatedBillingPaymentAttemptResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	/

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Billing

Overview

Available Operations

list_plans

Example Usage

Parameters

Response

Errors

list_prices

Example Usage

Parameters

Response

Errors

create_price

Example Usage

Parameters

Response

Errors

list_subscription_items

Example Usage

Parameters

Response

Errors

cancel_subscription_item

Example Usage

Parameters

Response

Errors

extend_subscription_item_free_trial

Example Usage

Parameters

Response

Errors

create_price_transition

Example Usage

Parameters

Response

Errors

list_statements

Example Usage

Parameters

Response

Errors

get_statement

Example Usage

Parameters

Response

Errors

get_statement_payment_attempts

Example Usage

Parameters

Response

Errors