Subscriptions

Update existing bill.

PUT

https://firefly.example.com/api/v1/bills/{id}

curl -X PUT 'https://firefly.example.com/api/v1/bills/123' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "currency_id": "5",
  "currency_code": "EUR",
  "name": "Rent",
  "amount_min": "123.45",
  "amount_max": "123.45",
  "date": "2026-10-01T00:00:00+00:00",
  "end_date": "2026-10-31T23:59:59+00:00",
  "extension_date": "2026-10-31T23:59:59+00:00",
  "repeat_freq": "monthly",
  "skip": 0,
  "active": true,
  "notes": "Some example notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}'

const body = `{
  "currency_id": "5",
  "currency_code": "EUR",
  "name": "Rent",
  "amount_min": "123.45",
  "amount_max": "123.45",
  "date": "2026-10-01T00:00:00+00:00",
  "end_date": "2026-10-31T23:59:59+00:00",
  "extension_date": "2026-10-31T23:59:59+00:00",
  "repeat_freq": "monthly",
  "skip": 0,
  "active": true,
  "notes": "Some example notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}`;

const response = await fetch('https://firefly.example.com/api/v1/bills/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 = '''{
  "currency_id": "5",
  "currency_code": "EUR",
  "name": "Rent",
  "amount_min": "123.45",
  "amount_max": "123.45",
  "date": "2026-10-01T00:00:00+00:00",
  "end_date": "2026-10-31T23:59:59+00:00",
  "extension_date": "2026-10-31T23:59:59+00:00",
  "repeat_freq": "monthly",
  "skip": 0,
  "active": true,
  "notes": "Some example notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}'''

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

{
  "currency_id": "5",
  "currency_code": "EUR",
  "name": "Rent",
  "amount_min": "123.45",
  "amount_max": "123.45",
  "date": "2026-10-01T00:00:00+00:00",
  "end_date": "2026-10-31T23:59:59+00:00",
  "extension_date": "2026-10-31T23:59:59+00:00",
  "repeat_freq": "monthly",
  "skip": 0,
  "active": true,
  "notes": "Some example notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}

{
  "currency_id": "5",
  "currency_code": "EUR",
  "name": "Rent",
  "amount_min": "123.45",
  "amount_max": "123.45",
  "date": "2026-10-01T00:00:00+00:00",
  "end_date": "2026-10-31T23:59:59+00:00",
  "extension_date": "2026-10-31T23:59:59+00:00",
  "repeat_freq": "monthly",
  "skip": 0,
  "active": true,
  "notes": "Some example notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}

{
  "data": {
    "type": "bills",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "name": "Rent",
      "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_min": "123.45",
      "pc_amount_min": "123.45",
      "amount_max": "123.45",
      "pc_amount_max": "123.45",
      "amount_avg": "123.45",
      "pc_amount_avg": "123.45",
      "date": "2026-10-01T00:00:00+00:00",
      "end_date": "2026-10-31T23:59:59+00:00",
      "extension_date": "2026-10-31T23:59:59+00:00",
      "repeat_freq": "monthly",
      "skip": 0,
      "active": true,
      "order": 1,
      "notes": "Some example notes",
      "object_group_id": "5",
      "object_group_order": 5,
      "object_group_title": "Example Group",
      "paid_dates": [
        {
          "transaction_group_id": "123",
          "transaction_journal_id": "123",
          "date": "2026-10-01T00:00:00+00:00",
          "subscription_id": "123",
          "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"
        }
      ],
      "pay_dates": [
        "2026-10-01T00:00:00+00:00"
      ],
      "next_expected_match": "2026-10-01T00:00:00+00:00",
      "next_expected_match_diff": "today"
    }
  }
}

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

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

currency_idstring

Use either currency_id or currency_code

Example

currency_codestring

Use either currency_id or currency_code

Example

EUR

namestringrequired

Example

Rent

amount_minstring<amount>

Example

123.45

amount_maxstring<amount>

Example

123.45

datestring<date-time>

Example

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

end_datestring<date-time>

The date after which this bill is no longer valid or applicable

Example

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

extension_datestring<date-time>

The date before which the bill must be renewed (or cancelled)

Example

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

repeat_freqBillRepeatFrequencyweeklymonthlyquarterlyhalf-yearyearly

How often the bill must be paid.

Example

monthly

skipinteger<int32>

How often the bill must be skipped. 1 means a bi-monthly bill.

Example

activeboolean

If the bill is active.

Example

true

notesstring | null

Example

Some example notes

object_group_idstring | null

The group ID of the group this object is part of. NULL if no group.

Example

object_group_titlestring | null

The name of the group. NULL if no group.

Example

Example Group

Parameters

idstringrequiredpath

The ID of the bill.

Response

200OKBillSingle

Updated bill stored, result in response

Response fields application/vnd.api+json

dataBillReadrequired

Show child attributes

typestringrequired

Immutable value

Example

bills

idstringrequired

Example

attributesBillPropertiesrequired

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

namestring

The name of the subscription.

Example

Rent

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

amount_minstring<amount>

The minimum amount that is expected for this subscription in the subscription's currency.

Example

123.45

pc_amount_minstring<amount>

The minimum amount that is expected for this subscription in the administration's primary currency.

Example

123.45

amount_maxstring<amount>

The maximum amount that is expected for this subscription in the subscription's currency.

Example

123.45

pc_amount_maxstring<amount>

The maximum amount that is expected for this subscription in the administration's primary currency.

Example

123.45

amount_avgstring<amount>

The average amount that is expected for this subscription in the subscription's currency.

Example

123.45

pc_amount_avgstring<amount>

The average amount that is expected for this subscription in the administration's primary currency.

Example

123.45

datestring<date-time>

Example

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

end_datestring<date-time> | null

The date after which this subscription is no longer valid or applicable

Example

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

extension_datestring<date-time> | null

The date before which the subscription must be renewed (or cancelled)

Example

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

repeat_freqBillRepeatFrequencyweeklymonthlyquarterlyhalf-yearyearly

How often the bill must be paid.

Example

monthly

skipinteger<int32>

How often the subscription will be skipped. 1 means a bi-monthly subscription.

Example

activeboolean

If the subscription is active.

Example

true

orderinteger<int32>

Order of the subscription.

Example

notesstring | null

Example

Some example notes

object_group_idstring | null

The group ID of the group this object is part of. NULL if no group.

Example

object_group_orderinteger<int32> | nullread only

The order of the group. At least 1, for the highest sorting.

Example

object_group_titlestring | null

The name of the group. NULL if no group.

Example

Example Group

paid_datesArray<object>read only

Array of past transactions when the subscription was paid.

Show child attributes

transaction_group_idstringread only

Transaction group ID of the transaction linked to this subscription.

Example

transaction_journal_idstringread only

Transaction journal ID of the transaction linked to this subscription.

Example

datestring<date-time>read only

Date the bill was paid.

Example

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

subscription_idstringread only

ID of this subscription.

Example

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>

The amount that was paid for this subscription in the subscription's currency.

Example

123.45

pc_amountstring<amount>

The amount that was paid for this subscription in the administration's primary currency.

Example

123.45

foreign_amountstring<amount>

The foreign amount that was paid for this subscription in the subscription's currency.

Example

123.45

pc_foreign_amountstring<amount>

The foreign amount that was paid for this subscription in the administration's primary currency.

Example

123.45

pay_datesArray<string>read only

Array of future dates when the bill is expected to be paid. Autogenerated.

next_expected_matchstring<date-time> | nullread only

When the subscription is expected to be due.

Example

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

next_expected_match_diffstring | nullread only

Formatted (locally) when the subscription is due.

Example

today

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.