openapi: 3.2.0
info:
  title: Karada Billing API
  version: 1.0.0
  description: Spec-Driven API definition for Karada MCP Platform
servers:
- url: https://api.karada.ai
  description: Production API
- url: http://localhost:8080
  description: Local development API
tags:
- name: Billing
paths:
  /api/v1/billing/checkout:
    post:
      summary: Create Paddle checkout session for a team
      operationId: createBillingCheckout
      tags:
      - Billing
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - team_id
              properties:
                team_id:
                  type: string
                  format: uuid
                tier_slug:
                  type: string
                  enum:
                  - gateway_pro
                  - pro
                  default: pro
      responses:
        '200':
          description: Checkout initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkout_url:
                    type: string
                  price_id:
                    type: string
                  custom_data:
                    type: object
  /api/v1/billing/portal:
    get:
      summary: Get Paddle customer portal link to manage subscription
      operationId: getBillingCustomerPortal
      tags:
      - Billing
      security:
      - BearerAuth: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Portal URL generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_portal_url:
                    type: string
  /api/v1/billing/subscription:
    get:
      summary: Retrieve subscription status and tier entitlements for a team
      operationId: getBillingSubscription
      tags:
      - Billing
      security:
      - BearerAuth: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  tier_slug:
                    type: string
                  current_period_end:
                    type: string
                    format: date-time
                  max_mcp_servers:
                    type: integer
                  max_gateways:
                    type: integer
                  enhanced_gateway:
                    type: boolean
                  max_teams:
                    type: integer
  /api/v1/billing/webhook:
    post:
      summary: Paddle webhook notification receiver
      operationId: handlePaddleWebhook
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Webhook received and processed
  /api/v1/billing/upgrade-request:
    post:
      summary: Submit team upgrade request
      operationId: createUpgradeRequest
      tags:
      - Billing
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tier_slug
              properties:
                team_id:
                  type: string
                  format: uuid
                tier_slug:
                  type: string
                notes:
                  type: string
      responses:
        '201':
          description: Upgrade request created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  team_id:
                    type: string
                    format: uuid
                  team_name:
                    type: string
                  user_id:
                    type: string
                    format: uuid
                  user_name:
                    type: string
                  user_email:
                    type: string
                  tier_slug:
                    type: string
                  status:
                    type: string
                  notes:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /api/v1/billing/razorpay/create-subscription:
    post:
      summary: Create Razorpay recurring subscription
      operationId: createRazorpaySubscription
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - team_id
              properties:
                team_id:
                  type: string
                  format: uuid
                tier_slug:
                  type: string
                  enum:
                  - gateway_pro
                  - pro
                  default: pro
                currency:
                  type: string
                  enum:
                  - USD
                  - INR
                  default: USD
      responses:
        '200':
          description: Razorpay subscription created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription_id:
                    type: string
                  plan_id:
                    type: string
                  key_id:
                    type: string
                  currency:
                    type: string
                  amount:
                    type: integer
                  status:
                    type: string
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '500':
          description: Razorpay API error
  /api/v1/billing/razorpay/verify-subscription:
    post:
      summary: Verify Razorpay recurring subscription signature
      operationId: verifyRazorpaySubscription
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - razorpay_payment_id
              - razorpay_subscription_id
              - razorpay_signature
              properties:
                razorpay_payment_id:
                  type: string
                razorpay_subscription_id:
                  type: string
                razorpay_signature:
                  type: string
                team_id:
                  type: string
                  format: uuid
                tier_slug:
                  type: string
      responses:
        '200':
          description: Subscription verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          description: Invalid signature or request format
        '401':
          description: Unauthorized
  /api/v1/billing/razorpay/create-order:
    post:
      summary: Create Razorpay Standard order
      operationId: createRazorpayOrder
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              properties:
                amount:
                  type: integer
                  description: Amount in paise (minimum 100)
                  minimum: 100
                currency:
                  type: string
                  default: INR
                receipt:
                  type: string
      responses:
        '200':
          description: Razorpay order created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: string
                  amount:
                    type: integer
                  currency:
                    type: string
                  status:
                    type: string
        '400':
          description: Invalid amount or input
        '401':
          description: Razorpay credentials unauthorized or missing
        '500':
          description: Razorpay API error
  /api/v1/billing/razorpay/verify-payment:
    post:
      summary: Verify Razorpay payment signature
      operationId: verifyRazorpayPayment
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - razorpay_order_id
              - razorpay_payment_id
              - razorpay_signature
              properties:
                razorpay_order_id:
                  type: string
                razorpay_payment_id:
                  type: string
                razorpay_signature:
                  type: string
                team_id:
                  type: string
                  format: uuid
                tier_slug:
                  type: string
      responses:
        '200':
          description: Payment verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          description: Invalid signature or request format
        '401':
          description: Razorpay credentials unauthorized
  /api/v1/billing/razorpay/webhook:
    post:
      summary: Handle Razorpay asynchronous webhook events
      operationId: handleRazorpayWebhook
      tags:
      - Billing
      parameters:
      - name: X-Razorpay-Signature
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Webhook event processed successfully
        '400':
          description: Bad request
        '401':
          description: Webhook signature verification failed
        '500':
          description: Internal server error
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT