Clerk Billing API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal 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:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    BillingStatement:
      description: A billing statement.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingStatement'
    BillingPrice.List:
      description: A list of billing prices.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedBillingPriceResponse'
    CommercePriceTransition:
      description: A commerce price transition.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommercePriceTransitionResponse'
    CommerceCreditBalance:
      description: A payer's credit balance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditBalanceResponse'
    BillingPrice:
      description: A billing price.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingPriceResponse'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceCreditLedger:
      description: A credit ledger entry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditLedgerResponse'
    responses-CommerceSubscriptionItem:
      description: A commerce subscription item.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-CommerceSubscriptionItem'
    BillingPaymentAttempt.List:
      description: A list of billing payment attempts.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedBillingPaymentAttemptResponse'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceSubscriptionItem:
      description: A commerce subscription item.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceSubscriptionItem'
    BillingStatement.List:
      description: A list of billing statements.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedBillingStatementResponse'
    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'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceSubscriptionItem.List:
      description: A list of commerce subscription items.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedCommerceSubscriptionItemResponse'
  schemas:
    CommerceProrationCreditDetailResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        cycle_days_remaining:
          type: integer
          format: int64
        cycle_days_total:
          type: integer
          format: int64
        cycle_remaining_percent:
          type: number
          format: double
      required:
      - amount
      - cycle_days_remaining
      - cycle_days_total
      - cycle_remaining_percent
    BillingPriceResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - plan_id
      - instance_id
      - currency
      - currency_symbol
      - amount
      - annual_monthly_amount
      - fee
      - annual_monthly_fee
      - is_default
      - created_at
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_price
        id:
          type: string
          description: Unique identifier for the price.
        plan_id:
          type: string
          description: Unique identifier for the associated plan.
        instance_id:
          type: string
          description: Unique identifier for the instance.
        currency:
          type: string
          description: The currency code (e.g., "USD").
        currency_symbol:
          type: string
          description: The currency symbol (e.g., "$").
        amount:
          type: integer
          format: int64
          description: The amount in cents for the price.
        annual_monthly_amount:
          type: integer
          format: int64
          description: The monthly amount in cents when billed annually.
        fee:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
        annual_monthly_fee:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
        description:
          type: string
          nullable: true
          description: The description of the price.
        is_default:
          type: boolean
          description: Whether this price is the default price for its plan.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of creation.
    PriceTransitionRequest:
      type: object
      additionalProperties: false
      required:
      - from_price_id
      - to_price_id
      properties:
        from_price_id:
          type: string
          description: The current price ID of the subscription item.
        to_price_id:
          type: string
          description: The target price ID to transition to.
    CommerceSubscription:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - instance_id
      - status
      - payer_id
      - created_at
      - updated_at
      - active_at
      - past_due_at
      - subscription_items
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_subscription
        id:
          type: string
          description: Unique identifier for the commerce subscription.
        instance_id:
          type: string
          description: The ID of the instance this subscription belongs to.
        status:
          type: string
          description: The current status of the subscription.
          enum:
          - active
          - past_due
          - canceled
          - ended
          - abandoned
          - incomplete
        payer_id:
          type: string
          description: The ID of the payer for this subscription.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of last update.
        active_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (milliseconds) when the subscription became active.
        past_due_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (milliseconds) when the subscription became past due.
        subscription_items:
          type: array
          items:
            $ref: '#/components/schemas/CommerceSubscriptionItem'
          description: Array of subscription items in this subscription.
        next_payment:
          $ref: '#/components/schemas/CommerceSubscriptionNextPayment'
          description: Information about the next scheduled payment.
        eligible_for_free_trial:
          type: boolean
          description: Whether the payer is eligible for a free trial.
    CommerceCreditBalanceResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - balance
      properties:
        object:
          type: string
          description: String representing the object's type. Always "commerce_credit_balance".
        balance:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
          description: The current credit balance. Null when the payer has never had credits.
    PaginatedCommerceSubscriptionItemResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - total_count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CommerceSubscriptionItem'
          description: Array of subscription items.
        total_count:
          type: integer
          format: int64
          description: Total number of subscription items.
    schemas-CommercePayerResponse:
      type: obj

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