{
  "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.\n"
  },
  "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"
    }
  ]
}