API Bills

API – Bills

Manage subscription bills and recurring payments. All bill endpoints are team-scoped — the active team context must be set before making requests.

Base path: /api/v1/bills

---

Endpoints

Method	Endpoint	Description
GET	/bills	List bills
POST	/bills	Create a bill
GET	/bills/{bill}	Get a single bill
PUT	/bills/{bill}	Update a bill
DELETE	/bills/{bill}	Delete a bill
PATCH	/bills/{bill}/pay	Mark a bill as paid
GET	/bills/upcoming	List upcoming bills

---

GET /bills

List all bills for the active team with optional filtering, sorting, and pagination.

Query Parameters:

Parameter	Type	Description
search	string	Search title/description (or column:value)
status	string	paid · unpaid · pending · cancelled · upcoming
category_id	integer	Filter by category
is_recurring	boolean	true or false
tags	array/string	Filter by one or more tags
sort_by	string	Column to sort by (default: due_date)
sort_direction	string	asc or desc (default: asc)
per_page	integer	Results per page (max: 100, default: 15)

Response 200:

{
  "data": [
    {
      "id": 1,
      "title": "Netflix Subscription",
      "slug": "netflix-subscription",
      "description": "Monthly streaming service",
      "amount": 15.99,
      "due_date": "2026-03-01T00:00:00.000Z",
      "status": "unpaid",
      "is_recurring": true,
      "recurrence_period": "monthly",
      "payment_url": "https://netflix.com/billing",
      "tags": ["entertainment", "subscription"],
      "category": {
        "id": 1,
        "name": "Entertainment"
      }
    }
  ],
  "links": { ... },
  "meta": { ... }
}

Filter examples:

# Unpaid bills sorted by due date
GET /api/v1/bills?status=unpaid&sort_by=due_date&sort_direction=asc

# Search for Netflix in the entertainment category
GET /api/v1/bills?search=Netflix&category_id=1

# All recurring bills
GET /api/v1/bills?is_recurring=true

# Advanced column-level search
GET /api/v1/bills?search=title:Netflix

---

POST /bills

Create a new bill.

Request:

{
  "title": "Netflix Subscription",
  "amount": 15.99,
  "due_date": "2026-03-01",
  "description": "Monthly streaming service",
  "category_id": 1,
  "is_recurring": true,
  "recurrence_period": "monthly",
  "payment_url": "https://netflix.com/billing",
  "tags": ["entertainment", "subscription"],
  "has_trial": false,
  "trial_start_date": "2026-02-01",
  "trial_end_date": "2026-02-28"
}

Field	Type	Required	Description
title	string	Yes	Bill name
amount	numeric	Yes	Bill amount (≥ 0)
due_date	date	Yes	Due date (YYYY-MM-DD)
description	string	No	Additional description
category_id	integer	No	Category ID
is_recurring	boolean	No	Whether the bill recurs
recurrence_period	string	Required if is_recurring	daily · weekly · monthly · yearly
payment_url	string	No	Billing portal URL
tags	array	No	List of tag strings
has_trial	boolean	No	Whether a trial period applies
trial_start_date	date	No	Trial start date
trial_end_date	date	No	Trial end date (must be after trial_start_date)

Response 201:

{
  "success": true,
  "message": "Bill created successfully",
  "data": {
    "id": 1,
    "title": "Netflix Subscription",
    "amount": 15.99,
    "due_date": "2026-03-01T00:00:00.000Z"
  }
}

---

GET /bills/{bill}

Get a single bill by ID or slug, including full relationships (category, transactions, notes).

Response 200:

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Netflix Subscription",
    "slug": "netflix-subscription",
    "amount": 15.99,
    "due_date": "2026-03-01T00:00:00.000Z",
    "status": "unpaid",
    "is_recurring": true,
    "recurrence_period": "monthly",
    "category": { "id": 1, "name": "Entertainment" },
    "transactions": [ ... ],
    "notes": [ ... ]
  }
}

---

PUT /bills/{bill}

Update an existing bill. All fields are optional — only include fields to change.

Request:

{
  "title": "Netflix Premium",
  "amount": 19.99,
  "status": "paid"
}

Field	Type	Description
title	string	Updated title
amount	numeric	Updated amount
due_date	date	Updated due date
status	string	paid · unpaid · pending · cancelled
description	string	Updated description
category_id	integer	Updated category
is_recurring	boolean	Toggle recurrence
recurrence_period	string	Updated recurrence period
payment_url	string	Updated billing URL
tags	array	Replaces all tags

Response 200:

{
  "success": true,
  "message": "Bill updated successfully",
  "data": {
    "id": 1,
    "title": "Netflix Premium",
    "amount": 19.99
  }
}

---

DELETE /bills/{bill}

Permanently delete a bill and all its associated transactions.

Response 200:

{
  "success": true,
  "message": "Bill deleted successfully"
}

---

PATCH /bills/{bill}/pay

Quick action to mark a bill as paid without creating a full transaction record.

Response 200:

{
  "success": true,
  "message": "Bill marked as paid",
  "data": {
    "id": 1,
    "status": "paid"
  }
}

---

GET /bills/upcoming

List upcoming bills — bills due within the next N days.

Query Parameters:

Parameter	Type	Description	Default
days	integer	Number of days to look ahead	7

Response 200:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Netflix Subscription",
      "amount": 15.99,
      "due_date": "2026-04-25T00:00:00.000Z"
    }
  ]
}

---

cURL Examples

TOKEN="YOUR_TOKEN"
BASE="https://bills.msar.me/api/v1"

# List bills
curl "$BASE/bills" -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# Create a bill
curl -X POST "$BASE/bills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Netflix Subscription",
    "amount": 15.99,
    "due_date": "2026-05-01",
    "is_recurring": true,
    "recurrence_period": "monthly",
    "category_id": 1
  }'

# Mark as paid
curl -X PATCH "$BASE/bills/1/pay" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# Upcoming bills (next 14 days)
curl "$BASE/bills/upcoming?days=14" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"