FIfirefly-iii
recurrences

Store a new recurring transaction

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

post/v1/recurrences

Request

  • Base URL
    https://demo.firefly-iii.org/api
  • URL
    https://demo.firefly-iii.org/api/v1/recurrences
  • Auth
    • OAuth 2
      Authorization code: https://demo.firefly-iii.org/oauth/authorize
      Token URL: https://demo.firefly-iii.org/oauth/token
    • or HTTP bearer

Headers

X-Trace-Idstring uuid
Example:40c71bbb-c676-4f24-83cf-cc725d7d7a00

Unique identifier associated with this request.

Request body

type'withdrawal' | 'transfer' | 'deposit' string required
titlestring string required
descriptionstring string

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

first_datestring date required

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

repeat_untilstring date nullable required

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

nr_of_repetitionsinteger nullable

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

apply_rulesboolean

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

activeboolean

If the recurrence is even active.

notesstring string nullable

Example request

{
  "type": "withdrawal",
  "title": "Rent",
  "description": "Recurring transaction for the monthly rent",
  "first_date": "2025-08-31",
  "repeat_until": "2025-08-31",
  "nr_of_repetitions": 5,
  "apply_rules": true,
  "active": true,
  "notes": "Some notes",
  "repetitions": [
    {
      "type": "weekly",
      "moment": "3",
      "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": [
        "Barbecue preparation"
      ],
      "piggy_bank_id": "123",
      "bill_id": "123"
    }
  ]
}

Response

New recurring transaction stored, result in response.

Example response

{
  "data": {
    "type": "recurrences",
    "id": "2",
    "attributes": {
      "created_at": "2025-08-01T00:00:00+00:00",
      "updated_at": "2025-08-01T00:00:00+00:00",
      "type": "withdrawal",
      "title": "Rent",
      "description": "Recurring transaction for the monthly rent",
      "first_date": "2025-08-31",
      "latest_date": "2025-08-01",
      "repeat_until": "2025-08-31",
      "apply_rules": true,
      "active": true,
      "nr_of_repetitions": 5,
      "notes": "Some notes",
      "repetitions": [
        {
          "id": "2",
          "created_at": "2025-08-01T00:00:00+00:00",
          "updated_at": "2025-08-01T00:00:00+00:00",
          "type": "weekly",
          "moment": "3",
          "weekend": 1,
          "description": "Every week on Friday",
          "occurrences": [
            "2025-08-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": [
            "Barbecue preparation"
          ],
          "piggy_bank_id": "123",
          "subscription_id": "123"
        }
      ]
    },
    "links": {
      "0": {
        "rel": "self",
        "uri": "/OBJECTS/1"
      },
      "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.