ChangeThisFile Billing API

openapi: 3.2.0
info:
  title: ChangeThisFile Billing API
  summary: The conversion API for AI builders.
  description: 'The ChangeThisFile API provides a single, predictable HTTP surface covering 1,000+ supported conversion routes across images, video, audio, documents, spreadsheets, ebooks, archives, and fonts.


    Built for AI builders, automation pipelines, and back-office workflows that need flat, predictable pricing and broad format coverage.


    ## Authentication


    All requests to `/v1/*` (except `/v1/keys/free`) require an API key passed as a bearer token:


    ```

    Authorization: Bearer ctf_sk_xxxxxxxxxxxx

    ```


    Request a free API key by calling `POST /v1/keys/free` with an email address and following the verification link. The free developer tier includes 25 conversions per month shared across REST and authenticated MCP, with a 25 MB file size cap.


    ## Synchronous vs asynchronous


    `POST /v1/convert` is synchronous up to the active plan''s file-size limit and returns the converted file inline. Use `POST /v1/jobs` when you need asynchronous processing.


    `POST /v1/jobs` always queues a job and returns a `job_id` immediately, regardless of file size. Use this when you want predictable async behaviour.


    ## Rate limits


    Every response includes the standard rate-limit headers so you can throttle clients in real time:


    | Header | Description |

    |---|---|

    | `X-RateLimit-Limit` | Requests permitted in the current window |

    | `X-RateLimit-Remaining` | Requests remaining in the current window |

    | `X-RateLimit-Reset` | Unix timestamp when the window resets |


    Exceeding either the per-minute rate limit or your monthly conversion quota returns HTTP `429` with a structured error body.


    ## Errors


    Every error response uses the same envelope:


    ```json

    { "error": { "code": "quota_exceeded", "message": "Monthly conversion quota exceeded.", "details": { "limit": 25, "used": 25 } } }

    ```


    See the `Error` schema for the full list of error codes.'
  version: 1.1.0
  contact:
    name: ChangeThisFile Support
    email: support@changethisfile.com
    url: https://changethisfile.com/contact
  termsOfService: https://changethisfile.com/terms
  license:
    name: Commercial
    url: https://changethisfile.com/terms
servers:
- url: https://changethisfile.com
  description: Production
tags:
- name: Billing
  description: Stripe Checkout and customer portal.
paths:
  /v1/plans:
    get:
      operationId: listPlans
      tags:
      - Billing
      security: []
      summary: List public self-serve plans
      description: Returns the catalogue of self-serve plans (Free, Hobby, Startup, Scale, Growth) with their conversion quotas, file size caps, rate limits, and pricing. The Enterprise plan is not returned — custom contracts are negotiated via support.
      responses:
        '200':
          description: Plan catalogue.
          content:
            application/json:
              schema:
                type: object
                required:
                - plans
                properties:
                  plans:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plan'
  /v1/billing/checkout:
    post:
      operationId: createCheckoutSession
      tags:
      - Billing
      summary: Start a Stripe Checkout session
      description: 'Creates a Stripe Checkout session for upgrading to a paid plan. Returns a hosted URL the caller can redirect the user to.


        Both monthly and annual intervals are supported. Annual plans are billed once a year at a 20% discount versus the monthly rate.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - plan
              - interval
              properties:
                plan:
                  $ref: '#/components/schemas/PlanId'
                interval:
                  type: string
                  enum:
                  - monthly
                  - annual
      responses:
        '200':
          description: Stripe Checkout session created.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/billing/portal:
    post:
      operationId: openBillingPortal
      tags:
      - Billing
      summary: Open the Stripe customer portal
      description: 'Returns a hosted Stripe customer-portal URL for the authenticated user. The portal lets the customer change plan, update payment method, view invoices, and cancel.


        Requires the user to have completed at least one Checkout session (otherwise no Stripe customer exists yet).'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Portal session created.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
        '400':
          description: User does not have a Stripe customer record yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/webhooks/stripe:
    post:
      operationId: stripeWebhook
      tags:
      - Billing
      summary: Stripe webhook receiver (internal)
      description: Internal endpoint that processes Stripe webhook events (`checkout.session.completed`, `invoice.paid`, `customer.subscription.deleted`). Not callable by API users — Stripe POSTs to this URL directly with a signed header.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Raw Stripe event payload.
      parameters:
      - in: header
        name: Stripe-Signature
        required: true
        schema:
          type: string
        description: HMAC-SHA-256 signature of the raw body, generated by Stripe with the configured webhook secret.
      responses:
        '200':
          description: Event processed (or duplicate ignored).
          content:
            application/json:
              schema:
                type: object
                properties:
                  received:
                    type: boolean
        '401':
          description: Invalid signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
              enum:
              - bad_request
              - invalid_api_key
              - quota_exceeded
              - rate_limited
              - file_too_large
              - unsupported_route
              - conversion_failed
              - service_unavailable
              - not_found
              - invalid_signature
            message:
              type: string
              description: Human-readable error message.
            details:
              type: object
              description: Optional structured details (e.g. limit, used, retry_after).
    Plan:
      type: object
      required:
      - id
      - name
      - monthly_price_cents
      - annual_price_cents
      - monthly_conversions
      - max_file_size
      - rate_per_minute
      - overage_cents_per_conversion
      properties:
        id:
          $ref: '#/components/schemas/PlanId'
        name:
          type: string
        monthly_price_cents:
          type:
          - integer
          - 'null'
          description: Monthly price in USD cents. `0` for the free plan, `null` for enterprise.
        annual_price_cents:
          type:
          - integer
          - 'null'
          description: Annual price in USD cents. Reflects the 20% annual discount.
        monthly_conversions:
          type:
          - integer
          - 'null'
          description: Conversions permitted per calendar month. `null` for enterprise (custom).
        max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum file size in bytes.
        rate_per_minute:
          type:
          - integer
          - 'null'
          description: Maximum requests per minute.
        overage_cents_per_conversion:
          type:
          - integer
          - 'null'
          description: Legacy pricing metadata. Runtime conversion above plan quota requires a prepaid conversion-credit balance; no automatic usage overage is charged.
    PlanId:
      type: string
      enum:
      - free
      - hobby
      - startup
      - scale
      - growth
      - enterprise
      description: Self-serve plan identifier. `enterprise` is billed via custom contract — see `/pricing`.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Pass your API key as a bearer token. Get one for free at `POST /v1/keys/free` (no credit card required).

        '