openapi: 3.0.3
info: { title: Extra Charges API, version: 1.0.0 }
servers: [ { url: https://your-domain.com/api/v1 } ]
tags: [ { name: Extra Charges } ]
security: [ { bearerAuth: [] } ]

paths:
  /extra-charges:
    get:
      tags: [Extra Charges]
      summary: List extra charges
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20 }
        - in: query
          name: parent_id
          schema: { type: integer }
        - in: query
          name: status
          schema: { type: string }
        - in: query
          name: school_year
          schema: { type: string }
      responses:
        "200": { description: Extra charges retrieved }
    post:
      tags: [Extra Charges]
      summary: Create an extra charge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [parent_id, invoice_id, amount, description]
              properties:
                parent_id: { type: integer }
                invoice_id: { type: integer }
                title: { type: string }
                description: { type: string }
                amount: { type: number }
                charge_type: { type: string, enum: [add, deduct] }
                due_date: { type: string, format: date }
      responses:
        "201": { description: Extra charge created }

  /extra-charges/{id}:
    get:
      tags: [Extra Charges]
      summary: Get an extra charge
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Extra charge }
        "404": { description: Not found }
    put:
      tags: [Extra Charges]
      summary: Update an extra charge
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string }
                description: { type: string }
                amount: { type: number }
                status: { type: string }
                charge_type: { type: string, enum: [add, deduct] }
                due_date: { type: string, format: date }
      responses:
        "200": { description: Extra charge updated }
    delete:
      tags: [Extra Charges]
      summary: Delete an extra charge
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Extra charge deleted }

  /extra-charges/{id}/apply:
    post:
      tags: [Extra Charges]
      summary: Mark an extra charge as applied
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [invoice_id]
              properties:
                invoice_id: { type: integer }
      responses:
        "200": { description: Extra charge applied }

  /extra-charges/parents:
    get:
      tags: [Extra Charges]
      summary: Get parent options
      responses:
        "200": { description: Parent options list }