Payments Endpoints

API endpoints for managing payment records.

List All Payments

Get all payments across all bills for the selected database.

GET /api/v2/payments
Authorization: Bearer <token>
X-Database: My Bills

Query Parameters:

Parameter	Type	Description
start_date	string	Filter from date (YYYY-MM-DD)
end_date	string	Filter to date (YYYY-MM-DD)
bill_id	integer	Filter by specific bill

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "bill_id": 1,
      "bill_name": "Electric Bill",
      "bill_type": "bill",
      "amount": 150.00,
      "date": "2024-01-15",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Update Payment

Modify an existing payment record.

PUT /api/v2/payments/{id}
Authorization: Bearer <token>
X-Database: My Bills
Content-Type: application/json

{
  "amount": 155.00,
  "date": "2024-01-16"
}

Editable Fields:

Field	Type	Description
amount	number	Payment amount
date	string	Payment date (YYYY-MM-DD)

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "bill_id": 1,
    "amount": 155.00,
    "date": "2024-01-16",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T09:00:00Z"
  }
}

Delete Payment

Remove a payment record.

DELETE /api/v2/payments/{id}
Authorization: Bearer <token>
X-Database: My Bills

Response:

{
  "success": true,
  "message": "Payment deleted"
}

note

Deleting a payment does not automatically adjust the associated bill's due date. If you need to revert the due date, update the bill separately.

Payment Statistics

Get monthly payment statistics.

GET /api/v2/stats/monthly
Authorization: Bearer <token>
X-Database: My Bills

Query Parameters:

Parameter	Type	Description
months	integer	Number of months (default: 6)

Response:

{
  "success": true,
  "data": [
    {
      "month": "2024-01",
      "expenses": 1250.00,
      "income": 3000.00,
      "net": 1750.00,
      "payment_count": 8
    },
    {
      "month": "2023-12",
      "expenses": 1180.00,
      "income": 3000.00,
      "net": 1820.00,
      "payment_count": 7
    }
  ]
}

Error Responses

Payment Not Found

{
  "success": false,
  "error": "Payment not found"
}

Invalid Amount

{
  "success": false,
  "error": "Amount must be a positive number"
}

Invalid Date

{
  "success": false,
  "error": "Invalid date format. Use YYYY-MM-DD"
}