Bills Endpoints

API endpoints for managing bills.

List Bills

Get all bills for the selected database.

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

Query Parameters:

Parameter	Type	Description
include_archived	boolean	Include archived bills
type	string	Filter by "bill" or "deposit"
account	string	Filter by account name

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Electric Bill",
      "amount": 150.00,
      "due_date": "2024-01-15",
      "frequency": "monthly",
      "type": "bill",
      "account": "Utilities",
      "url": "https://power.example.com",
      "notes": "Account #12345",
      "auto_pay": false,
      "draft": false,
      "archived": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Single Bill

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

Create Bill

POST /api/v2/bills
Authorization: Bearer <token>
X-Database: My Bills
Content-Type: application/json

{
  "name": "Netflix",
  "amount": 15.99,
  "due_date": "2024-01-20",
  "frequency": "monthly",
  "type": "bill",
  "account": "Subscriptions",
  "url": "https://netflix.com",
  "notes": "",
  "auto_pay": true,
  "draft": false
}

Required Fields:

• name - Bill name
• amount - Payment amount
• due_date - Next due date (YYYY-MM-DD)
• frequency - One of: weekly, biweekly, monthly, quarterly, semiannual, annual
• type - "bill" or "deposit"

Update Bill

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

{
  "name": "Netflix Premium",
  "amount": 22.99
}

Only include fields you want to update.

Archive Bill

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

This archives the bill (soft delete). The bill can be restored later.

Unarchive Bill

POST /api/v2/bills/{id}/unarchive
Authorization: Bearer <token>
X-Database: My Bills

Permanent Delete

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

warning

This permanently deletes the bill and all associated payment history. This cannot be undone.

Record Payment

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

{
  "amount": 150.00,
  "date": "2024-01-15",
  "advance_due": true
}

Parameters:

Field	Type	Default	Description
amount	number	required	Payment amount
date	string	today	Payment date (YYYY-MM-DD)
advance_due	boolean	true	Advance due date to next cycle

Get Bill Payments

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

Response:

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