Clerk Checkouts API

openapi: 3.2.0
info:
  title: Clerk Frontend Checkouts API
  version: v1
  description: 'The Clerk REST Frontend API, meant to be accessed from a browser or native environment.


    This is a Form Based API and all the data must be sent and formatted according to the `application/x-www-form-urlencoded` content type.


    ### 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. `2021-02-05`. For more information, please see [Clerk API Versions](https://clerk.com/docs/backend-requests/versioning/overview).


    ### Using the Try It Console


    The `Try It` feature of the docs only works for **Development Instances** when using the `DevBrowser` security scheme.

    To use it, first generate a dev instance token from the `/v1/dev_browser` endpoint.


    Please see https://clerk.com/docs for more information.'
  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 Team
    url: https://clerk.com/support
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/javascript/blob/main/LICENSE
servers:
- url: https://{domain}.clerk.accounts.dev
  variables:
    domain:
      default: example-destined-camel-13
      description: Your Development Instance Frontend API Domain.
security:
- {}
- DevBrowser: []
- ProductionBrowser: []
- ProductionNativeApp: []
  ProductionNativeFlag: []
tags:
- name: Checkouts
  description: Used to interact with the checkout flow.
paths:
  /v1/me/billing/checkouts:
    post:
      operationId: CreateUserBillingCheckout
      x-speakeasy-group: billing
      x-speakeasy-name-override: createUserCheckout
      tags:
      - Checkouts
      summary: Create Billing Checkout
      description: Creates a new billing checkout for the current user.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                plan_id:
                  type: string
                  description: The ID of the plan to checkout
                plan_period:
                  type: string
                  enum:
                  - month
                  - annual
                  description: The billing period for the plan
                  default: month
                org_id:
                  type:
                  - string
                  - 'null'
                  description: Organization ID (if creating org checkout)
                payment_method_id:
                  type:
                  - string
                  - 'null'
                  description: Payment method ID to use
              required:
              - plan_id
              - plan_period
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingCheckout'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /v1/me/billing/checkouts/{checkoutID}:
    get:
      operationId: GetUserBillingCheckout
      x-speakeasy-group: billing
      x-speakeasy-name-override: getUserCheckout
      tags:
      - Checkouts
      summary: Get Billing Checkout
      description: Returns a billing checkout for the current user.
      parameters:
      - name: checkoutID
        in: path
        description: The ID of the checkout
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingCheckout'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /v1/me/billing/checkouts/{checkoutID}/confirm:
    patch:
      operationId: ConfirmUserBillingCheckout
      x-speakeasy-group: billing
      x-speakeasy-name-override: confirmUserCheckout
      tags:
      - Checkouts
      summary: Confirm Billing Checkout
      description: Confirms a billing checkout for the current user.
      parameters:
      - name: checkoutID
        in: path
        description: The ID of the checkout to confirm
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                payment_method_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the payment method to use for this checkout
                gateway:
                  type:
                  - string
                  - 'null'
                  description: The payment gateway to use (e.g., stripe)
                payment_token:
                  type:
                  - string
                  - 'null'
                  description: A payment token for processing the payment
                use_test_card:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to use a test card for payment processing
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingCheckout'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /v1/organizations/{organizationID}/billing/checkouts:
    post:
      operationId: CreateOrganizationBillingCheckout
      x-speakeasy-group: billing
      x-speakeasy-name-override: createOrganizationCheckout
      tags:
      - Checkouts
      summary: Create Organization Billing Checkout
      description: Creates a new billing checkout for the organization.
      parameters:
      - name: organizationID
        in: path
        description: The ID of the organization
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                plan_id:
                  type: string
                  description: The ID of the plan to checkout
                plan_period:
                  type: string
                  enum:
                  - month
                  - annual
                  description: The billing period for the plan
                  default: month
                payment_method_id:
                  type:
                  - string
                  - 'null'
                  description: Payment method ID to use
              required:
              - plan_id
              - plan_period
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingCheckout'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}:
    get:
      operationId: GetOrganizationBillingCheckout
      x-speakeasy-group: billing
      x-speakeasy-name-override: getOrganizationCheckout
      tags:
      - Checkouts
      summary: Get Organization Billing Checkout
      description: Returns a billing checkout for the organization.
      parameters:
      - name: organizationID
        in: path
        description: The ID of the organization
        required: true
        schema:
          type: string
      - name: checkoutID
        in: path
        description: The ID of the checkout
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingCheckout'
        '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'
  /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm:
    patch:
      operationId: ConfirmOrganizationBillingCheckout
      x-speakeasy-group: billing
      x-speakeasy-name-override: confirmOrganizationCheckout
      tags:
      - Checkouts
      summary: Confirm Organization Billing Checkout
      description: Confirms a billing checkout for the organization.
      parameters:
      - name: organizationID
        in: path
        description: The ID of the organization
        required: true
        schema:
          type: string
      - name: checkoutID
        in: path
        description: The ID of the checkout to confirm
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                payment_method_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the payment method to use for this checkout
                gateway:
                  type:
                  - string
                  - 'null'
                  description: The payment gateway to use (e.g., stripe)
                payment_token:
                  type:
                  - string
                  - 'null'
                  description: A payment token for processing the payment
                use_test_card:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to use a test card for payment processing
      responses:
        '200':
          $ref: '#/components/responses/Client.BillingCheckout'
        '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'
components:
  schemas:
    BillingPlanUnitPriceTier:
      type: object
      additionalProperties: false
      properties:
        starts_at_block:
          type: integer
          format: int64
          description: Start block (inclusive) for this tier
        ends_after_block:
          type:
          - integer
          - 'null'
          format: int64
          description: End block (inclusive) for this tier; null means unlimited
        fee_per_block:
          $ref: '#/components/schemas/BillingMoneyResponse'
          description: Price charged per block in this tier
      required:
      - starts_at_block
      - fee_per_block
    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:
          type:
          - string
          - 'null'
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type:
            - object
            - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        attempts:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.Link:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_email_link
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - email_link
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        verified_at_client:
          type: string
      required:
      - status
      - strategy
      - expire_at
    Client.Passkey:
      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:
          - passkey
        name:
          type: string
        last_used_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Unix timestamp of when the passkey was last used.

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

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

            '
      required:
      - id
      - object
      - name
      - verification
    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
          - 'null'
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        default:
          type: boolean
      required:
      - strategy
    Stubs.Verification.BackupCode:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_backup_code
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - backup_code
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    BillingSubscriptionCreditResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/BillingMoneyResponse'
          description: Credit amount with formatting
        cycle_days_remaining:
          type: integer
          format: int64
          description: Number of days remaining in the billing cycle
        cycle_days_total:
          type: integer
          format: int64
          description: Total number of days in the billing cycle
        cycle_remaining_percent:
          type: number
          format: double
          description: Percentage of the billing cycle remaining
      required:
      - amount
      - cycle_days_remaining
      - cycle_days_total
      - cycle_remaining_percent
    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
          - 'null'
          description: User ID for user-type payers
        first_name:
          type:
          - string
          - 'null'
          description: First name of the payer (only set when user_id isn't null)
        last_name:
          type:
          - string
          - 'null'
          description: Last name of the payer (only set when user_id isn't null)
        email:
          type:
          - string
          - 'null'
          format: email
          description: Email address of the payer (only set when user_id isn't null)
        organization_id:
          type:
          - string
          - 'null'
          description: Organization ID for org-type payers
        organization_name:
          type:
          - string
          - 'null'
          description: Organization name for org-type payers (only set when organization_id isn't null)
        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.FromOauth:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_from_oauth
        status:
          type: string
          enum:
          - verified
          - unverified
        strategy:
          type: string
          enum:
          - from_oauth_apple
          - from_oauth_google
          - from_oauth_mock
          - from_oauth_custom_mock
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Token:
      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:
          - token
        jwt:
          type: string
          description: 'String representing the encoded JWT value.

            '
      required:
      - object
      - jwt
    Stubs.Verification.Admin:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_admin
        status:
          type: string
          enum:
          - verified
          - unverified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - admin
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    BillingCreditsResponse:
      type: object
      additionalProperties: false
      properties:
        proration:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/BillingProrationCreditDetail'
          description: Proration credit details from unused subscription time
        payer:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/BillingPayerCreditResponse'
          description: Payer credit details from the payer's credit balance
        total:
          $ref: '#/components/schemas/BillingMoneyResponse'
          description: Total credits applied
      required:
      - proration
      - payer
      - total
    BillingPlan:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: String representing the object's type
          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/BillingFee'
          description: The monthly fee for this plan
        annual_monthly_fee:
          allOf:
          - $ref: '#/components/schemas/BillingFee'
          description: The monthly equivalent when billed annually
        annual_fee:
          allOf:
          - $ref: '#/components/schemas/BillingFee'
          description: The annual fee for this plan
        description:
          type:
          - string
          - 'null'
          description: The description of the plan
        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
          - 'null'
          description: The URL of the plan's avatar image
        free_trial_enabled:
          type: boolean
          description: Whether free trial is enabled for this plan
        free_trial_days:
          type:
          - integer
          - 'null'
          description: Number of free trial days for this plan
        unit_prices:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlanUnitPrice'
          description: Per-unit pricing tiers for this plan (for example, seats)
        features:
          type: array
          description: The features included in this plan
          items:
            type: object
            properties:
              object:
                type: string
                enum:
                - feature
                description: String representing the object's type
              id:
                type: string
                description: Unique identifier for the feature
              name:
                type: string
                description: Name of the feature
              description:
                type:
                - string
                - 'null'
                description: Description of the feature
              slug:
                type: string
                description: URL-friendly representation of the feature's name
              avatar_url:
                type:
                - string
                - 'null'
                description: URL for an image to represent the feature
            required:
            - object
            - id
            - name
            - description
            - slug
            - avatar_url
      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
    ExternalAccountWithVerification:
      type: object
      additionalProperties: true
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - external_account
          - facebook_account
          - google_account
        id:
          type: string
        provider:
          type: string
        identification_id:
          type: string
        provider_user_id:
          description: The unique ID of the user in the external provider's system
          type: string
        approved_scopes:
          type: string
        email_address:
          type: string
        email_address_verified:
          type:
          - boolean
          - 'null'
          description: 'Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified

            '
        first_name:
          type: string
        last_name:
          type: string
        avatar_url:
          type: string
          deprecated: true
          description: Please use `image_url` instead
        image_url:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
        public_metadata:
          type: object
          additionalProperties: true
        label:
          type:
          - string
          - 'null'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

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

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/verification_oauth'
          - $ref: '#/components/schemas/verification_google_one_tap'
          discriminator:
            propertyName: object
      required:
      - object
      - id
      - provider
      - identification_id
      - provider_user_id
      - approved_scopes
      - email_address
      - first_name
      - last_name
      - public_metadata
      - created_at
      - updated_at
      - verification
    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
          - 'null'
          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
    Client.OrganizationMembership:
      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:
          - organization_membership
        public_metadata:
          type: object
          additionalProperties: true
        role:
          type: string
        role_name:
          type: string
        permissions:
          type:
          - array
          - 'null'
          items:
            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.
        organization:
          $ref: '#/components/schemas/Client.Organization'
        public_user_data:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Client.PublicUserData'
      required:
      - object
      - id
      - public_metadata
      - role
      - role_name
      - permissions
      - created_at
      - updated_at
      - organization
    Client.PublicUserData:
      type: object
      additionalProperties: false
      properties:
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        image_url:
          type:
          - string
          - 'null'
        has_image:
          type: boolean
        identifier:
          type: string
        profile_image_url:
          type:
          - string
          - 'null'
          deprecated: true
          description: Use `image_url` instead.
        user_id:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        banned:
          type: boolean
      required:
      - first_name
      - last_name
      - identifier
      - has_image
    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
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/ClerkError'
        expire_at:
          type: integer
        attempts:
          type:
          - integer
          - 'null'
        verified_at_client:
          type:
          - string
          - 'null'
      required:
      - status
      - strategy
      - attempts
      - expire_at
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array

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