Clerk · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Clerk Frontend Checkouts API

7 actions 7 updates phrasing extends openapi/clerk-com-checkouts-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Clerk's API. It is a proposal applied on top of the contract, not a document Clerk publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 7

$.info

$.paths['/v1/me/billing/checkouts'].post

$.paths['/v1/me/billing/checkouts/{checkoutID}'].get

$.paths['/v1/me/billing/checkouts/{checkoutID}/confirm'].patch

$.paths['/v1/organizations/{organizationID}/billing/checkouts'].post

$.paths['/v1/organizations/{organizationID}/billing/checkouts/{checkoutID}'].get

$.paths['/v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm'].patch

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Frontend Checkouts API
  version: 1.0.0
extends: openapi/clerk-com-checkouts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/v1/me/billing/checkouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a checkout for my own plan
      effect: write
      questions:
      - How do I start checking out a paid plan for myself?
      - Can I choose monthly or annual billing when starting my checkout?
      instructions:
      - text: Start a checkout for plan {plan_id} billed {plan_period} for me.
        slots:
          plan_id: requestBody.plan_id
          plan_period: requestBody.plan_period
      - text: Create my checkout for plan {plan_id} ({plan_period}) with payment method {payment_method_id}.
        slots:
          plan_id: requestBody.plan_id
          plan_period: requestBody.plan_period
          payment_method_id: requestBody.payment_method_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/billing/checkouts/{checkoutID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my checkout
      effect: read
      questions:
      - What is the status and total of the checkout I started?
      - Has my own plan checkout been completed yet?
      instructions:
      - text: Show my checkout {checkoutID}.
        slots:
          checkoutID: path.checkoutID
      - text: Check the status of my checkout {checkoutID}.
        slots:
          checkoutID: path.checkoutID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/billing/checkouts/{checkoutID}/confirm'].patch
  update:
    x-apievangelist-phrasing:
      intent: Confirm and pay for my checkout
      effect: write
      questions:
      - How do I complete my own checkout and pay for the plan?
      - Can I confirm my checkout with a test card in development?
      instructions:
      - text: Confirm my checkout {checkoutID}.
        slots:
          checkoutID: path.checkoutID
      - text: Pay for my checkout {checkoutID} with payment method {payment_method_id}.
        slots:
          checkoutID: path.checkoutID
          payment_method_id: requestBody.payment_method_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationID}/billing/checkouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a checkout for an organization
      effect: write
      questions:
      - How do I start a plan purchase on behalf of my organization?
      - Can an organization checkout use an existing saved payment method?
      instructions:
      - text: Start an organization checkout for {organizationID} on plan {plan_id} billed {plan_period}.
        slots:
          organizationID: path.organizationID
          plan_id: requestBody.plan_id
          plan_period: requestBody.plan_period
      - text: Start a checkout for organization {organizationID} on plan {plan_id} ({plan_period}) with payment method {payment_method_id}.
        slots:
          organizationID: path.organizationID
          plan_id: requestBody.plan_id
          plan_period: requestBody.plan_period
          payment_method_id: requestBody.payment_method_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationID}/billing/checkouts/{checkoutID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's checkout
      effect: read
      questions:
      - What is the status of the checkout my organization started?
      - Has my organization's plan checkout been paid yet?
      instructions:
      - text: Show checkout {checkoutID} for organization {organizationID}.
        slots:
          checkoutID: path.checkoutID
          organizationID: path.organizationID
      - text: Check the status of organization {organizationID} checkout {checkoutID}.
        slots:
          organizationID: path.organizationID
          checkoutID: path.checkoutID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm'].patch
  update:
    x-apievangelist-phrasing:
      intent: Confirm an organization's checkout
      effect: write
      questions:
      - How do I finish paying for my organization's plan checkout?
      - Can I confirm an organization checkout with a payment token from the gateway?
      instructions:
      - text: Confirm checkout {checkoutID} for organization {organizationID}.
        slots:
          checkoutID: path.checkoutID
          organizationID: path.organizationID
      - text: Pay organization {organizationID} checkout {checkoutID} with payment method {payment_method_id}.
        slots:
          organizationID: path.organizationID
          checkoutID: path.checkoutID
          payment_method_id: requestBody.payment_method_id
      method: generated
      generated: '2026-09-26'