openapi: 3.1.0
info:
  title: Quub Exchange - Fees & Billing API
  version: 2.0.0
  license:
    name: Proprietary
    url: https://quub.exchange/license
  description:
    "Manage organization fee schedules, invoices, rebates, and billing operations.

    "
servers:
  - url: https://api.quub.exchange/v1
    description: Production API
paths:
  /orgs/{orgId}/fees/schedules:
    get:
      summary: Get fee schedules
      operationId: listFeeSchedules
      tags:
        - Fee Schedules
      description: Retrieve all applicable fee schedules for the organization.
      security:
        - oauth2:
            - read:fees
        - apiKey: []
      parameters:
        - $ref: ./common/components.yaml#/components/parameters/orgId
        - $ref: ./common/components.yaml#/components/parameters/orgIdHeader
        - name: type
          in: query
          description: Filter by fee type
          schema:
            type: string
            enum:
              - TRADING
              - WITHDRAWAL
              - DEPOSIT
              - NETWORK
              - SERVICE
        - $ref: ./common/pagination.yaml#/components/parameters/cursor
        - $ref: ./common/pagination.yaml#/components/parameters/limit
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: List of fee schedules
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/FeeSchedule"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /orgs/{orgId}/billing/invoices:
    get:
      summary: List invoices
      operationId: listInvoices
      tags:
        - Invoices
      description: Retrieve a paginated list of invoices for an organization.
      security:
        - oauth2:
            - read:fees
        - apiKey: []
      parameters:
        - $ref: ./common/components.yaml#/components/parameters/orgId
        - $ref: ./common/components.yaml#/components/parameters/orgIdHeader
        - $ref: ./common/pagination.yaml#/components/parameters/cursor
        - $ref: ./common/pagination.yaml#/components/parameters/limit
        - name: status
          in: query
          description: Filter by invoice status
          schema:
            type: string
            enum:
              - DRAFT
              - ISSUED
              - PAID
              - OVERDUE
              - CANCELLED
        - name: fromDate
          in: query
          description: Return invoices issued after this date
          schema:
            type: string
            format: date
        - name: toDate
          in: query
          description: Return invoices issued before this date
          schema:
            type: string
            format: date
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: List of invoices
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Invoice"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /orgs/{orgId}/billing/invoices/{invoiceId}:
    get:
      summary: Get invoice details
      operationId: getInvoice
      tags:
        - Invoices
      description: Retrieve full details of a specific invoice.
      security:
        - oauth2:
            - read:fees
        - apiKey: []
      parameters:
        - $ref: ./common/components.yaml#/components/parameters/orgId
        - $ref: ./common/components.yaml#/components/parameters/orgIdHeader
        - name: invoiceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: Invoice details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Invoice"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /orgs/{orgId}/billing/rebates:
    get:
      summary: List rebates
      operationId: listRebates
      tags:
        - Rebates
      description: Retrieve all applicable rebates for an organization.
      security:
        - oauth2:
            - read:fees
        - apiKey: []
      parameters:
        - $ref: ./common/components.yaml#/components/parameters/orgId
        - $ref: ./common/components.yaml#/components/parameters/orgIdHeader
        - name: status
          in: query
          description: Filter by rebate status
          schema:
            type: string
            enum:
              - PENDING
              - APPROVED
              - CREDITED
              - REJECTED
        - $ref: ./common/pagination.yaml#/components/parameters/cursor
        - $ref: ./common/pagination.yaml#/components/parameters/limit
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
        "404":
          $ref: ./common/responses.yaml#/components/responses/NotFound
        "429":
          $ref: ./common/responses.yaml#/components/responses/TooManyRequests
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: List of rebates
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Rebate"
components:
  securitySchemes:
    bearerAuth:
      $ref: ./common/components.yaml#/components/securitySchemes/bearerAuth
    oauth2:
      $ref: ./common/components.yaml#/components/securitySchemes/oauth2
    apiKey:
      $ref: ./common/components.yaml#/components/securitySchemes/apiKey
  schemas:
    FeeSchedule:
      type: object
      description: Defines fee structure for an operation type.
      properties:
        id:
          type: string
          format: uuid
        orgId:
          type: string
          format: uuid
        feeType:
          type: string
          enum:
            - TRADING
            - WITHDRAWAL
            - DEPOSIT
            - NETWORK
            - SERVICE
        rate:
          type: number
          format: float
          example: 0.001
        currency:
          type: string
          example: USD
        effectiveDate:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
    Invoice:
      type: object
      description: Represents an organization billing invoice.
      properties:
        id:
          type: string
          format: uuid
        orgId:
          type: string
          format: uuid
        amount:
          type: number
          format: float
        currency:
          type: string
          example: USD
        status:
          type: string
          enum:
            - DRAFT
            - ISSUED
            - PAID
            - OVERDUE
            - CANCELLED
        issueDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        items:
          type: array
          items:
            $ref: "#/components/schemas/InvoiceItem"
        paidAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    InvoiceItem:
      type: object
      description: Line item in an invoice.
      properties:
        description:
          type: string
          example: Trading fees for January
        amount:
          type: number
          format: float
        currency:
          type: string
          example: USD
    Rebate:
      type: object
      description: Represents a rebate or fee credit.
      properties:
        id:
          type: string
          format: uuid
        orgId:
          type: string
          format: uuid
        description:
          type: string
        amount:
          type: number
          format: float
        currency:
          type: string
          example: USD
        status:
          type: string
          enum:
            - PENDING
            - APPROVED
            - CREDITED
            - REJECTED
        effectiveDate:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
tags:
  - name: Fee Schedules
    description: Fee Schedules operations
  - name: Invoices
    description: Invoices operations
  - name: Rebates
    description: Rebates operations