GroundRoute AI Console Billing API

openapi: 3.2.0
info:
  title: GroundRoute Console Billing API
  version: 0.3.0
tags:
- name: console-billing
paths:
  /console/billing/checkout:
    post:
      tags:
      - console-billing
      summary: Buy Credits
      description: 'Create a Stripe Checkout Session to BUY prepaid credits. The balance is added on the

        checkout.session.completed webhook / the synchronous confirm — idempotent, not here.'
      operationId: buy_credits_console_billing_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Buy Credits Console Billing Checkout Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/billing/topup:
    post:
      tags:
      - console-billing
      summary: Topup Saved Card
      description: 'One-click top-up: charge the card ON FILE off-session (no Checkout re-entry) and credit the

        balance. Response shape for #5:

        • success → {"ok": true, "balance_usd": }

        • cannot one-click (no card, OR off-session charge needs SCA/3DS / was declined) →

        {"needs_checkout": true, "checkout_url": } — a Checkout Session for the same amount is

        created here so the frontend just redirects (no second round-trip).

        Credit is keyed on the PaymentIntent id (same ref as the webhook + auto-top-up) → no double

        credit.'
      operationId: topup_saved_card_console_billing_topup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Topup Saved Card Console Billing Topup Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/billing/auto-top-up:
    put:
      tags:
      - console-billing
      summary: Set Auto Topup
      description: 'Configure auto-top-up. Enabling requires a saved card (POST /console/billing/setup-intent

        first); we still store the config but it only fires once a card is on file.'
      operationId: set_auto_topup_console_billing_auto_top_up_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoTopupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Set Auto Topup Console Billing Auto Top Up Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/billing/auto-topup:
    put:
      tags:
      - console-billing
      summary: Set Auto Topup
      description: 'Configure auto-top-up. Enabling requires a saved card (POST /console/billing/setup-intent

        first); we still store the config but it only fires once a card is on file.'
      operationId: set_auto_topup_console_billing_auto_topup_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoTopupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Set Auto Topup Console Billing Auto Topup Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/billing/status:
    get:
      tags:
      - console-billing
      summary: Billing Status
      description: 'Prepaid-credits status for the logged-in tenant: balance, auto-top-up config, recent ledger

        transactions, and whether a card is on file.'
      operationId: billing_status_console_billing_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Status Console Billing Status Get
  /console/billing/setup-intent:
    post:
      tags:
      - console-billing
      summary: Create Setup Intent
      description: 'Return a Stripe SetupIntent client_secret for the frontend card form (card-on-file, no

        charge). Lazily creates + stores the tenant''s Stripe customer if it doesn''t have one yet.'
      operationId: create_setup_intent_console_billing_setup_intent_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Create Setup Intent Console Billing Setup Intent Post
  /console/billing/refresh:
    post:
      tags:
      - console-billing
      summary: Refresh Payment Method
      description: 'Reconcile card-on-file AND prepaid credit SYNCHRONOUSLY from Stripe — no webhook dependence.

        Called after `confirmCardSetup` in onboarding AND on the Settings/Connect page load

        (self-heal a user whose webhook was missed). Sets `payment_method_on_file` when Stripe reports a

        card (additive — never un-set on an empty list, to avoid a just-detached-card race) and credits

        any PAID Checkout Sessions not yet applied (idempotent on the session id → no double-credit with

        the webhook). Returns the resulting billing state for the UI.'
      operationId: refresh_payment_method_console_billing_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Refresh Payment Method Console Billing Refresh Post
  /console/billing/checkout/confirm:
    post:
      tags:
      - console-billing
      summary: Confirm Checkout
      description: 'Synchronously credit a completed Checkout — called on the Stripe `success_url` return with

        `session_id` — so a purchase lands WITHOUT waiting on webhook delivery. Verifies the session is

        PAID and belongs to THIS tenant''s Stripe customer (403 on a foreign session), credits its

        amount_total, idempotent on the session id (so the webhook can''t double-credit).'
      operationId: confirm_checkout_console_billing_checkout_confirm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutConfirmRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Confirm Checkout Console Billing Checkout Confirm Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AutoTopupRequest:
      properties:
        enabled:
          type: boolean
          title: Enabled
        threshold_usd:
          type: number
          maximum: 10000.0
          minimum: 0.0
          title: Threshold Usd
        topup_amount_usd:
          type: number
          maximum: 10000.0
          minimum: 0.0
          title: Topup Amount Usd
      type: object
      required:
      - enabled
      - threshold_usd
      - topup_amount_usd
      title: AutoTopupRequest
    CheckoutConfirmRequest:
      properties:
        session_id:
          type: string
          maxLength: 255
          minLength: 1
          title: Session Id
      type: object
      required:
      - session_id
      title: CheckoutConfirmRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TopupRequest:
      properties:
        amount_usd:
          type: number
          maximum: 10000.0
          minimum: 1.0
          title: Amount Usd
      type: object
      required:
      - amount_usd
      title: TopupRequest
    CheckoutRequest:
      properties:
        amount_usd:
          type: number
          maximum: 10000.0
          exclusiveMinimum: 0.0
          title: Amount Usd
      type: object
      required:
      - amount_usd
      title: CheckoutRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError