Clerk

Clerk Billing API

Billing-related endpoints for managing statements and payment attempts.

GitHub OpenAPI
Business capability
Subscription Billing & Revenue Management BC-4250

Operations 18

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /users/{user_id}/billing/subscription Retrieve a user's billing subscription · Retrieve a user's billing subscription #
Ask an LLM
“What plans is a given user subscribed to and what is their payment status?”
“How do I read a user's billing subscription items from my backend?”
Tell an agent
Get the billing subscription for user {user_id}.
Show which plans user {user_id} is paying for.
GET /users/{user_id}/billing/credits Check a user's credit balance · Retrieve a user's credit balance #
Ask an LLM
“How much billing credit does a user have left?”
“Can I see a user's credit balance before their next recurring charge?”
Tell an agent
Get the credit balance for user {user_id}.
Tell me how many credits user {user_id} has.
POST /users/{user_id}/billing/credits Add or remove credit for a user · Adjust a user's credit balance #
Ask an LLM
“How do I give a user account credit toward future charges?”
“Can I decrease a user's credit balance and record a note on the ledger entry?”
Tell an agent
Adjust user {user_id} credits: {action} {amount} with idempotency key {idempotency_key}.
Credit user {user_id} {amount} in {currency} ({action}) with key {idempotency_key} and note {note}.
GET /organizations/{organization_id}/billing/subscription Retrieve an organization's billing subscription · Retrieve an organization's billing subscription #
Ask an LLM
“Which plans is an organization subscribed to, as seen from the backend?”
“How do I check an organization's payment status and subscription items server-side?”
Tell an agent
Get the billing subscription for organization {organization_id} from the backend.
Show which plans organization {organization_id} pays for.
GET /organizations/{organization_id}/billing/credits Check an organization's credit balance · Retrieve an organization's credit balance #
Ask an LLM
“How much billing credit does an organization have available?”
“Can I see an organization's credits before its next renewal?”
Tell an agent
Get the credit balance for organization {organization_id}.
Tell me how many credits organization {organization_id} has.
POST /organizations/{organization_id}/billing/credits Add or remove credit for an organization · Adjust an organization's credit balance #
Ask an LLM
“How do I grant an organization credit to offset its next bill?”
“Can I deduct credits from an organization and leave a note on the ledger?”
Tell an agent
Adjust organization {organization_id} credits: {action} {amount} with idempotency key {idempotency_key}.
Give organization {organization_id} {amount} {currency} of credit ({action}), key {idempotency_key}.
GET /billing/plans List all billing plans for the instance · List all billing plans #
Ask an LLM
“What billing plans, free and paid, are configured on my instance?”
“Can I list only the plans meant for organizations rather than users?”
Tell an agent
List every billing plan in my instance from the backend.
List billing plans for payer type {payer_type}.
GET /billing/prices List billing prices · List all billing prices #
Ask an LLM
“Which prices, including custom ones, exist for my billing plans?”
“How do I see all the prices attached to one plan?”
Tell an agent
List all billing prices.
Show the prices for plan {plan_id}.
POST /billing/prices Create a custom price for a plan · Create a custom billing price #
Ask an LLM
“How do I offer a specific customer a different price on the same plan?”
“Can a custom price have a separate monthly amount when billed annually?”
Tell an agent
Create a custom price of {amount} for plan {plan_id}.
Add a {currency} price of {amount} to plan {plan_id} with annual monthly amount {annual_monthly_amount}.
GET /billing/subscription_items List subscription items across the instance · List all subscription items #
Ask an LLM
“Which users and organizations are subscribed to a given plan?”
“Can I list subscription items by status and exclude free plans?”
Tell an agent
List all subscription items on plan {plan_id}.
Show subscription items with status {status} for payer type {payer_type}.
DELETE /billing/subscription_items/{subscription_item_id} Cancel a subscription item · Cancel a subscription item #
Ask an LLM
“How do I cancel a customer's plan at the end of the billing period?”
“Can I cancel a subscription item immediately instead of waiting for the period to end?”
Tell an agent destructive · confirm first
Cancel subscription item {subscription_item_id} at period end.
Cancel subscription item {subscription_item_id} now (end_now {end_now}).
POST /billing/subscription_items/{subscription_item_id}/extend_free_trial Extend a subscription item's free trial · Extend free trial for a subscription item #
Ask an LLM
“How do I give a customer a longer free trial on their plan?”
“Is there a limit on how far into the future a free trial can be extended?”
Tell an agent
Extend the free trial of subscription item {subscription_item_id} to {extend_to}.
Push the trial end of subscription item {subscription_item_id} out to {extend_to}.
POST /billing/subscription_items/{subscription_item_id}/price_transition Move a subscription item to a new price · Create a price transition for a subscription item #
Ask an LLM
“How do I switch a subscriber from one price to another on their subscription item?”
“Does a price transition take effect immediately or create an upcoming item?”
Tell an agent
Transition subscription item {subscription_item_id} from price {from_price_id} to {to_price_id}.
Move subscriber item {subscription_item_id} onto price {to_price_id}, replacing {from_price_id}.
POST /billing/subscription_items/{subscription_item_id}/discounts Apply a discount to a subscription item #
DELETE /billing/subscription_items/{subscription_item_id}/discounts/{discount_id} Remove a discount from a subscription item #
GET /billing/statements List all billing statements for the instance · List all billing statements #
Ask an LLM
“Where can I see every billing statement issued across my instance?”
“How do I page through all statements, newest first, from the backend?”
Tell an agent
List all billing statements for my instance.
Show the latest {limit} instance billing statements.
GET /billing/statements/{statementID} Retrieve a billing statement from the backend · Retrieve a billing statement #
Ask an LLM
“How do I pull up the details of one billing statement on the server side?”
“What line items and totals are on a particular instance billing statement?”
Tell an agent
Retrieve billing statement {statementID} via the backend API.
Show the details of instance statement {statementID}.
GET /billing/statements/{statementID}/payment_attempts List payment attempts on a statement · List payment attempts for a billing statement #
Ask an LLM
“Were there failed payment attempts on a billing statement?”
“How do I see every charge attempt made against a statement?”
Tell an agent
List payment attempts for statement {statementID}.
Show charge attempts made on billing statement {statementID}.

Documentation

📖
Documentation
https://clerk.com/docs/reference/backend-api
📖
APIReference
https://clerk.com/docs/reference/backend-api
📖
GettingStarted
https://clerk.com/docs/quickstarts/overview
📖
Authentication
https://clerk.com/docs/backend-requests/making/jwt-templates
📖
Documentation
https://clerk.com/docs
📖
Documentation
https://clerk.com/docs/webhooks/overview

Specifications

⚙
OpenAPI
https://artifacts.apis.io/clerk-com/openapi/clerk-com-billing-api-openapi.yml

Other Resources

🔗
SpectralRuleset
https://artifacts.apis.io/clerk-com/rules/clerk-rules.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clerk-com:clerk-com-billing-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clerk-com-billing-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Backend Billing API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Backend API, meant to be accessed by backend servers.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see Clerk API Versions.


    Please see https://clerk.com/docs for more information.'
  version: '2026-08-20'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:


# --- truncated at 32 KB (92 KB total) ---
# Full source: https://artifacts.apis.io/clerk-com/openapi/clerk-com-billing-api-openapi.yml