Clerk Statements API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Statements 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: Statements
  description: Used to interact with billing statements for users and organizations.
paths:
  /v1/me/billing/statements:
    get:
      operationId: GetUserStatements
      x-speakeasy-group: billing
      x-speakeasy-name-override: listUserStatements
      tags:
      - Statements
      summary: List User Statements
      description: Returns a list of billing statements for the current user.
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - $ref: '#/components/parameters/Paginated'
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingStatementList'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
  /v1/me/billing/statements/{statementID}:
    get:
      operationId: GetUserStatement
      x-speakeasy-group: billing
      x-speakeasy-name-override: getUserStatement
      tags:
      - Statements
      summary: Get User Statement
      description: Returns details of a specific billing statement for the current user.
      parameters:
      - name: statementID
        in: path
        description: The ID of the statement to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingStatement'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /v1/organizations/{organizationID}/billing/statements:
    get:
      operationId: GetOrganizationStatements
      x-speakeasy-group: billing
      x-speakeasy-name-override: getOrganizationStatements
      tags:
      - Statements
      summary: List Organization Statements
      description: Lists all statements for the organization.
      parameters:
      - name: organizationID
        in: path
        description: The ID of the organization
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingGenericArray'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /v1/organizations/{organizationID}/billing/statements/{statementID}:
    get:
      operationId: GetOrganizationStatement
      x-speakeasy-group: billing
      x-speakeasy-name-override: getOrganizationStatement
      tags:
      - Statements
      summary: Get Organization Statement
      description: Gets a specific statement for the organization.
      parameters:
      - name: organizationID
        in: path
        description: The ID of the organization
        required: true
        schema:
          type: string
      - name: statementID
        in: path
        description: The ID of the statement to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingGenericObject'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
components:
  schemas:
    Stubs.Verification.GoogleOneTap:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_google_one_tap
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - google_one_tap
        expire_at:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    BillingPayee:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: String representing the object's type
          enum:
          - commerce_payee
        id:
          type: string
          description: Unique identifier for the payee
        gateway_type:
          type: string
          description: Type of payment gateway
        gateway_external_id:
          type: string
          description: External ID in the payment gateway
        gateway_status:
          type: string
          description: Status of the gateway connection
      required:
      - object
      - id
      - gateway_type
      - gateway_external_id
      - gateway_status
    Stubs.Verification.SAML:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_saml
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - saml
        external_verification_redirect_url:
          nullable: true
          type: string
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type: object
            nullable: true
        expire_at:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Client.BillingGenericArray:
      type: object
      additionalProperties: false
      properties:
        response:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
            total_count:
              type: integer
              format: int64
          required:
          - data
          - total_count
        client:
          type: object
          nullable: true
          allOf:
          - $ref: '#/components/schemas/schemas-Client.Client'
      required:
      - response
      - client
    BillingPlanUnitPrice:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the billable unit (for example, seats)
        block_size:
          type: integer
          format: int64
          description: Number of units included in each pricing block
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlanUnitPriceTier'
          description: Tiered pricing configuration for this unit
      required:
      - name
      - block_size
      - tiers
    Client.EmailAddress:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - email_address
        email_address:
          type: string
        reserved:
          type: boolean
        verification:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Invitation'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
          - $ref: '#/components/schemas/Stubs.Verification.FromOauth'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
        linked_to:
          type: array
          items:
            $ref: '#/components/schemas/Stubs.Identification.Link'
        matches_sso_connection:
          description: 'Indicates whether this email address domain matches an active enterprise connection.

            '
          type: boolean
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
      required:
      - id
      - object
      - email_address
      - verification
      - linked_to
      - reserved
      - created_at
      - updated_at
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    Stubs.SignUpVerification.AdditionalFields:
      type: object
      properties:
        next_action:
          type: string
          enum:
          - needs_prepare
          - needs_attempt
          - ''
        supported_strategies:
          type: array
          items:
            type: string
      required:
      - next_action
      - supported_strategies
    schemas-Client.Session:
      allOf:
      - $ref: '#/components/schemas/schemas-Client.SessionBase'
      - type: object
        properties:
          last_active_organization_id:
            type: string
            nullable: true
          user:
            $ref: '#/components/schemas/Client.User'
          public_user_data:
            type: object
            nullable: true
            allOf:
            - $ref: '#/components/schemas/Client.PublicUserData'
          factor_verification_age:
            type: array
            description: Each item represents the minutes that have passed since the last time a first or second factor were verified.
            items:
              type: integer
          created_at:
            type: integer
            format: int64
            description: Unix timestamp of creation.
            example: 1700690400000
          updated_at:
            type: integer
            format: int64
            description: Unix timestamp of last update.
            example: 1700690400000
        required:
        - last_active_organization_id
        - public_user_data
        - factor_verification_age
        - created_at
        - updated_at
    schemas-Client.SessionBase:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - session
        status:
          type: string
          enum:
          - active
          - revoked
          - ended
          - expired
          - removed
          - abandoned
          - pending
        expire_at:
          type: integer
          format: int64
        abandon_at:
          type: integer
          format: int64
        last_active_at:
          type: integer
          format: int64
        last_active_token:
          type: object
          nullable: true
          allOf:
          - $ref: '#/components/schemas/Token'
        actor:
          type: object
          nullable: true
          additionalProperties: true
        tasks:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Client.SessionTask'
      required:
      - id
      - object
      - status
      - expire_at
      - abandon_at
      - last_active_at
    Stubs.SignInFactor:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum:
          - ticket
          - password
          - email_code
          - email_link
          - phone_code
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
          - totp
          - backup_code
          - oauth_apple
          - oauth_google
          - oauth_facebook
          - oauth_hubspot
          - oauth_github
          - oauth_mock
          - oauth_custom_mock
          - oauth_token_mock
          - saml
          - enterprise_sso
          - reset_password_email_code
          - reset_password_phone_code
          - passkey
          - google_one_tap
        safe_identifier:
          type: string
        enterprise_connection_id:
          type: string
        enterprise_connection_name:
          type: string
        email_address_id:
          type: string
        phone_number_id:
          type: string
        web3_wallet_id:
          type: string
        passkey_id:
          type: string
        primary:
          type: boolean
          nullable: true
        external_verification_redirect_url:
          nullable: true
          type: string
        default:
          type: boolean
      required:
      - strategy
    BillingPerUnitTotal:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the billable unit (for example, seats)
        block_size:
          type: integer
          format: int64
          description: Number of units included in each pricing block
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/BillingPerUnitTotalTier'
          description: Computed totals for each pricing tier
      required:
      - name
      - block_size
      - tiers
    verification_oauth:
      x-speakeasy-name-override: Oauth
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_oauth
        status:
          type: string
          x-speakeasy-unknown-values: allow
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          x-speakeasy-unknown-values: allow
          pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z]+$
        external_verification_redirect_url:
          type: string
        error:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ClerkError'
        expire_at:
          type: integer
        attempts:
          type: integer
          nullable: true
        verified_at_client:
          type: string
          nullable: true
      required:
      - status
      - strategy
      - attempts
      - expire_at
    BillingFee:
      type: object
      additionalProperties: false
      properties:
        amount:
          type: integer
          format: int64
          description: Amount in the smallest currency unit (e.g., cents)
          minimum: 0
        amount_formatted:
          type: string
          description: The formatted amount as a string (e.g., "$49.99")
        currency:
          type: string
          description: The currency code (e.g., "USD")
        currency_symbol:
          type: string
          description: The currency symbol (e.g., "$")
      required:
      - amount
      - amount_formatted
      - currency
      - currency_symbol
    Client.SignUp:
      type: object
      properties:
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - sign_up_attempt
        id:
          type: string
          description: Unique identifier for this sign up.
        status:
          type: string
          enum:
          - abandoned
          - missing_requirements
          - complete
        required_fields:
          type: array
          items:
            type: string
          description: 'List of required fields which need to be supplied to the current sign-up. These fields are mandatory in order for the sign-up to satisfy the attached registration policy and be marked as complete.

            '
        optional_fields:
          type: array
          items:
            type: string
          description: 'List of optional fields which can be supplied to the current sign-up. These fields are not required and their absence does not prevent the sign-up to be marked as complete.

            '
        missing_fields:
          type: array
          items:
            type: string
          description: 'List of the missing fields which still need to be supplied to the current sign-up. These fields are mandatory in order for the sign-up to satisfy the attached registration policy and be marked as complete.

            '
        unverified_fields:
          type: array
          items:
            type: string
          description: 'List of fields which are already supplied to the current sign-up but they need to be verified. Example of such fields are email addresses and phone numbers.

            '
        verifications:
          description: 'Group for all available verifications.

            '
          allOf:
          - $ref: '#/components/schemas/Client.SignUp.Verifications'
        username:
          type: string
          nullable: true
        email_address:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        web3_wallet:
          type: string
          nullable: true
        password_enabled:
          type: boolean
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        unsafe_metadata:
          description: 'Custom JSON that callers can use to store arbitrary values that make sense in the context of the current sign up.

            '
          type: object
          additionalProperties: true
        public_metadata:
          description: 'Custom JSON that can be used to store arbitrary values which will end up in the user''s public metadata. This field can only be populated from the application''s BE. At this point, this can be done via invitations.

            '
          type: object
          additionalProperties: true
        custom_action:
          type: boolean
        external_id:
          type: string
          nullable: true
        created_session_id:
          type: string
          nullable: true
        created_user_id:
          type: string
          nullable: true
        abandon_at:
          type: integer
          format: int64
          description: Unix timestamp at which the sign up will be abandoned.
          example: 1700690400000
        legal_accepted_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp at which the user accepted the legal requirements.
          example: 1700690400000
      required:
      - object
      - id
      - status
      - required_fields
      - optional_fields
      - missing_fields
      - unverified_fields
      - verifications
      - username
      - email_address
      - phone_number
      - web3_wallet
      - password_enabled
      - first_name
      - last_name
      - custom_action
      - external_id
      - created_session_id
      - created_user_id
      - abandon_at
      - legal_accepted_at
    BillingStatementResponseGroup:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: String representing the object's type
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) for the group
        items:
          type: array
          items:
            $ref: '#/components/schemas/BillingPaymentAttempt'
          description: Payment items in this group
      required:
      - object
      - timestamp
      - items
    Client.SessionTask:
      type: object
      properties:
        key:
          type: string
      required:
      - key
    BillingMoneyResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          type: integer
          format: int64
          description: Amount in cents
        amount_formatted:
          type: string
          description: Formatted amount as a string (e.g., "$10.00")
        currency:
          type: string
          description: Currency code (e.g., "USD")
        currency_symbol:
          type: string
          description: Currency symbol (e.g., "$")
      required:
      - amount
      - amount_formatted
      - currency
      - currency_symbol
    BillingPayer:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: String representing the object's type
          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
          nullable: true
        first_name:
          type: string
          description: First name of the payer (only set when user_id isn't null)
          nullable: true
        last_name:
          type: string
          description: Last name of the payer (only set when user_id isn't null)
          nullable: true
        email:
          type: string
          format: email
          description: Email address of the payer (only set when user_id isn't null)
          nullable: true
        organization_id:
          type: string
          description: Organization ID for org-type payers
          nullable: true
        organization_name:
          type: string
          description: Organization name for org-type payers (only set when organization_id isn't null)
          nullable: true
        image_url:
          type: string
          format: uri
          description: URL of the payer's image/avatar
        credits_balance:
          $ref: '#/components/schemas/BillingMoneyResponse'
          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
      required:
      - object
      - id
      - instance_id
      - user_id
      - organization_id
    Stubs.Verification.Password:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_password
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - password
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Client.PhoneNumber:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - phone_number
        phone_number:
          type: string
        reserved_for_second_factor:
          type: boolean
        default_second_factor:
          type: boolean
        reserved:
          type: boolean
        verification:
          nullable: true
          type: object
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
        linked_to:
          type: array
          items:
            $ref: '#/components/schemas/Stubs.Identification.Link'
        backup_codes:
          type: array
          items:
            type: string
          nullable: true
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
      required:
      - id
      - object
      - phone_number
      - verification
      - linked_to
      - reserved
      - created_at
      - updated_at
    Client.SAMLAccount:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - saml_account
        provider:
          type: string
        active:
          type: boolean
        email_address:
          type: string
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        provider_user_id:
          description: The unique ID of the user in the external provider's system
          type: string
          nullable: true
        enterprise_connection_id:
          type: string
          nullable: true
        last_authenticated_at:
          type: integer
          format: int64
          nullable: true
          description: 'Unix timestamp of last authentication.

            '
        public_metadata:
          type: object
          additionalProperties: true
        verification:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
        saml_connection:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.SAMLConnection.SAMLAccount'
      required:
      - id
      - object
      - provider
      - active
      - email_address
      - first_name
      - last_name
      - provider_user_id
      - public_metadata
      - saml_connection
      - verification
    Stubs.Verification.OTP:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_otp
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - phone_code
          - email_code
          - reset_password_email_code
          - reset_password_phone_code
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
      required:
      - status
      - strategy
      - expire_at
    BillingSubscriptionItemNextPayment:
      type: object
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/BillingFee'
          description: Amount for the next payment
        date:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) for the next payment date
        per_unit_totals:
          type: array
          items:
            $ref: '#/components/schemas/BillingPerUnitTotal'
          description: Per-unit total breakdown for the next payment
    schemas-Client.SignIn:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - sign_in_attempt
        id:
          type: string
        status:
          type: string
          enum:
          - abandoned
          - needs_identifier
          - needs_first_factor
          - needs_second_factor
          - needs_client_trust
          - needs_new_password
          - needs_protect_check
          - complete
        supported_identifiers:
          type: array
          description: List of supported identifiers that can be used to sign in.
          items:
            type: string
            enum:
            - email_address
            - phone_number
            - username
            - web3_wallet
            - passkey
        supported_first_factors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Stubs.SignInFactor'
        supported_second_factors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Stubs.SignInFactor'
        first_factor_verification:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Password'
          - $ref: '#/components/schemas/Stubs.Verification.Oauth'
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Web3Signature'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
          - $ref: '#/components/schemas/Stubs.Verification.GoogleOneTap'
        second_factor_verification:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.TOTP'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.BackupCode'
        identifier:
          nullable: true
          type: string
        user_data:
          type: object
          additionalProperties: false
          nullable: true
          properties:
            first_name:
              type: string
              nullable: true
            last_name:
              type: string
              nullable: true
            image_url:
              type: string
            has_image:
              type: boolean
            profile_image_url:
              type: string
              nullable: true
              deprecated: true
              description: Use `image_url` instead.
          required:
          - first_name
          - last_name
          - has_image
        created_session_id:
          nullable: true
          type: string
        abandon_at:
          type: integer
          format: int64
          description: Unix timestamp at which the sign in will be abandoned.
          example: 1700690400000
        client_trust_state:
          type: string
          nullable: true
          description: 'The trust state of the client for this sign-in attempt. - `pending`: The identifier has not been set yet. - `new`: The user has not had a session on this client before. - `known`: The user has had a session on this client before.

            '
          enum:
          - pending
          - new
          - known
      required:
      - object
      - id
      - status
      - supported_identifi

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