# Update existing bill. `PUT /v1/bills/{id}` Update existing bill. Authentication (security requirement alternatives): ```json [ { "firefly_iii_auth": [] }, { "local_bearer_auth": [] } ] ``` - firefly_iii_auth: oauth2. 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](https://sourcey-firefly.pages.dev/how-to/firefly-iii/features/api/index.md) walks through it. - local_bearer_auth: http (bearer). A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens. Parameters: - `X-Trace-Id` (header, string, uuid, optional) - Unique identifier associated with this request. Type: string, uuid Example: ```json "40c71bbb-c676-4f24-83cf-cc725d7d7a00" ``` - `id` (path, string, required) - The ID of the bill. Type: string Example: ```json "123" ``` Request body: application/json (required) JSON array or key=value pairs with updated bill information. See the model for the exact specifications. Type: object Schema: [BillUpdate](https://sourcey-firefly.pages.dev/api/models/billupdate/index.md) - `currency_id` (optional) Type: string, string Use either currency_id or currency_code Example: ```json "5" ``` - `currency_code` (optional) Type: string, string Use either currency_id or currency_code Example: ```json "EUR" ``` - `name` (required) Type: string, string Example: ```json "Rent" ``` - `amount_min` (optional) Type: string, amount Example: ```json "123.45" ``` - `amount_max` (optional) Type: string, amount Example: ```json "123.45" ``` - `date` (optional) Type: string, date-time Example: ```json "2026-10-01T00:00:00+00:00" ``` - `end_date` (optional) Type: string, date-time The date after which this bill is no longer valid or applicable Example: ```json "2026-10-31T23:59:59+00:00" ``` - `extension_date` (optional) Type: string, date-time The date before which the bill must be renewed (or cancelled) Example: ```json "2026-10-31T23:59:59+00:00" ``` - `repeat_freq` (optional) Reference: [BillRepeatFrequency](https://sourcey-firefly.pages.dev/api/models/billrepeatfrequency/index.md); Type: string, string How often the bill must be paid. enum: ["weekly","monthly","quarterly","half-year","yearly"] Example: ```json "monthly" ``` - `skip` (optional) Type: integer, int32 How often the bill must be skipped. 1 means a bi-monthly bill. Example: ```json 0 ``` - `active` (optional) Type: boolean If the bill is active. Example: ```json true ``` - `notes` (optional) Type: string, string; nullable Example: ```json "Some example notes" ``` - `object_group_id` (optional) Type: string, string; nullable The group ID of the group this object is part of. NULL if no group. Example: ```json "5" ``` - `object_group_title` (optional) Type: string, string; nullable The name of the group. NULL if no group. Example: ```json "Example Group" ``` Request body: application/x-www-form-urlencoded (required) JSON array or key=value pairs with updated bill information. See the model for the exact specifications. Type: object Schema: [BillUpdate](https://sourcey-firefly.pages.dev/api/models/billupdate/index.md) - `currency_id` (optional) Type: string, string Use either currency_id or currency_code Example: ```json "5" ``` - `currency_code` (optional) Type: string, string Use either currency_id or currency_code Example: ```json "EUR" ``` - `name` (required) Type: string, string Example: ```json "Rent" ``` - `amount_min` (optional) Type: string, amount Example: ```json "123.45" ``` - `amount_max` (optional) Type: string, amount Example: ```json "123.45" ``` - `date` (optional) Type: string, date-time Example: ```json "2026-10-01T00:00:00+00:00" ``` - `end_date` (optional) Type: string, date-time The date after which this bill is no longer valid or applicable Example: ```json "2026-10-31T23:59:59+00:00" ``` - `extension_date` (optional) Type: string, date-time The date before which the bill must be renewed (or cancelled) Example: ```json "2026-10-31T23:59:59+00:00" ``` - `repeat_freq` (optional) Reference: [BillRepeatFrequency](https://sourcey-firefly.pages.dev/api/models/billrepeatfrequency/index.md); Type: string, string How often the bill must be paid. enum: ["weekly","monthly","quarterly","half-year","yearly"] Example: ```json "monthly" ``` - `skip` (optional) Type: integer, int32 How often the bill must be skipped. 1 means a bi-monthly bill. Example: ```json 0 ``` - `active` (optional) Type: boolean If the bill is active. Example: ```json true ``` - `notes` (optional) Type: string, string; nullable Example: ```json "Some example notes" ``` - `object_group_id` (optional) Type: string, string; nullable The group ID of the group this object is part of. NULL if no group. Example: ```json "5" ``` - `object_group_title` (optional) Type: string, string; nullable The name of the group. NULL if no group. Example: ```json "Example Group" ``` Responses: - 200: Updated bill stored, result in response Content type: application/vnd.api+json Type: object Schema: [BillSingle](https://sourcey-firefly.pages.dev/api/models/billsingle/index.md) - `data` (required) Reference: [BillRead](https://sourcey-firefly.pages.dev/api/models/billread/index.md); Type: object - 400: Bad request Content type: application/json Type: object Schema: [BadRequestResponse](https://sourcey-firefly.pages.dev/api/models/badrequestresponse/index.md) - `message` (optional) Type: string, string Example: ```json "Bad Request" ``` - `exception` (optional) Type: string, string Example: ```json "BadRequestHttpException" ``` - 401: Unauthenticated Content type: application/json Type: object Schema: [UnauthenticatedResponse](https://sourcey-firefly.pages.dev/api/models/unauthenticatedresponse/index.md) - `message` (optional) Type: string, string Example: ```json "Unauthenticated" ``` - `exception` (optional) Type: string, string Example: ```json "AuthenticationException" ``` - 404: Page not found Content type: application/json Type: object Schema: [NotFoundResponse](https://sourcey-firefly.pages.dev/api/models/notfoundresponse/index.md) - `message` (optional) Type: string, string Example: ```json "Resource not found" ``` - `exception` (optional) Type: string, string Example: ```json "NotFoundHttpException" ``` - 422: Validation error. The body will have the exact details. Content type: application/json Type: object Schema: [ValidationErrorResponse](https://sourcey-firefly.pages.dev/api/models/validationerrorresponse/index.md) - `message` (optional) Type: string, string Example: ```json "The given data was invalid." ``` - `errors` (optional) Type: object - `email` (optional) Type: array Items: Type: string, string - `force` (optional) Type: array Items: Type: string, string - `blocked` (optional) Type: array Items: Type: string, string - `field` (optional) Type: array Items: Type: string, string - `role` (optional) Type: array Items: Type: string, string - `blocked_code` (optional) Type: array Items: Type: string, string - `name` (optional) Type: array Items: Type: string, string - `type` (optional) Type: array Items: Type: string, string - `iban` (optional) Type: array Items: Type: string, string - `start` (optional) Type: array Items: Type: string, string - `end` (optional) Type: array Items: Type: string, string - `date` (optional) Type: array Items: Type: string, string - 500: Internal exception Content type: application/json Type: object Schema: [InternalExceptionResponse](https://sourcey-firefly.pages.dev/api/models/internalexceptionresponse/index.md) - `message` (optional) Type: string, string Example: ```json "Internal Exception" ``` - `exception` (optional) Type: string, string Example: ```json "InternalException" ``` ## Examples ### cURL ```bash 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" }' ``` ### JavaScript ```javascript 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(); ``` ### Python ```python 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) ```