Budgets

Update existing budget limit.

PUT

https://firefly.example.com/api/v1/budgets/{id}/limits/{limitId}

curl -X PUT 'https://firefly.example.com/api/v1/budgets/123/limits/123' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "start": "2026-10-01T00:00:00+00:00",
  "end": "2026-10-31T23:59:59+00:00",
  "currency_id": "5",
  "currency_name": "Euro",
  "currency_code": "EUR",
  "amount": "123.45",
  "notes": "Some example notes",
  "fire_webhooks": true
}'

const body = `{
  "start": "2026-10-01T00:00:00+00:00",
  "end": "2026-10-31T23:59:59+00:00",
  "currency_id": "5",
  "currency_name": "Euro",
  "currency_code": "EUR",
  "amount": "123.45",
  "notes": "Some example notes",
  "fire_webhooks": true
}`;

const response = await fetch('https://firefly.example.com/api/v1/budgets/123/limits/123', {
  method: 'PUT',
  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 = '''{
  "start": "2026-10-01T00:00:00+00:00",
  "end": "2026-10-31T23:59:59+00:00",
  "currency_id": "5",
  "currency_name": "Euro",
  "currency_code": "EUR",
  "amount": "123.45",
  "notes": "Some example notes",
  "fire_webhooks": true
}'''

response = requests.put(
    'https://firefly.example.com/api/v1/budgets/123/limits/123',
    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

{
  "start": "2026-10-01T00:00:00+00:00",
  "end": "2026-10-31T23:59:59+00:00",
  "currency_id": "5",
  "currency_name": "Euro",
  "currency_code": "EUR",
  "amount": "123.45",
  "notes": "Some example notes",
  "fire_webhooks": true
}

{
  "start": "2026-10-01T00:00:00+00:00",
  "end": "2026-10-31T23:59:59+00:00",
  "currency_id": "5",
  "currency_name": "Euro",
  "currency_code": "EUR",
  "amount": "123.45",
  "notes": "Some example notes",
  "fire_webhooks": true
}

{
  "data": {
    "type": "budget_limits",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "start": "2026-10-01T00:00:00+00:00",
      "end": "2026-10-31T23:59:59+00:00",
      "budget_id": "23",
      "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",
      "period": "monthly",
      "spent": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "pc_spent": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "notes": "Some example notes"
    }
  }
}

{
  "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 with updated budget limit information. See the model for the exact specifications.

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

startstring<date-time>

Start date of the budget limit.

Example

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

endstring<date-time>

End date of the budget limit.

Example

2026-10-31T23:59:59+00:00

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

amountstring<amount>

Example

123.45

notesstring | null

Some notes for this specific budget limit.

Example

Some example notes

fire_webhooksbooleantrue

Whether or not to fire the webhooks that are related to this event.

Example

true

Parameters

idstringrequiredpath

The ID of the budget. The budget limit MUST be associated to the budget ID.

limitIdstringrequiredpath

The ID of the budget limit. The budget limit MUST be associated to the budget ID.

Response

200OKBudgetLimitSingle

Updated budget limit stored, result in response

Response fields application/vnd.api+json

dataBudgetLimitReadrequired

Show child attributes

typestringrequired

Immutable value

Example

budget_limits

idstringrequired

Example

attributesBudgetLimitPropertiesrequired

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

startstring<date-time>

Start date of the budget limit.

Example

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

endstring<date-time>

End date of the budget limit.

Example

2026-10-31T23:59:59+00:00

budget_idstringread only

The budget ID of the associated budget.

Example

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>

Example

123.45

pc_amountstring<amount> | nullread only

The amount of this budget limit in the user's primary currency, if the original amount is in a different currency.

Example

123.45

periodstring | nullread only

Period of the budget limit. Only used when auto-generated by auto-budget.

Example

monthly

spentArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) spent in the currencies in the database for this budget limit.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

pc_spentArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) spent in the primary currency in the database for this budget limit.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

notesstring | null

Some notes for this specific budget limit.

Example

Some example notes

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.