Subscriptions

Get a single subscription.

GET

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

Get a single subscription. Subscriptions are also known as bills.

curl -X GET 'https://firefly.example.com/api/v1/subscriptions/123' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/subscriptions/123', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/subscriptions/123',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "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": "Internal Exception",
  "exception": "InternalException"
}

Parameters

idstringrequiredpath

The ID of the subscription.

startstring<date>query

A date formatted YYYY-MM-DD. If it is are added to the request, Firefly III will calculate the appropriate payment and paid dates.

endstring<date>query

A date formatted YYYY-MM-DD. If it is added to the request, Firefly III will calculate the appropriate payment and paid dates.

Response

200OKBillSingle

The requested subscription

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

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.