Billing

Overview

Available Operations

listPlans - List all billing plans
listPrices - List all billing prices
createPrice - Create a custom billing price
listSubscriptionItems - List all subscription items
cancelSubscriptionItem - Cancel a subscription item
extendSubscriptionItemFreeTrial - Extend free trial for a subscription item
createPriceTransition - Create a price transition for a subscription item
listStatements - List all billing statements
getStatement - Retrieve a billing statement
getStatementPaymentAttempts - List payment attempts for a billing statement

listPlans

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetCommercePlanListResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetCommercePlanListResponse res = sdk.billing().listPlans()
                .limit(10L)
                .offset(0L)
                .call();

        if (res.paginatedCommercePlanResponse().isPresent()) {
            System.out.println(res.paginatedCommercePlanResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`paginated`	Optional<Boolean>	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional<Long>	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.
`offset`	Optional<Long>	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.
`payerType`	Optional<PayerType>	➖	Filter plans by payer type

Response

GetCommercePlanListResponse

Errors

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

listPrices

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetBillingPriceListResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetBillingPriceListResponse res = sdk.billing().listPrices()
                .limit(10L)
                .offset(0L)
                .call();

        if (res.paginatedBillingPriceResponse().isPresent()) {
            System.out.println(res.paginatedBillingPriceResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`paginated`	Optional<Boolean>	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional<Long>	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.
`offset`	Optional<Long>	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.
`planId`	Optional<String>	➖	Filter prices by plan ID

Response

GetBillingPriceListResponse

Errors

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

createPrice

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.components.CreateBillingPriceRequest;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.CreateBillingPriceResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CreateBillingPriceRequest req = CreateBillingPriceRequest.builder()
                .planId("<id>")
                .amount(826545L)
                .build();

        CreateBillingPriceResponse res = sdk.billing().createPrice()
                .request(req)
                .call();

        if (res.billingPriceResponse().isPresent()) {
            System.out.println(res.billingPriceResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`request`	CreateBillingPriceRequest	✔️	The request object to use for the request.

Response

CreateBillingPriceResponse

Errors

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

listSubscriptionItems

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetCommerceSubscriptionItemListRequest;
import com.clerk.backend_api.models.operations.GetCommerceSubscriptionItemListResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetCommerceSubscriptionItemListRequest req = GetCommerceSubscriptionItemListRequest.builder()
                .build();

        GetCommerceSubscriptionItemListResponse res = sdk.billing().listSubscriptionItems()
                .request(req)
                .call();

        if (res.paginatedCommerceSubscriptionItemResponse().isPresent()) {
            System.out.println(res.paginatedCommerceSubscriptionItemResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`request`	GetCommerceSubscriptionItemListRequest	✔️	The request object to use for the request.

Response

GetCommerceSubscriptionItemListResponse

Errors

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

cancelSubscriptionItem

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

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.CancelCommerceSubscriptionItemResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CancelCommerceSubscriptionItemResponse res = sdk.billing().cancelSubscriptionItem()
                .subscriptionItemId("<id>")
                .endNow(false)
                .call();

        if (res.commerceSubscriptionItem().isPresent()) {
            System.out.println(res.commerceSubscriptionItem().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`subscriptionItemId`	String	✔️	The ID of the subscription item to cancel
`endNow`	Optional<Boolean>	➖	Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)

Response

CancelCommerceSubscriptionItemResponse

Errors

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

extendSubscriptionItemFreeTrial

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.components.ExtendFreeTrialRequest;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.ExtendBillingSubscriptionItemFreeTrialResponse;
import java.lang.Exception;
import java.time.OffsetDateTime;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        ExtendBillingSubscriptionItemFreeTrialResponse res = sdk.billing().extendSubscriptionItemFreeTrial()
                .subscriptionItemId("<id>")
                .extendFreeTrialRequest(ExtendFreeTrialRequest.builder()
                    .extendTo(OffsetDateTime.parse("2026-01-08T00:00:00Z"))
                    .build())
                .call();

        if (res.schemasCommerceSubscriptionItem().isPresent()) {
            System.out.println(res.schemasCommerceSubscriptionItem().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`subscriptionItemId`	String	✔️	The ID of the subscription item to extend the free trial for
`extendFreeTrialRequest`	ExtendFreeTrialRequest	✔️	Parameters for extending the free trial

Response

ExtendBillingSubscriptionItemFreeTrialResponse

Errors

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

createPriceTransition

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.components.PriceTransitionRequest;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.CreateBillingPriceTransitionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CreateBillingPriceTransitionResponse res = sdk.billing().createPriceTransition()
                .subscriptionItemId("<id>")
                .priceTransitionRequest(PriceTransitionRequest.builder()
                    .fromPriceId("<id>")
                    .toPriceId("<id>")
                    .build())
                .call();

        if (res.commercePriceTransitionResponse().isPresent()) {
            System.out.println(res.commercePriceTransitionResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`subscriptionItemId`	String	✔️	The ID of the subscription item to transition
`priceTransitionRequest`	PriceTransitionRequest	✔️	Parameters for the price transition

Response

CreateBillingPriceTransitionResponse

Errors

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

listStatements

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetBillingStatementListResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetBillingStatementListResponse res = sdk.billing().listStatements()
                .limit(10L)
                .offset(0L)
                .call();

        if (res.paginatedBillingStatementResponse().isPresent()) {
            System.out.println(res.paginatedBillingStatementResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`paginated`	Optional<Boolean>	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional<Long>	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.
`offset`	Optional<Long>	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.

Response

GetBillingStatementListResponse

Errors

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

getStatement

Retrieves the details of a billing statement.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetBillingStatementResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetBillingStatementResponse res = sdk.billing().getStatement()
                .statementID("<id>")
                .call();

        if (res.billingStatement().isPresent()) {
            System.out.println(res.billingStatement().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`statementID`	String	✔️	The ID of the statement to retrieve.

Response

GetBillingStatementResponse

Errors

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

getStatementPaymentAttempts

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

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetBillingStatementPaymentAttemptsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetBillingStatementPaymentAttemptsResponse res = sdk.billing().getStatementPaymentAttempts()
                .statementID("<id>")
                .limit(10L)
                .offset(0L)
                .call();

        if (res.paginatedBillingPaymentAttemptResponse().isPresent()) {
            System.out.println(res.paginatedBillingPaymentAttemptResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`statementID`	String	✔️	The ID of the statement to retrieve payment attempts for.
`paginated`	Optional<Boolean>	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
`limit`	Optional<Long>	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.
`offset`	Optional<Long>	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.

Response

GetBillingStatementPaymentAttemptsResponse

Errors

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

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Billing

Overview

Available Operations

listPlans

Example Usage

Parameters

Response

Errors

listPrices

Example Usage

Parameters

Response

Errors

createPrice

Example Usage

Parameters

Response

Errors

listSubscriptionItems

Example Usage

Parameters

Response

Errors

cancelSubscriptionItem

Example Usage

Parameters

Response

Errors

extendSubscriptionItemFreeTrial

Example Usage

Parameters

Response

Errors

createPriceTransition

Example Usage

Parameters

Response

Errors

listStatements

Example Usage

Parameters

Response

Errors

getStatement

Example Usage

Parameters

Response

Errors

getStatementPaymentAttempts

Example Usage

Parameters

Response

Errors