openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Organizations 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: Organizations
  description: Organizations are used to group members under a common entity and provide shared access to resources.
  externalDocs:
    url: https://clerk.com/docs/organizations/overview
paths:
  /organizations:
    get:
      operationId: ListOrganizations
      x-speakeasy-group: organizations
      x-speakeasy-name-override: list
      summary: Get a List of Organizations for an Instance
      description: 'This request returns the list of organizations for an instance.

        Results can be paginated using the optional `limit` and `offset` query parameters.

        The organizations are ordered by descending creation date.

        Most recent organizations will be returned first.'
      tags:
      - Organizations
      parameters:
      - in: query
        required: false
        name: include_members_count
        description: Flag to denote whether the member counts of each organization should be included in the response or not.
        schema:
          type: boolean
      - in: query
        required: false
        name: include_missing_member_with_elevated_permissions
        description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.
        schema:
          type: boolean
      - in: query
        required: false
        name: query
        description: 'Returns organizations with ID, name, or slug that match the given query.

          Uses exact match for organization ID and partial match for name and slug.'
        schema:
          type: string
      - in: query
        name: user_id
        description: 'Returns organizations that include any of the specified user IDs as members. Any user IDs not found are ignored.

          For each user ID, the `+` and `-` can be prepended to the ID, which denote whether the

          respective organization should be included or excluded from the result set.'
        schema:
          type: array
          items:
            type: string
        required: false
      - in: query
        name: organization_id
        description: 'Returns organizations with the organization IDs specified. Any organization IDs not found are ignored.

          For each organization ID, the `+` and `-` can be prepended to the ID, which denote whether the

          respective organization should be included or excluded from the result set. Accepts up to 100 organization IDs.

          Example: ?organization_id=+org_1&organization_id=-org_2'
        schema:
          type: array
          items:
            type: string
        required: false
      - in: query
        name: order_by
        description: 'Allows to return organizations in a particular order.

          At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`.

          In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.

          For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`.

          If you don''t use `+` or `-`, then `+` is implied.

          Defaults to `-created_at`.'
        schema:
          type: string
          default: -created_at
        required: false
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/Organizations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: create
      summary: Create an Organization
      description: 'Creates a new organization with the given name for an instance.

        You can specify an optional slug for the new organization.

        If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-".

        Organization slugs must be unique for the instance.

        You can provide additional metadata for the organization and set any custom attribute you want.

        Organizations support private and public metadata.

        Private metadata can only be accessed from the Backend API.

        Public metadata can be accessed from the Backend API, and are read-only from the Frontend API.

        The `created_by` user will see this as their [active organization](https://clerk.com/docs/organizations/overview#active-organization)

        the next time they create a session, presuming they don''t explicitly set a different organization as active before then.'
      tags:
      - Organizations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'The name of the new organization.

                    May not contain URLs or HTML.

                    Max length: 256'
                created_by:
                  type: string
                  description: The ID of the User who will become the administrator for the new organization
                  nullable: true
                private_metadata:
                  type: object
                  description: Metadata saved on the organization, accessible only from the Backend API
                  additionalProperties: true
                  nullable: true
                public_metadata:
                  type: object
                  description: Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API
                  additionalProperties: true
                  nullable: true
                slug:
                  type: string
                  description: 'A slug for the new organization.

                    Can contain only lowercase alphanumeric characters and the dash "-".

                    Must be unique for the instance.

                    This field should only be included when slugs are enabled in the organization settings, refer to our [documentation](https://clerk.com/docs/guides/organizations/overview#organization-slugs).'
                  nullable: true
                max_allowed_memberships:
                  type: integer
                  minimum: 0
                  description: The maximum number of memberships allowed for this organization
                  nullable: true
                created_at:
                  type: string
                  description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                  nullable: true
                role_set_key:
                  type: string
                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
                  nullable: true
              required:
              - name
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}:
    get:
      operationId: GetOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: get
      summary: Retrieve an Organization by ID or Slug
      description: Fetches the organization whose ID or slug matches the provided `id_or_slug` URL query parameter.
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID or slug of the organization
      - in: query
        required: false
        name: include_members_count
        description: Flag to denote whether or not the organization's members count should be included in the response.
        schema:
          type: boolean
      - in: query
        required: false
        name: include_missing_member_with_elevated_permissions
        description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: update
      summary: Update an Organization
      description: Updates an existing organization
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: Metadata saved on the organization, that is visible to both your frontend and backend.
                  additionalProperties: true
                  nullable: true
                private_metadata:
                  type: object
                  description: Metadata saved on the organization that is only visible to your backend.
                  additionalProperties: true
                  nullable: true
                name:
                  type: string
                  description: 'The new name of the organization.

                    May not contain URLs or HTML.

                    Max length: 256'
                  nullable: true
                slug:
                  type: string
                  description: The new slug of the organization, which needs to be unique in the instance
                  nullable: true
                max_allowed_memberships:
                  type: integer
                  minimum: 0
                  description: The maximum number of memberships allowed for this organization
                  nullable: true
                admin_delete_enabled:
                  type: boolean
                  description: If true, an admin can delete this organization with the Frontend API.
                  nullable: true
                created_at:
                  type: string
                  description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                  nullable: true
                role_set_key:
                  type: string
                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/ResourceNotFound'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: delete
      summary: Delete an Organization
      description: 'Deletes the given organization.

        Please note that deleting an organization will also delete all memberships and invitations.

        This is not reversible.


        After the organization is deleted, any user''s active sessions that contain the deleted

        organization will be cleared.'
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization to delete
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /organizations/{organization_id}/metadata:
    patch:
      operationId: MergeOrganizationMetadata
      x-speakeasy-group: organizations
      x-speakeasy-name-override: mergeMetadata
      summary: Merge and Update Metadata for an Organization
      description: 'Update organization metadata attributes by merging existing values with the provided parameters.

        Metadata values will be updated via a deep merge.

        Deep meaning that any nested JSON objects will be merged as well.

        You can remove metadata keys at any level by setting their value to `null`.'
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        description: The ID of the organization for which metadata will be merged or updated
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: 'Metadata saved on the organization, that is visible to both your frontend and backend.

                    The new object will be merged with the existing value.'
                  additionalProperties: true
                private_metadata:
                  type: object
                  description: 'Metadata saved on the organization that is only visible to your backend.

                    The new object will be merged with the existing value.'
                  additionalProperties: true
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/logo:
    put:
      operationId: UploadOrganizationLogo
      x-speakeasy-group: organizations
      x-speakeasy-name-override: uploadLogo
      summary: Upload a Logo for the Organization
      description: 'Set or replace an organization''s logo, by uploading an image file.

        This endpoint uses the `multipart/form-data` request content type and accepts a file of image type.

        The file size cannot exceed 10MB.

        Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.'
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        description: The ID of the organization for which to upload a logo
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                uploader_user_id:
                  type: string
                  description: The ID of the user that will be credited with the image upload.
                file:
                  type: string
                  format: binary
              required:
              - file
      responses:
        '200':
          $ref: '#/components/responses/OrganizationWithLogo'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '413':
          $ref: '#/components/responses/ClerkErrors'
    delete:
      operationId: DeleteOrganizationLogo
      x-speakeasy-group: organizations
      x-speakeasy-name-override: deleteLogo
      summary: Delete the Organization's Logo.
      description: Delete the organization's logo.
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        description: The ID of the organization for which the logo will be deleted.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /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:
      - Organizations
      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:
      - Organizations
      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:
      - Organizations
      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'
components:
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceCreditBalance:
      description: A payer's credit balance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditBalanceResponse'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceCreditLedger:
      description: A credit ledger entry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditLedgerResponse'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Organization:
      description: An organization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Organization'
    Organizations:
      description: A list of organizations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Organizations'
    CommerceSubscription:
      description: A commerce subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceSubscription'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    OrganizationWithLogo:
      description: An organization with a logo URL.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationWithLogo'
  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
    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.
    Organizations:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Organization'
        total_count:
          type: integer
          format: int64
          description: 'Total number of organizations

            '
      required:
      - data
      - total_count
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    CommercePaymentMethodResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - payer_id
      - payment_type
      - gateway
      - gateway_external_id
      - gateway_external_account_id
      - last4
      - status
      - card_type
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_payment_method
        id:
          type: string
          description: Unique identifier for the payment method.
        payer_id:
          type: string
          description: Unique identifier for the payer.
        payment_type:
          type: string
          description: The payment method type.
          enum:
          - card
          - link
        is_default:
          type: boolean
          description: Whether this is the default payment method for the payer.
        gateway:
          type: string
          description: The payment gateway.
        gateway_external_id:
          type: string
          description: External ID in the payment gateway.
        gateway_external_account_id:
          type: string
          nullable: true
          description: External account ID in the payment gateway.
        last4:
          type: string
          description: Last 4 digits of the card (for card payment methods).
          nullable: true
        status:
          type: string
          description: Status of the payment method.
          enum:
          - active
          - disconnected
        wallet_type:
          type: string
          description: Type of wallet (if applicable).
          nullable: true
        card_type:
          type: string
          description: Type of card (if applicable).
          nullable: true
        expiry_year:
          type: integer
          description: Card expiration year (for card payment methods).
          nullable: true
        expiry_month:
          type: integer
          description: Card expiration month (for card payment methods).
          nullable: true
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the payment method was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the payment method was last updated.
        is_removable:
          type: boolean
          description: Whether this payment method can be removed.
    CommercePlanUnitPrice:
      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/CommercePlanUnitPriceTier'
          description: Tiered pricing configuration for this unit
      required:
      - name
      - block_size
      - tiers
    CommercePlanUnitPriceTier:
      type: object
      additionalProperties: false
      properties:
        starts_at_block:
          type: integer
          format: int64
          description: Start block (inclusive) for this tier
        ends_after_block:
          type: integer
          format: int64
          nullable: true
          description: End block (inclusive) for this tier; null means unlimited
        fee_per_block:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: Price charged per block in this tier
      required:
      - starts_at_block
      - fee_per_block
    CommercePerUnitTotal:
      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/CommercePerUnitTotalTier'
          description: Computed totals for each pricing tier
      required:
      - name
      - block_size
      - tiers
    CommercePayerCreditResponse:
      type: object
      additionalProperties: false
      properties:
        remaining_balance:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        applied_amount:
          $ref: '#/components/schemas/CommerceMoneyResponse'
      required:
      - remaining_balance
      - applied_amount
    CommerceSubscriptionItemSeatsResponse:
      type: object
      additionalProperties: false
      properties:
        quantity:
          type: integer
          format: int64
          nullable: true
          description: Seat quantity being billed; null means unlimited
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/CommercePerUnitTotalTier'
          description: Per-unit cost breakdown by pricing tier
      required:
      - quantity
    CommerceSubscriptionCreditResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
          description: Credit amount.
        cycle_remaining_percent:
          type: number
          format: float
          description: Percentage of the billing cycle remaining.
    CommerceCreditsResponse:
      type: object
      additionalProperties: false
      properties:
        proration:
          allOf:
          - $ref: '#/components/schemas/CommerceProrationCreditDetailResponse'
          nullable: true
        payer:
          allOf:
          - $ref: '#/components/schemas/CommercePayerCreditResponse'
          nullable: true
        total:
          $ref: '#/components/schemas/CommerceMoneyResponse'
      required:
      - proration
      - payer
      - total
    DeletedObject:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
        id:
          type: string
        slug:
          type: string
        deleted:
          type: boolean
        external_id:
          type: string
      required:
      - object
      - deleted
    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.
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    OrganizationWithLogo:
      type: object
      allOf:
      - $ref: '#/components/schemas/Organization'
      - type: object
        properties:
          logo_url:
            type: string
            deprecated: true
          image_url:
            type: string
          has_image:
            type: boolean
        required:
        - image_url
        - has_image
    CommercePerUnitTotalTier:
      type: object
      additionalProperties: false
      properties:
        quantity:
          type: integer
          format: int64
          nullable: true
          description: Units billed in this tier; null means unlimited
        fee_per_block:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: Price charged per block in this tier
        total:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: Total charge for this tier
      required:
      - fee_per_block
      - total
    CommerceMoneyResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          type: integer
          format: int64
          description: The amount in cents.
        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
    CommerceCreditLedgerResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - payer_id
      - amount
      - currency
      - source_type
      - source_id
      - created_at
      properties:
        object:
          type: string
          description: String representing the object's type. Always "commerce_credit_ledger".
        id:
          type: string
          description: Unique identifier for the ledger entry.
        payer_id:
          type: string
          description: The ID of the payer whose balance was adjusted.
        amount:
          type: integer
          format: int64
          description: The signed credit amount. Positive for increases, negative for decreases.
        currency:
          type: string
          description: The currency code of the credit adjustment.
        source_type:
          type: string
          description: The type of source that originated the adjustment (e.g. "grant").
        source_id:
          type: string
          description: The ID of the source that originated the adjustment.
        note:
          type: string
          nullable: true
          description: An optional note attached to the ledger entry.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the ledger entry was created.
    CommerceSubscriptionNextPayment:
      type: object
      additionalProperties: false
      required:
      - date
      - amount
      properties:
        date:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of the next payment date.
        amount:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: The amount of the next payment.
    CommercePayerResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - instance_id
      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.
          nullable: true
        first_name:
          type: string
          description: First name of the payer.
          nullable: true
        last_name:
          type: string
          description: Last name of the payer.
          nullable: true
        email:
          type: string
          description: Email address of the payer.
          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.
          nullable: true
        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.
    Organization:
      type: object
      properties:
        object:
          type: string
          enum:
          - organization
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        image_url:
          type: string
        has_image:
          type: boolean
        members_count:
          type: integer
        missing_member_with_elevated_permissions:
          type: boolean
        pending_invitations_count:
          type: integer
        max_allowed_memberships:
          type: integer
        admin_delete_enabled:
          type: boolean
        public_metadata:
          type: object
          additionalProperties: true
        private_metadata:
          type: object
          additionalProperties: true
        created_by:
          type: string
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
        last_active_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last activity.

            '
        role_set_key:
          type: string
          description: 'The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.

            '
          nullable: true
      required:
      - object
      - id
      - name
      - slug
      - has_image
      - max_allowed_memberships
      - admin_delete_enabled
      - public_metadata
      - created_at
      - updated_at
    CommerceSubscriptionItemNextPaymentResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
          description: Amount for the next payment.
        date:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (in milliseconds) for the next payment date.
    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'
          nullable: true
      required:
      - subtotal
      - base_fee
      - tax_total
      - grand_total
    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
          nullable: true
          description: The description of the feature.
        slug:
          type: string
          description: The URL-friendly slug for the feature.
        avatar_url:
          type: string
          nullable: true
          description: The URL of the feature's avatar image.
    CommercePlan:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - name
      - fee
      - annual_monthly_fee
      - annual_fee
      - description
      - product_id
      - is_default
      - is_recurring
      - publicly_visible
      - has_base_fee
      - for_payer_type
      - slug
      - avatar_url
      - free_trial_enabled
      - free_trial_days
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_plan
        id:
          type: string
          description: Unique identifier for the plan.
        name:
          type: string
          description: The name of the plan.
        fee:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
        annual_monthly_fee:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
        annual_fee:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
        description:
          type: string
          description: The description of the plan.
          nullable: true
        product_id:
          type: string
          description: The ID of the product this plan belongs to.
          deprecated: true
        is_default:
          type: boolean
          description: Whether this is the default plan.
        is_recurring:
          type: boolean
          description: Whether this is a recurring plan.
        publicly_visible:
          type: boolean
          description: Whether this plan is publicly visible.
        has_base_fee:
          type: boolean
          description: Whether this plan has a base fee.
        for_payer_type:
          type: string
          description: The payer type this plan is designed for.
        slug:
          type: string
          description: The URL-friendly slug for the plan.
        avatar_url:
          type: string
          description: The URL of the plan's avatar image.
          nullable: true
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureResponse'
          description: The features included in this plan.
        free_trial_enabled:
          type: boolean
          description: Whether free trial is enabled for this plan.
        free_trial_days:
          type: integer
          format: int64
          nullable: true
          description: Number of free trial days for this plan.
        unit_prices:
          type: array
          items:
            $ref: '#/components/schemas/CommercePlanUnitPrice'
          description: Per-unit pricing tiers for this plan (for example, seats)
    CommerceSubscriptionItem:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - instance_id
      - status
      - plan_id
      - plan_period
      - payer_id
      - is_free_trial
      - period_start
      - period_end
      - canceled_at
      - past_due_at
      - ended_at
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_subscription_item
        id:
          type: string
          description: Unique identifier for the subscription item.
        instance_id:
          type: string
          description: Unique identifier for the Clerk instance.
        status:
          type: string
          description: Current status of the subscription item.
          enum:
          - active
          - canceled
          - expired
          - ended
          - past_due
          - upcoming
          - incomplete
          - abandoned
        credit:
          $ref: '#/components/schemas/CommerceSubscriptionCreditResponse'
          description: Credit information (only available in PaymentAttempt events).
        credits:
          allOf:
          - $ref: '#/components/schemas/CommerceCreditsResponse'
          nullable: true
          description: Unified credits breakdown for this subscription item.
        plan_id:
          type: string
          description: Unique identifier for the associated plan.
          nullable: true
        price_id:
          type: string
          description: Unique identifier for the associated price
        plan:
          allOf:
          - $ref: '#/components/schemas/CommercePlan'
          nullable: true
          description: The associated plan.
        plan_period:
          type: string
          description: The billing period for this subscription item.
          enum:
          - month
          - annual
        payment_method:
          $ref: '#/components/schemas/CommercePaymentMethodResponse'
          description: The payment method used for this subscription item.
        lifetime_paid:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: Total amount paid over the lifetime of this subscription item.
        next_payment:
          allOf:
          - $ref: '#/components/schemas/CommerceSubscriptionItemNextPaymentResponse'
          nullable: true
          description: Information about the next payment.
        payer_id:
          type: string
          description: Unique identifier for the payer.
        payer:
          $ref: '#/components/schemas/CommercePayerResponse'
          description: The payer associated with this subscription item.
        is_free_trial:
          type: boolean
          description: Whether this subscription item includes a free trial.
        period_start:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the current period started.
        period_end:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (in milliseconds) when the current period ends.
        proration_date:
          type: string
          format: date
          description: The day the subscription item was prorated from. Only available in some responses.
        canceled_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (in milliseconds) when the subscription item was canceled.
        past_due_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (in milliseconds) when the subscription item became past due.
        ended_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (in milliseconds) when the subscription item ended.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the subscription item was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the subscription item was last updated.
        seats:
          allOf:
          - $ref: '#/components/schemas/CommerceSubscriptionItemSeatsResponse'
          nullable: true
          description: Seat quantity for seat-based billing.
        totals:
          allOf:
          - $ref: '#/components/schemas/CommerceTotalsResponse'
          nullable: true
          description: Totals for this subscription item.
  parameters:
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true