Overview The Bills API enables you to manage household bills, including tracking amounts, due dates, categories, and payment status. It also provides monthly bill aggregations.
Endpoints Get All Bills Retrieves all bills for the authenticated user’s household, ordered by position.
Authentication : RequiredResponse ID of the household this bill belongs to
Name of the bill (e.g., “Electric Bill”)
Bill category (e.g., “Utilities”, “Insurance”)
Position for ordering in the list
Whether the bill has been paid (default: false)
curl -X GET https://your-domain.com/api/bills \ -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response [ { "id" : "clx123abc" , "householdId" : "clx456def" , "name" : "Electric Bill" , "amount" : 125.50 , "dueDate" : "2024-03-25T00:00:00Z" , "category" : "Utilities" , "position" : 0 , "checked" : false , "createdAt" : "2024-03-01T10:00:00Z" , }, { "id" : "clx789ghi" , "householdId" : "clx456def" , "name" : "Internet" , "amount" : 79.99 , "dueDate" : "2024-03-15T00:00:00Z" , "category" : "Utilities" , "position" : 1 , "checked" : true , "createdAt" : "2024-03-01T11:00:00Z" , } ]
Create or Reorder Bills Creates a new bill or reorders existing bills.
Authentication : RequiredRequest Body (Create) Request Body (Reorder) Create Bill
Reorder Bills
Create Bill
curl -X POST https://your-domain.com/api/bills \ -H "Authorization: Bearer YOUR_CLERK_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Car Insurance", "amount": 250.00, "dueDate": "2024-04-01T00:00:00Z", "category": "Insurance" }'
Response (Create) { "id" : "clxnew123" , "householdId" : "clx456def" , "name" : "Car Insurance" , "amount" : 250.00 , "dueDate" : "2024-04-01T00:00:00Z" , "category" : "Insurance" , "position" : 2 , "checked" : false , "createdAt" : "2024-03-15T12:00:00Z" , }
Response (Reorder) Status: 200 OK
Update Bill Updates an existing bill’s details.
Authentication : RequiredRequest Body curl -X POST https://your-domain.com/api/bills/update \ -H "Authorization: Bearer YOUR_CLERK_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "id": "clx123abc", "name": "Electric Bill", "amount": 135.75, "dueDate": "2024-03-28T00:00:00Z", "category": "Utilities" }'
Response Delete Bill Deletes (marks as paid) a bill and creates a payment notification.
Authentication : RequiredRequest Body curl -X POST https://your-domain.com/api/bills/delete \ -H "Authorization: Bearer YOUR_CLERK_TOKEN" \ -H "Content-Type: application/json" \ -d '{"id": "clx123abc"}'
Response { "id" : "clx123abc" , "householdId" : "clx456def" , "name" : "Electric Bill" , "amount" : 125.50 , "dueDate" : "2024-03-25T00:00:00Z" , "category" : "Utilities" , "position" : 0 , "checked" : false , "createdAt" : "2024-03-01T10:00:00Z" , }
When a bill is deleted, a notification is automatically created with:
Type : “bills”Title : “Bill Paid”Body : “You paid: [bill name] for $[amount]“ Get Bills Count Returns the total number of bills for the household.
Authentication : Requiredcurl -X GET https://your-domain.com/api/bills/count \ -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Response Get Monthly Bills Overview Returns aggregated bill data for 5 months (2 past, current, 2 future).
Authentication : RequiredResponse Array of monthly bill summaries
Show Monthly Summary Fields
Month abbreviation (e.g., “Jan”, “Feb”, “Mar”)
Total amount of all bills due in this month
Total amount of checked (paid) bills in this month
curl -X GET https://your-domain.com/api/bills/monthly \ -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response [ { "month" : "Jan" , "total" : 450.25 , "paid" : 450.25 }, { "month" : "Feb" , "total" : 523.00 , "paid" : 523.00 }, { "month" : "Mar" , "total" : 612.50 , "paid" : 205.50 }, { "month" : "Apr" , "total" : 475.00 , "paid" : 0 }, { "month" : "May" , "total" : 0 , "paid" : 0 } ]
The monthly endpoint uses date-fns functions to calculate date ranges and aggregates bills based on their dueDate field. It considers a bill as “paid” if the checked field is true.
Error Responses User is not authenticated
Missing required fields or invalid data
or
500 Internal Server Error
Unexpected server error
Source Code Reference
Main routes: ~/workspace/source/src/app/api/bills/route.ts:19
Count endpoint: ~/workspace/source/src/app/api/bills/count/route.ts:19
Delete endpoint: ~/workspace/source/src/app/api/bills/delete/route.ts:21
Update endpoint: ~/workspace/source/src/app/api/bills/update/route.ts:19
Monthly overview: ~/workspace/source/src/app/api/bills/monthly/route.ts:18