Recurring transactions

Store a new recurring transaction

POST

https://firefly.example.com/api/v1/recurrences

Creates a new recurring transaction. The data required can be submitted as a JSON body or as a list of parameters.

curl -X POST 'https://firefly.example.com/api/v1/recurrences' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "type": "withdrawal",
  "title": "Rent",
  "description": "Recurring transaction for the monthly rent",
  "first_date": "2026-10-31",
  "repeat_until": "2026-10-31",
  "nr_of_repetitions": 5,
  "apply_rules": true,
  "active": true,
  "notes": "Some notes",
  "repetitions": [
    {
      "type": "weekly",
      "moment": "3",
      "skip": 0,
      "weekend": 1
    }
  ],
  "transactions": [
    {
      "description": "Rent for the current month",
      "amount": "123.45",
      "foreign_amount": "123.45",
      "currency_id": "3",
      "currency_code": "EUR",
      "foreign_currency_id": "17",
      "foreign_currency_code": "GBP",
      "budget_id": "4",
      "category_id": "211",
      "source_id": "913",
      "destination_id": "258",
      "tags": null,
      "piggy_bank_id": "123",
      "bill_id": "123"
    }
  ]
}'

const body = `{
  "type": "withdrawal",
  "title": "Rent",
  "description": "Recurring transaction for the monthly rent",
  "first_date": "2026-10-31",
  "repeat_until": "2026-10-31",
  "nr_of_repetitions": 5,
  "apply_rules": true,
  "active": true,
  "notes": "Some notes",
  "repetitions": [
    {
      "type": "weekly",
      "moment": "3",
      "skip": 0,
      "weekend": 1
    }
  ],
  "transactions": [
    {
      "description": "Rent for the current month",
      "amount": "123.45",
      "foreign_amount": "123.45",
      "currency_id": "3",
      "currency_code": "EUR",
      "foreign_currency_id": "17",
      "foreign_currency_code": "GBP",
      "budget_id": "4",
      "category_id": "211",
      "source_id": "913",
      "destination_id": "258",
      "tags": null,
      "piggy_bank_id": "123",
      "bill_id": "123"
    }
  ]
}`;

const response = await fetch('https://firefly.example.com/api/v1/recurrences', {
  method: 'POST',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "type": "withdrawal",
  "title": "Rent",
  "description": "Recurring transaction for the monthly rent",
  "first_date": "2026-10-31",
  "repeat_until": "2026-10-31",
  "nr_of_repetitions": 5,
  "apply_rules": true,
  "active": true,
  "notes": "Some notes",
  "repetitions": [
    {
      "type": "weekly",
      "moment": "3",
      "skip": 0,
      "weekend": 1
    }
  ],
  "transactions": [
    {
      "description": "Rent for the current month",
      "amount": "123.45",
      "foreign_amount": "123.45",
      "currency_id": "3",
      "currency_code": "EUR",
      "foreign_currency_id": "17",
      "foreign_currency_code": "GBP",
      "budget_id": "4",
      "category_id": "211",
      "source_id": "913",
      "destination_id": "258",
      "tags": null,
      "piggy_bank_id": "123",
      "bill_id": "123"
    }
  ]
}'''

response = requests.post(
    'https://firefly.example.com/api/v1/recurrences',
    data=body.encode('utf-8'),
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "type": "withdrawal",
  "title": "Rent",
  "description": "Recurring transaction for the monthly rent",
  "first_date": "2026-10-31",
  "repeat_until": "2026-10-31",
  "nr_of_repetitions": 5,
  "apply_rules": true,
  "active": true,
  "notes": "Some notes",
  "repetitions": [
    {
      "type": "weekly",
      "moment": "3",
      "skip": 0,
      "weekend": 1
    }
  ],
  "transactions": [
    {
      "description": "Rent for the current month",
      "amount": "123.45",
      "foreign_amount": "123.45",
      "currency_id": "3",
      "currency_code": "EUR",
      "foreign_currency_id": "17",
      "foreign_currency_code": "GBP",
      "budget_id": "4",
      "category_id": "211",
      "source_id": "913",
      "destination_id": "258",
      "tags": null,
      "piggy_bank_id": "123",
      "bill_id": "123"
    }
  ]
}

{
  "type": "withdrawal",
  "title": "Rent",
  "description": "Recurring transaction for the monthly rent",
  "first_date": "2026-10-31",
  "repeat_until": "2026-10-31",
  "nr_of_repetitions": 5,
  "apply_rules": true,
  "active": true,
  "notes": "Some notes",
  "repetitions": [
    {
      "type": "weekly",
      "moment": "3",
      "skip": 0,
      "weekend": 1
    }
  ],
  "transactions": [
    {
      "description": "Rent for the current month",
      "amount": "123.45",
      "foreign_amount": "123.45",
      "currency_id": "3",
      "currency_code": "EUR",
      "foreign_currency_id": "17",
      "foreign_currency_code": "GBP",
      "budget_id": "4",
      "category_id": "211",
      "source_id": "913",
      "destination_id": "258",
      "tags": null,
      "piggy_bank_id": "123",
      "bill_id": "123"
    }
  ]
}

{
  "data": {
    "type": "recurrences",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "type": "withdrawal",
      "title": "Rent",
      "description": "Recurring transaction for the monthly rent",
      "first_date": "2026-10-31",
      "latest_date": "2026-10-01",
      "repeat_until": "2026-10-31",
      "apply_rules": true,
      "active": true,
      "nr_of_repetitions": 5,
      "notes": "Some notes",
      "repetitions": [
        {
          "id": "2",
          "created_at": "2026-10-01T00:00:00+00:00",
          "updated_at": "2026-10-01T00:00:00+00:00",
          "type": "weekly",
          "moment": "3",
          "skip": 0,
          "weekend": 1,
          "description": "Every week on Friday",
          "occurrences": [
            "2026-10-31T23:59:59+00:00"
          ]
        }
      ],
      "transactions": [
        {
          "id": "ID of the recurring transaction. Not to be confused with the ID of the recurrence itself.",
          "description": "Rent for the current month",
          "object_has_currency_setting": true,
          "currency_id": "5",
          "currency_name": "Euro",
          "currency_code": "EUR",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "primary_currency_id": "5",
          "primary_currency_name": "Euro",
          "primary_currency_code": "EUR",
          "primary_currency_symbol": "$",
          "primary_currency_decimal_places": 2,
          "amount": "123.45",
          "pc_amount": "123.45",
          "foreign_amount": "123.45",
          "pc_foreign_amount": "123.45",
          "foreign_currency_id": "17",
          "foreign_currency_name": "British Pound",
          "foreign_currency_code": "GBP",
          "foreign_currency_symbol": "$",
          "foreign_currency_decimal_places": 2,
          "budget_id": "4",
          "budget_name": "Groceries",
          "category_id": "211",
          "category_name": "Bills",
          "source_id": "913",
          "source_name": "Checking account",
          "source_iban": "NL02ABNA0123456789",
          "source_type": "Asset account",
          "destination_id": "258",
          "destination_name": "Buy and Large",
          "destination_iban": "NL02ABNA0123456789",
          "destination_type": "Asset account",
          "tags": null,
          "piggy_bank_id": "123",
          "piggy_bank_name": "string",
          "subscription_id": "123",
          "subscription_name": "string"
        }
      ]
    },
    "links": {
      "0": {
        "rel": "self",
        "uri": "/OBJECTS/1"
      },
      "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
    }
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "string"
    ],
    "force": [
      "string"
    ],
    "blocked": [
      "string"
    ],
    "field": [
      "string"
    ],
    "role": [
      "string"
    ],
    "blocked_code": [
      "string"
    ],
    "name": [
      "string"
    ],
    "type": [
      "string"
    ],
    "iban": [
      "string"
    ],
    "start": [
      "string"
    ],
    "end": [
      "string"
    ],
    "date": [
      "string"
    ]
  }
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Body

JSON array or key=value pairs with the necessary recurring transaction information. See the model for the exact specifications.

application/json,application/x-www-form-urlencodedRecurrenceStore

typeRecurrenceTransactionTypewithdrawaltransferdepositrequired

Example

withdrawal

titlestringrequired

Example

Rent

descriptionstring

Not to be confused with the description of the actual transaction(s) being created.

Example

Recurring transaction for the monthly rent

first_datestring<date>required

First time the recurring transaction will fire. Must be after today.

Example

2026-10-31

repeat_untilstring<date> | nullrequired

Date until the recurring transaction can fire. Use either this field or repetitions.

Example

2026-10-31

nr_of_repetitionsinteger<int32> | null

Max number of created transactions. Use either this field or repeat_until.

Example

apply_rulesboolean

Whether or not to fire the rules after the creation of a transaction.

Example

true

activeboolean

If the recurrence is even active.

Example

true

notesstring | null

Example

Some notes

repetitionsArray<RecurrenceRepetitionStore>required

Show child attributes

typeRecurrenceRepetitionTypedailyweeklyndommonthlyyearlyrequired

The type of the repetition. ndom means: the n-th weekday of the month, where you can also specify which day of the week.

Example

weekly

momentstringrequired

Information that defined the type of repetition.

For 'daily', this is empty.
For 'weekly', it is day of the week between 1 and 7 (Monday - Sunday).
For 'ndom', it is '1,2' or '4,5' or something else, where the first number is the week in the month, and the second number is the day in the week (between 1 and 7). '2,3' means: the 2nd Wednesday of the month
For 'monthly' it is the day of the month (1 - 31)
For yearly, it is a full date, ie '2026-10-01'. The year you use does not matter.

Example

skipinteger<int32>

How many occurrences to skip. 0 means skip nothing. 1 means every other.

Example

weekendinteger<int32>

How to respond when the recurring transaction falls in the weekend. Possible values:

Do nothing, just create it
Create no transaction.
Skip to the previous Friday.
Skip to the next Monday.

Example

transactionsArray<RecurrenceTransactionStore>required

Show child attributes

descriptionstringrequired

Example

Rent for the current month

amountstring<amount>required

Amount of the transaction.

Example

123.45

foreign_amountstring<amount> | null

Foreign amount of the transaction.

Example

123.45

currency_idstring

Submit either a currency_id or a currency_code.

Example

currency_codestring

Submit either a currency_id or a currency_code.

Example

EUR

foreign_currency_idstring | null

Submit either a foreign_currency_id or a foreign_currency_code, or neither.

Example

foreign_currency_codestring | null

Submit either a foreign_currency_id or a foreign_currency_code, or neither.

Example

GBP

budget_idstring

The budget ID for this transaction.

Example

category_idstring

Category ID for this transaction.

Example

source_idstringrequired

ID of the source account.

Example

destination_idstringrequired

ID of the destination account.

Example

tagsArray<string> | null

Array of tags.

Example

null

piggy_bank_idstring | null

Optional.

Example

bill_idstring | null

Optional.

Example

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

Response

200OKRecurrenceSingle

New recurring transaction stored, result in response.

Response fields application/vnd.api+json

dataRecurrenceReadrequired

Show child attributes

typestringrequired

Immutable value

Example

recurrences

idstringrequired

Example

attributesRecurrencePropertiesrequired

Show child attributes

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

typeRecurrenceTransactionTypewithdrawaltransferdeposit

Example

withdrawal

titlestring

Example

Rent

descriptionstring

Not to be confused with the description of the actual transaction(s) being created.

Example

Recurring transaction for the monthly rent

first_datestring<date>

First time the recurring transaction will fire. Must be after today.

Example

2026-10-31

latest_datestring<date> | nullread only

Last time the recurring transaction has fired.

Example

2026-10-01

repeat_untilstring<date> | null

Date until the recurring transaction can fire. Use either this field or repetitions.

Example

2026-10-31

apply_rulesboolean

Whether or not to fire the rules after the creation of a transaction.

Example

true

activeboolean

If the recurrence is even active.

Example

true

nr_of_repetitionsinteger<int32> | null

Max number of created transactions. Use either this field or repeat_until.

Example

notesstring | null

Example

Some notes

repetitionsArray<RecurrenceRepetition>

Show child attributes

idstringread only

Example

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

typeRecurrenceRepetitionTypedailyweeklyndommonthlyyearlyrequired

The type of the repetition. ndom means: the n-th weekday of the month, where you can also specify which day of the week.

Example

weekly

momentstringrequired

Information that defined the type of repetition.

For 'daily', this is empty.
For 'weekly', it is day of the week between 1 and 7 (Monday - Sunday).
For 'ndom', it is '1,2' or '4,5' or something else, where the first number is the week in the month, and the second number is the day in the week (between 1 and 7). '2,3' means: the 2nd Wednesday of the month
For 'monthly' it is the day of the month (1 - 31)
For yearly, it is a full date, ie '2026-10-01'. The year you use does not matter.

Example

skipinteger<int32>

How many occurrences to skip. 0 means skip nothing. 1 means every other.

Example

weekendinteger<int32>

How to respond when the recurring transaction falls in the weekend. Possible values:

Do nothing, just create it
Create no transaction.
Skip to the previous Friday.
Skip to the next Monday.

Example

descriptionstringread only

Auto-generated repetition description.

Example

Every week on Friday

occurrencesArray<string>read only

Array of future dates when the repetition will apply to. Auto generated.

transactionsArray<RecurrenceTransaction>

Show child attributes

idstring

Example

ID of the recurring transaction. Not to be confused with the ID of the recurrence itself.

descriptionstringrequired

Example

Rent for the current month

object_has_currency_settingbooleanread only

Indicates whether the object has a currency setting. If false, the object uses the administration's primary currency.

Example

true

currency_idstring

The currency ID of the currency associated with this object.

Example

currency_namestring

The currency name of the currency associated with this object.

Example

Euro

currency_codestring

The currency code of the currency associated with this object.

Example

EUR

currency_symbolstringread only

Example

currency_decimal_placesinteger<int32>read only

Example

primary_currency_idstringread only

The currency ID of the administration's primary currency.

Example

primary_currency_namestringread only

The currency name of the administration's primary currency.

Example

Euro

primary_currency_codestringread only

The currency code of the administration's primary currency.

Example

EUR

primary_currency_symbolstringread only

The currency symbol of the administration's primary currency.

Example

primary_currency_decimal_placesinteger<int32>read only

The currency decimal places of the administration's primary currency.

Example

amountstring<amount>required

Amount of the transaction.

Example

123.45

pc_amountstring<amount>

Amount of the transaction in primary currency.

Example

123.45

foreign_amountstring<amount> | null

Foreign amount of the transaction.

Example

123.45

pc_foreign_amountstring<amount> | null

Foreign amount of the transaction.

Example

123.45

foreign_currency_idstring | null

Example

foreign_currency_namestring | null

Example

British Pound

foreign_currency_codestring | null

Example

GBP

foreign_currency_symbolstring | nullread only

Example

foreign_currency_decimal_placesinteger<int32> | nullread only

Number of decimals in the currency

Example

budget_idstring

The budget ID for this transaction.

Example

budget_namestring | nullread only

The name of the budget to be used. If the budget name is unknown, the ID will be used or the value will be ignored.

Example

Groceries

category_idstring

Category ID for this transaction.

Example

category_namestring

Category name for this transaction.

Example

Bills

source_idstring

ID of the source account. Submit either this or source_name.

Example

source_namestring

Name of the source account. Submit either this or source_id.

Example

Checking account

source_ibanstring | nullread only

Example

NL02ABNA0123456789

source_typeAccountTypePropertyDefault accountCash accountAsset accountExpense accountRevenue accountInitial balance accountBeneficiary accountImport accountReconciliation accountLoanDebtMortgageread only

Example

Asset account

destination_idstring

ID of the destination account. Submit either this or destination_name.

Example

destination_namestring

Name of the destination account. Submit either this or destination_id.

Example

Buy and Large

destination_ibanstring | nullread only

Example

NL02ABNA0123456789

destination_typeAccountTypePropertyDefault accountCash accountAsset accountExpense accountRevenue accountInitial balance accountBeneficiary accountImport accountReconciliation accountLoanDebtMortgageread only

Example

Asset account

tagsArray<string> | null

Array of tags.

Example

null

piggy_bank_idstring | null

Example

piggy_bank_namestring | null

subscription_idstring | null

Example

subscription_namestring | null

linksObjectLinkrequired

Show child attributes

0object

Show child attributes

relstring

Example

self

uristring

Example

/OBJECTS/1

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECTS/1

400Bad RequestBadRequestResponse

Bad request

Response fields application/json

messagestring

Example

Bad Request

exceptionstring

Example

BadRequestHttpException

401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json

messagestring

Example

Unauthenticated

exceptionstring

Example

AuthenticationException

404Not FoundNotFoundResponse

Page not found

Response fields application/json

messagestring

Example

Resource not found

exceptionstring

Example

NotFoundHttpException

422Unprocessable EntityValidationErrorResponse

Validation error. The body will have the exact details.

Response fields application/json

messagestring

Example

The given data was invalid.

errorsobject

Show child attributes

emailArray<string>

forceArray<string>

blockedArray<string>

fieldArray<string>

roleArray<string>

blocked_codeArray<string>

nameArray<string>

typeArray<string>

ibanArray<string>

startArray<string>

endArray<string>

dateArray<string>

500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json

messagestring

Example

Internal Exception

exceptionstring

Example

InternalException

Authorization

firefly_iii_authoauth2

OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.