{
  "openapi": "3.1.0",
  "info": {
    "title": "Reditus API - Rewards",
    "description": "API specification for managing rewards in Reditus reward programs.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.getreditus.com/api"
    }
  ],
  "paths": {
    "/v1/rewards": {
      "get": {
        "summary": "List Rewards",
        "description": "Retrieve a paginated list of rewards",
        "parameters": [
          {
            "name": "state_eq",
            "in": "query",
            "schema": { "type": "string", "description": "Filter by state" }
          },
          {
            "name": "advocate_id_eq",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Filter by advocate ID (UUID) or advocate UID"
            }
          },
          {
            "name": "lead_id_eq",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Filter by lead ID"
            }
          },
          {
            "name": "created_at_lt",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Created before (e.g. \"2022-12-24%2012:47:45%20+0200\")"
            }
          },
          {
            "name": "created_at_gt",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Created after (e.g. \"2021-11-23%2012:47:45%20+0200\")"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "description": "Page number" }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 50,
              "description": "Records to be displayed per page"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RewardListResponse"
                }
              }
            }
          }
        },
        "security": [{ "BearerAuth": [] }]
      }
    },
    "/v1/rewards/{id}": {
      "put": {
        "summary": "Mark Reward as Paid",
        "description": "Set the reward's state to 'paid'",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Reward ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RewardUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reward updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RewardResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid state: reward must be in 'pending' state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRewardNotPendingError"
                }
              }
            }
          },
          "404": {
            "description": "Reward not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRewardNotFoundError"
                }
              }
            }
          }
        },
        "security": [{ "BearerAuth": [] }]
      }
    }
  },
  "components": {
    "schemas": {
      "RewardListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Reward" }
          },
          "meta": {
            "type": "object",
            "properties": {
              "pagination": {
                "type": "object",
                "properties": {
                  "page": { "type": "integer" },
                  "per_page": { "type": "integer" },
                  "has_more": { "type": "boolean" }
                }
              }
            }
          }
        }
      },
      "RewardResponse": {
        "type": "object",
        "properties": {
          "data": { "$ref": "#/components/schemas/Reward" }
        }
      },
      "Reward": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string" },
          "attributes": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "advocate_id": { "type": "string" },
              "advocate_uid": { "type": "string" },
              "lead_id": { "type": "string" },
              "lead_email": { "type": "string" },
              "amount": {
                "type": "integer",
                "description": "Amount in cents (e.g., 1000 = $10.00)"
              },
              "currency": { "type": "string" },
              "state": { "type": "string" },
              "created_at": { "type": "integer" },
              "updated_at": { "type": "integer" }
            }
          }
        }
      },
      "RewardUpdateRequest": {
        "type": "object",
        "required": ["state"],
        "properties": {
          "state": {
            "type": "string",
            "enum": ["paid"],
            "description": "New state to set (currently only 'paid' is supported)"
          }
        }
      },
      "ErrorRewardNotPendingError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "details": {
                  "type": "string",
                  "example": "Reward must be in 'pending' state"
                }
              }
            }
          }
        }
      },
      "ErrorRewardNotFoundError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "details": {
                  "type": "string",
                  "example": "Reward not found"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}