Clerk Billing API

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](https://clerk.com/docs/versioning/available-versions).


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  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:
- name: Billing
  description: Billing-related endpoints for managing statements and payment attempts.
  externalDocs:
    url: https://clerk.com/docs/billing/overview
paths:
  /users/{user_id}/billing/subscription:
    get:
      operationId: GetUserBillingSubscription
      x-speakeasy-group: users
      x-speakeasy-name-override: getBillingSubscription
      summary: Retrieve a User's Billing Subscription
      description: 'Retrieves the billing subscription for the specified user.

        This includes subscription details, active plans, billing information, and payment status.

        The subscription contains subscription items which represent the individual plans the user is subscribed to.'
      tags:
      - Billing
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
        description: The ID of the user whose subscription to retrieve
      responses:
        '200':
          $ref: '#/components/responses/CommerceSubscription'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /users/{user_id}/billing/credits:
    get:
      operationId: GetUserBillingCreditBalance
      x-speakeasy-group: users
      x-speakeasy-name-override: getBillingCreditBalance
      summary: Retrieve a User's Credit Balance
      description: 'Retrieves the current credit balance for the specified user.

        Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges'
      tags:
      - Billing
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
        description: The ID of the user whose credit balance to retrieve
      responses:
        '200':
          $ref: '#/components/responses/CommerceCreditBalance'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
    post:
      operationId: AdjustUserBillingCreditBalance
      x-speakeasy-group: users
      x-speakeasy-name-override: adjustBillingCreditBalance
      summary: Adjust a User's Credit Balance
      description: 'Increases or decreases the credit balance for the specified user.

        Each adjustment is recorded as a ledger entry. The idempotency_key parameter

        ensures that duplicate requests are safely handled.'
      tags:
      - Billing
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
        description: The ID of the user whose credit balance to adjust
      requestBody:
        description: Parameters for the credit balance adjustment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustCreditBalanceRequest'
      responses:
        '200':
          $ref: '#/components/responses/CommerceCreditLedger'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /organizations/{organization_id}/billing/subscription:
    get:
      operationId: GetOrganizationBillingSubscription
      x-speakeasy-group: organizations
      x-speakeasy-name-override: getBillingSubscription
      summary: Retrieve an Organization's Billing Subscription
      description: 'Retrieves the billing subscription for the specified organization.

        This includes subscription details, active plans, billing information, and payment status.

        The subscription contains subscription items which represent the individual plans the organization is subscribed to.'
      tags:
      - Billing
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization whose subscription to retrieve
      responses:
        '200':
          $ref: '#/components/responses/CommerceSubscription'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /organizations/{organization_id}/billing/credits:
    get:
      operationId: GetOrganizationBillingCreditBalance
      x-speakeasy-group: organizations
      x-speakeasy-name-override: getBillingCreditBalance
      summary: Retrieve an Organization's Credit Balance
      description: 'Retrieves the current credit balance for the specified organization.

        Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges.'
      tags:
      - Billing
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization whose credit balance to retrieve
      responses:
        '200':
          $ref: '#/components/responses/CommerceCreditBalance'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
    post:
      operationId: AdjustOrganizationBillingCreditBalance
      x-speakeasy-group: organizations
      x-speakeasy-name-override: adjustBillingCreditBalance
      summary: Adjust an Organization's Credit Balance
      description: 'Increases or decreases the credit balance for the specified organization.

        Each adjustment is recorded as a ledger entry. The idempotency_key parameter

        ensures that duplicate requests are safely handled.'
      tags:
      - Billing
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization whose credit balance to adjust
      requestBody:
        description: Parameters for the credit balance adjustment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustCreditBalanceRequest'
      responses:
        '200':
          $ref: '#/components/responses/CommerceCreditLedger'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/plans:
    get:
      operationId: GetCommercePlanList
      x-speakeasy-group: billing
      x-speakeasy-name-override: listPlans
      tags:
      - Billing
      summary: List All Billing Plans
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: query
        name: payer_type
        description: Filter plans by payer type
        required: false
        schema:
          type: string
          enum:
          - user
          - org
      responses:
        '200':
          $ref: '#/components/responses/CommercePlan.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/prices:
    get:
      operationId: GetBillingPriceList
      x-speakeasy-group: billing
      x-speakeasy-name-override: listPrices
      tags:
      - Billing
      summary: List All Billing Prices
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: query
        name: plan_id
        description: Filter prices by plan ID
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/BillingPrice.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
    post:
      operationId: CreateBillingPrice
      x-speakeasy-group: billing
      x-speakeasy-name-override: createPrice
      tags:
      - Billing
      summary: Create a Custom Billing Price
      description: '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.'
      requestBody:
        description: Parameters for creating a custom price
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingPriceRequest'
      responses:
        '200':
          $ref: '#/components/responses/BillingPrice'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/subscription_items:
    get:
      operationId: GetCommerceSubscriptionItemList
      x-speakeasy-group: billing
      x-speakeasy-name-override: listSubscriptionItems
      tags:
      - Billing
      summary: List All Subscription Items
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: query
        name: status
        description: Filter subscription items by status
        required: false
        schema:
          type: string
          enum:
          - active
          - ended
          - past_due
          - upcoming
          - free_trial
      - in: query
        name: payer_type
        description: Filter subscription items by payer type
        required: false
        schema:
          type: string
          enum:
          - user
          - org
      - in: query
        name: plan_id
        description: Filter subscription items by plan ID
        required: false
        schema:
          type: string
      - in: query
        name: include_free
        description: Whether to include free plan subscription items
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: query
        description: Search query to filter subscription items
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/CommerceSubscriptionItem.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/subscription_items/{subscription_item_id}:
    delete:
      operationId: CancelCommerceSubscriptionItem
      x-speakeasy-group: billing
      x-speakeasy-name-override: cancelSubscriptionItem
      tags:
      - Billing
      summary: Cancel a Subscription Item
      description: Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period.
      parameters:
      - name: subscription_item_id
        in: path
        description: The ID of the subscription item to cancel
        required: true
        schema:
          type: string
      - in: query
        name: end_now
        description: Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/CommerceSubscriptionItem'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/subscription_items/{subscription_item_id}/extend_free_trial:
    post:
      operationId: ExtendBillingSubscriptionItemFreeTrial
      x-speakeasy-group: billing
      x-speakeasy-name-override: extendSubscriptionItemFreeTrial
      tags:
      - Billing
      summary: Extend Free Trial for a Subscription Item
      description: '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.'
      parameters:
      - name: subscription_item_id
        in: path
        description: The ID of the subscription item to extend the free trial for
        required: true
        schema:
          type: string
      requestBody:
        description: Parameters for extending the free trial
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtendFreeTrialRequest'
      responses:
        '200':
          $ref: '#/components/responses/responses-CommerceSubscriptionItem'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/subscription_items/{subscription_item_id}/price_transition:
    post:
      operationId: CreateBillingPriceTransition
      x-speakeasy-group: billing
      x-speakeasy-name-override: createPriceTransition
      tags:
      - Billing
      summary: Create a Price Transition for a Subscription Item
      description: '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.'
      parameters:
      - name: subscription_item_id
        in: path
        description: The ID of the subscription item to transition
        required: true
        schema:
          type: string
      requestBody:
        description: Parameters for the price transition
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceTransitionRequest'
      responses:
        '200':
          $ref: '#/components/responses/CommercePriceTransition'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/statements:
    get:
      operationId: GetBillingStatementList
      x-speakeasy-group: billing
      x-speakeasy-name-override: listStatements
      tags:
      - Billing
      summary: List All Billing Statements
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/BillingStatement.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/statements/{statementID}:
    get:
      operationId: GetBillingStatement
      x-speakeasy-group: billing
      x-speakeasy-name-override: getStatement
      tags:
      - Billing
      summary: Retrieve a Billing Statement
      description: Retrieves the details of a billing statement.
      parameters:
      - name: statementID
        in: path
        description: The ID of the statement to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/BillingStatement'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /billing/statements/{statementID}/payment_attempts:
    get:
      operationId: GetBillingStatementPaymentAttempts
      x-speakeasy-group: billing
      x-speakeasy-name-override: getStatementPaymentAttempts
      tags:
      - Billing
      summary: List Payment Attempts for a Billing Statement
      description: '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.'
      parameters:
      - name: statementID
        in: path
        description: The ID of the statement to retrieve payment attempts for.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/BillingPaymentAttempt.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
components:
  responses:
    CommerceCreditLedger:
      description: A credit ledger entry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditLedgerResponse'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    BillingPaymentAttempt.List:
      description: A list of billing payment attempts.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedBillingPaymentAttemptResponse'
    CommerceSubscriptionItem.List:
      description: A list of commerce subscription items.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedCommerceSubscriptionItemResponse'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    BillingPrice:
      description: A billing price.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingPriceResponse'
    CommerceSubscription:
      description: A commerce subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceSubscription'
    CommercePlan.List:
      description: A list of commerce plans.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedCommercePlanResponse'
    CommercePriceTransition:
      description: A commerce price transition.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommercePriceTransitionResponse'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    BillingPrice.List:
      description: A list of billing prices.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedBillingPriceResponse'
    BillingStatement:
      description: A billing statement.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingStatement'
    responses-CommerceSubscriptionItem:
      description: A commerce subscription item.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-CommerceSubscriptionItem'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    BillingStatement.List:
      description: A list of billing statements.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedBillingStatementResponse'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceSubscriptionItem:
      description: A commerce subscription item.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceSubscriptionItem'
    CommerceCreditBalance:
      description: A payer's credit balance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditBalanceResponse'
  schemas:
    schemas-FeatureResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - name
      - description
      - slug
      - avatar_url
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - feature
        id:
          type: string
          description: Unique identifier for the feature.
        name:
          type: string
          description: The name of the feature.
        description:
          type: string
          description: The description of the feature.
        slug:
          type: string
          description: The URL-friendly slug for the feature.
        avatar_url:
          type: string
          description: The URL of the feature's avatar image.
    PaginatedBillingStatementResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - total_count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingStatement'
          description: Array of billing statements.
        total_count:
          type: integer
          format: int64
          description: Total number of billing statements.
    schemas-CommercePayerResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - instance_id
      - first_name
      - last_name
      - email
      - image_url
      - created_at
      - updated_at
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_payer
        id:
          type: string
          description: Unique identifier for the payer.
        instance_id:
          type: string
          description: Unique identifier for the Clerk instance.
        user_id:
          type: string
          description: User ID for user-type payers.
        first_name:
          type: string
          description: First name of the payer.
        last_name:
          type: string
          description: Last name of the payer.
        email:
          type: string
          description: Email address of the payer.
        organization_id:
          type: string
          description: Organization ID for org-type payers.
        organization_name:
          type: string
          description: Organization name for org-type payers.
        image_url:
          type: string
          description: URL of the payer's image/avatar.
        credits_balance:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: Current credits balance for the payer.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the payer was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the payer was last updated.
    PaginatedBillingPriceResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - total_count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingPriceResponse'
          description: Array of prices.
        total_count:
          type: integer
          format: int64
          description: Total number of prices.
    CommerceTotalsResponse:
      type: object
      additionalProperties: false
      properties:
        subtotal:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        base_fee:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        tax_total:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        grand_total:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        per_unit_totals:
          type: array
          items:
            $ref: '#/components/schemas/CommercePerUnitTotal'
        credits:
          allOf:
          - $ref: '#/components/schemas/CommerceCreditsResponse'
      required:
      - subtotal
      - base_fee
      - tax_total
      - grand_total
    ExtendFreeTrialRequest:
      type: object
      additionalProperties: false
      required:
      - extend_to
      properties:
        extend_to:
          type: string
          format: date-time
          description: 'RFC3339 timestamp to extend the free trial to.

            Must be in the future and not more than 365 days from now.'
          example: '2026-01-08T00:00:00Z'
    AdjustCreditBalanceRequest:
      type: object
      additionalProperties: false
      required:
      - amount
      - action
      - idempotency_key
      properties:
        amount:
          type: integer
          format: int64
          description: The credit amount in cents. Must be greater than zero.
        action:
          type: string
          enum:
          - increase
          - decrease
          description: Whether to increase or decrease the credit balance.
        currency:
          type: string
          description: The currency code (e.g. "USD"). Defaults to USD if not provided.
        idempotency_key:
          type: string
          description: A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry.
        note:
          type: string
          description: An optional note to attach to the ledger entry.
    PaginatedBillingPaymentAttemptResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - total_count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingPaymentAttempt'
          description: Array of billing payment attempts.
        total_count:
          type: integer
          format: int64
          description: Total number of billing payment attempts.
    CommercePerUnitT

# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-billing-api-openapi.yml