Recurring Transactions API

Overview

The Recurring Transactions API (also called Recurrences) allows you to set up automatic transaction creation based on flexible schedules. Perfect for salary, rent, subscriptions, and any regularly occurring financial activity.

List All Recurring Transactions

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

Endpoint: GET /v1/recurrences

Query Parameters

page

integer

Page number for pagination

Response Fields

string

Recurrence ID

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

type

string

Transaction type: withdrawal, deposit, or transfer

title

string

Recurrence title

description

string

Recurrence description

first_date

string

First occurrence date (ISO 8601)

latest_date

string

Date of last created transaction (ISO 8601)

repeat_until

string

End date for recurrence (ISO 8601)

apply_rules

boolean

Whether to apply rules to created transactions

active

boolean

Whether the recurrence is active

nr_of_repetitions

integer

Number of times to repeat (null for unlimited)

notes

string

Recurrence notes

repetitions

array

Array of repetition schedules

transactions

array

Array of transaction templates

Create Recurring Transaction

curl -X POST "https://demo.firefly-iii.org/api/v1/recurrences" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "withdrawal",
    "title": "Monthly Rent",
    "description": "Apartment rent payment",
    "first_date": "2024-02-01",
    "repeat_until": null,
    "nr_of_repetitions": null,
    "apply_rules": true,
    "active": true,
    "repetitions": [
      {
        "type": "monthly",
        "moment": "1",
        "skip": 0,
        "weekend": 1
      }
    ],
    "transactions": [
      {
        "description": "Rent payment",
        "amount": "1500.00",
        "currency_code": "USD",
        "source_id": "1",
        "destination_name": "Landlord",
        "category_name": "Housing"
      }
    ]
  }'

Endpoint: POST /v1/recurrences

Request Body

type

string

required

Transaction type: withdrawal, deposit, or transfer

title

string

required

Recurrence title (1-255 characters, must be unique)

description

string

Recurrence description (1-32,768 characters)

first_date

string

required

First occurrence date (YYYY-MM-DD)

repeat_until

string

End date (YYYY-MM-DD)

nr_of_repetitions

integer

Number of repetitions (1-31, conflicts with repeat_until)

apply_rules

boolean

default:"true"

Apply transaction rules to created transactions

active

boolean

default:"true"

Whether the recurrence is active

notes

string

Recurrence notes

repetitions

array

required

Array of repetition objects (minimum 1)

transactions

array

required

Array of transaction templates (minimum 1)

Repetition Object Fields

repetitions[].type

string

required

Repetition type: daily, weekly, ndom, monthly, yearly

repetitions[].moment

string

When to trigger (0-10, meaning depends on type)

repetitions[].skip

integer

Periods to skip (0-31)

repetitions[].weekend

integer

Weekend handling: 1=skip to Monday, 2=skip to Friday, 3=skip to next Friday, 4=no adjustment

Transaction Template Fields

transactions[].description

string

required

Transaction description (1-255 characters)

transactions[].amount

string

required

Transaction amount (positive number)

transactions[].foreign_amount

string

Foreign currency amount

transactions[].currency_id

integer

Currency ID

transactions[].currency_code

string

Currency code (3-51 characters)

transactions[].foreign_currency_id

integer

Foreign currency ID

transactions[].foreign_currency_code

string

Foreign currency code

transactions[].source_id

integer

Source account ID (must belong to user)

transactions[].source_name

string

Source account name (1-255 characters)

transactions[].destination_id

integer

Destination account ID

transactions[].destination_name

string

Destination account name

transactions[].budget_id

integer

Budget ID (must belong to user)

transactions[].budget_name

string

Budget name (1-255 characters)

transactions[].category_id

integer

Category ID (must belong to user)

transactions[].category_name

string

Category name (1-255 characters)

transactions[].piggy_bank_id

integer

Piggy bank ID (must belong to user)

transactions[].piggy_bank_name

string

Piggy bank name (1-255 characters)

transactions[].tags

string

Comma-separated tags (1-255 characters)

Repetition Types:

daily: Every day (moment not used)
weekly: Every week on day X (moment: 1=Monday, 7=Sunday)
monthly: Every month on day X (moment: 1-31)
ndom: Nth day of month (moment: “1.1” = first Monday)
yearly: Every year on date from first_date (moment not used)

Weekend Handling:

Skip to Monday: If falls on weekend, move to next Monday
Skip to Friday: If falls on weekend, move to previous Friday
Skip to next Friday: If falls on weekend, move to next Friday
No adjustment: Create transaction on the scheduled date regardless

Get Recurring Transaction by ID

curl -X GET "https://demo.firefly-iii.org/api/v1/recurrences/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/recurrences/{id} Returns the same response fields as the List endpoint.

Update Recurring Transaction

curl -X PUT "https://demo.firefly-iii.org/api/v1/recurrences/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Monthly Rent",
    "transactions": [
      {
        "description": "Rent payment",
        "amount": "1600.00"
      }
    ]
  }'

Endpoint: PUT /v1/recurrences/{id} Accepts the same parameters as Create Recurring Transaction. All fields are optional.

Delete Recurring Transaction

curl -X DELETE "https://demo.firefly-iii.org/api/v1/recurrences/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: DELETE /v1/recurrences/{id} Deletes the recurring transaction. Previously created transactions remain.

Deleting a recurring transaction stops future automatic creation but does not delete transactions that were already created.

Trigger Recurring Transaction

curl -X POST "https://demo.firefly-iii.org/api/v1/recurrences/{id}/trigger" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: POST /v1/recurrences/{id}/trigger Manually triggers the recurrence to create the next transaction immediately.

Get Recurring Transaction’s Created Transactions

curl -X GET "https://demo.firefly-iii.org/api/v1/recurrences/{id}/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/recurrences/{id}/transactions Returns all transactions that were created by this recurrence.

Query Parameters

page

integer

Page number for pagination

start

string

Start date filter (YYYY-MM-DD)

end

string

End date filter (YYYY-MM-DD)

Best Practices

Choosing End Conditions

You can end a recurrence in three ways:

No end date: Leave both repeat_until and nr_of_repetitions null for unlimited recurrence
End by date: Set repeat_until to a specific date
End by count: Set nr_of_repetitions to limit occurrences

You cannot set both repeat_until and nr_of_repetitions. Choose one or neither.

Common Recurring Patterns

Monthly Bills:

{
  "repetitions": [{
    "type": "monthly",
    "moment": "1",
    "skip": 0,
    "weekend": 1
  }]
}

Bi-weekly Paycheck:

{
  "repetitions": [{
    "type": "weekly",
    "moment": "5",
    "skip": 1,
    "weekend": 4
  }]
}

Quarterly Payment:

{
  "repetitions": [{
    "type": "monthly",
    "moment": "1",
    "skip": 2,
    "weekend": 1
  }]
}

First Monday of Month:

{
  "repetitions": [{
    "type": "ndom",
    "moment": "1,1",
    "skip": 0,
    "weekend": 4
  }]
}

Maintenance Tips

Review regularly: Check recurrences quarterly to ensure they’re still accurate
Update amounts: Adjust when bills change (rent increases, subscription price changes)
Set active=false: Instead of deleting, deactivate recurrences you might need later
Use descriptive titles: Include frequency and amount for easy identification

​Overview

​List All Recurring Transactions

​Query Parameters

​Response Fields

​Create Recurring Transaction

​Request Body

​Repetition Object Fields

​Transaction Template Fields

​Get Recurring Transaction by ID

​Update Recurring Transaction

​Delete Recurring Transaction

​Trigger Recurring Transaction

​Related Endpoints

​Get Recurring Transaction’s Created Transactions

​Query Parameters

​Best Practices

​Choosing End Conditions

​Common Recurring Patterns

​Maintenance Tips

Overview

List All Recurring Transactions

Query Parameters

Response Fields

Create Recurring Transaction

Request Body

Repetition Object Fields

Transaction Template Fields

Get Recurring Transaction by ID

Update Recurring Transaction

Delete Recurring Transaction

Trigger Recurring Transaction

Related Endpoints

Get Recurring Transaction’s Created Transactions

Query Parameters

Best Practices

Choosing End Conditions

Common Recurring Patterns

Maintenance Tips