Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/firefly-iii/firefly-iii/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Bills API (also called Subscriptions in some contexts) allows you to manage recurring expenses like rent, utilities, subscriptions, and other regular payments. Firefly III can automatically match transactions to bills based on configured rules.

​
List All Bills

curl -X GET "https://demo.firefly-iii.org/api/v1/bills" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/bills

​
Query Parameters

​
page
integer
Page number for pagination
​
start
string
Start date for paid dates (YYYY-MM-DD)
​
end
string
End date for paid dates (YYYY-MM-DD)

​
Response Fields

​
id
integer
Bill ID
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update
​
name
string
Bill name
​
object_has_currency_setting
boolean
Always true for bills
​
currency_id
string
Currency ID
​
currency_code
string
Currency code
​
currency_name
string
Currency name
​
currency_symbol
string
Currency symbol
​
currency_decimal_places
integer
Decimal places for currency
​
amount_min
string
Minimum expected amount
​
pc_amount_min
string
Minimum amount in primary currency
​
amount_max
string
Maximum expected amount
​
pc_amount_max
string
Maximum amount in primary currency
​
amount_avg
string
Average amount
​
pc_amount_avg
string
Average amount in primary currency
​
date
string
Bill start date (ISO 8601)
​
end_date
string
Bill end date (ISO 8601)
​
extension_date
string
Extension date (ISO 8601)
​
repeat_freq
string
Repeat frequency: weekly, monthly, quarterly, half-year, yearly
​
skip
integer
Number of periods to skip (0-31)
​
active
boolean
Whether the bill is active
​
order
integer
Display order
​
notes
string
Bill notes
​
object_group_id
string
Object group ID if bill is in a group
​
object_group_order
integer
Order within object group
​
object_group_title
string
Object group title
​
paid_dates
array
Array of dates when bill was paid
​
pay_dates
array
Array of expected payment dates
​
next_expected_match
string
Next expected match date (ISO 8601)
​
next_expected_match_diff
string
Human-readable time until next match

​
Create Bill

curl -X POST "https://demo.firefly-iii.org/api/v1/bills" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Netflix Subscription",
    "amount_min": "15.00",
    "amount_max": "15.00",
    "currency_code": "USD",
    "date": "2024-01-15",
    "repeat_freq": "monthly",
    "skip": 0,
    "active": true,
    "notes": "Streaming subscription"
  }'
Endpoint: POST /v1/bills

​
Request Body

​
name
string
required
Bill name (1-255 characters, must be unique)
​
amount_min
string
required
Minimum expected amount (positive number)
​
amount_max
string
required
Maximum expected amount (must be ≥ amount_min)
​
currency_id
integer
Currency ID (must exist in transaction_currencies)
​
currency_code
string
Currency code (3-51 characters, must exist)
​
date
string
required
Bill start date (YYYY-MM-DD, after 1970-01-02, before 2038-01-17)
​
end_date
string
Bill end date (must be after date)
​
extension_date
string
Extension date (must be after date)
​
repeat_freq
string
required
Repeat frequency: weekly, monthly, quarterly, half-year, yearly
​
skip
integer
default:"0"
Number of periods to skip (0-31)
​
active
boolean
default:"true"
Whether the bill is active
​
order
integer
Display order
​
notes
string
Bill notes (max 32,768 characters)
​
object_group_id
integer
Object group ID to associate bill with
​
object_group_title
string
Object group title
Matching Transactions:Firefly III will automatically attempt to match transactions to bills based on:
  • Amount falling within min/max range
  • Transaction date matching expected payment schedule
  • Description or account name patterns

​
Get Bill by ID

curl -X GET "https://demo.firefly-iii.org/api/v1/bills/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/bills/{id} Returns the same response fields as the List endpoint.

​
Update Bill

curl -X PUT "https://demo.firefly-iii.org/api/v1/bills/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Netflix Premium",
    "amount_min": "17.99",
    "amount_max": "17.99",
    "notes": "Upgraded to premium plan"
  }'
Endpoint: PUT /v1/bills/{id} Accepts the same parameters as Create Bill. All fields are optional.

​
Delete Bill

curl -X DELETE "https://demo.firefly-iii.org/api/v1/bills/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: DELETE /v1/bills/{id} Deletes the bill. Associated transactions will no longer be linked to this bill.
Deleting a bill removes the bill association from transactions but does not delete the transactions themselves.

​
Get Bill Attachments

Endpoint: GET /v1/bills/{id}/attachments Returns all attachments for this bill.

​
Get Bill Rules

Endpoint: GET /v1/bills/{id}/rules Returns all rules associated with this bill.

​
Get Bill Transactions

Endpoint: GET /v1/bills/{id}/transactions Returns all transactions matched to this bill.

​
Query Parameters for Transactions

​
start
string
Start date (YYYY-MM-DD)
​
end
string
End date (YYYY-MM-DD)

​
Subscriptions Endpoints

The /v1/subscriptions endpoints are aliases for /v1/bills endpoints and work identically:
  • GET /v1/subscriptions - List all subscriptions
  • POST /v1/subscriptions - Create subscription
  • GET /v1/subscriptions/{id} - Get subscription by ID
  • PUT /v1/subscriptions/{id} - Update subscription
  • DELETE /v1/subscriptions/{id} - Delete subscription
  • GET /v1/subscriptions/{id}/attachments - Get subscription attachments
  • GET /v1/subscriptions/{id}/rules - Get subscription rules
  • GET /v1/subscriptions/{id}/transactions - Get subscription transactions

Build docs developers (and LLMs) love

Get started for freeTalk to us