Patrons account lines endpoint RFC

General overview

This RFC proposes several endpoints:

Account lines

• /account/lines: for dealing with account lines (listing and making them void).

Patron's balance

• /patrons/{patron_id}/account: for fetching the patron's balance information.

Patron's credits and debits

• GET /patrons/{patron_id}/account/credits: for listing a patrons credits
• POST /patrons/{patron_id}/account/credits: for creating credit-based account lines (both against account lines and fixed amounts).
• GET /patrons/{patron_id}/account/debits: for listing a patrons debits
• POST /patrons/{patron_id}/account/debits: for creating debit-based account lines (both against account lines and fixed amounts).

Account lines

Routes and actions

Description	Action	Proposed path
List account lines	GET	/account/lines
Get a single account line	GET	/account/lines/{account_line_id}
Void a credit	DELETE	/account/lines/{account_line_id}
Partially update an account line (only description fields)	PATCH	/account/lines/{account_line_id}

Making credits void

Bug 20703 introduces a way to void any kind of credit. This spec is based on that capability. This action only applies to credits, so trying to void a debit will result in a bad request code.

Object definition

Bug 20777 removes the accountlines.dispute column, this spec is based on it.

DB schema	API	Description
accountlines_id	account_line_id	Internal account line identifier
issue_id	checkout_id	Internal ID for the checkout the account line is related to
borrowernumber	patron_id	Internal identifier for the patron the account line belongs to
accountno	REMOVED	No longer required.
dispute	REMOVED	No longer required.
itemnumber	item_id	Internal identifier for the item the account line is related to (fines?)
date	date	Date the account line was created
amount	amount	Account line amount
description	description	Description
accounttype	account_type (Payment, Writeoff, Fine TODO: track use cases)	Type of account line
payment_type	payment_type (optional, see PAYMENT_TYPE usage on the codebase)	Payment type (only applies if account_type related to some kind of payment)
amountoutstanding	amount_outstanding	Outstanding amount
lastincrement	last_increment	The amount the fine was updated on the last update
timestamp	timestamp (what about date?)	Timestamp for the latest update
note	internal_note	Internal note
manager_id	user_id	Internal patron identifier for the staff member that introduced the account line

Query parameters

Use the existing objects.search method of adding query facilities

Patron's balance

Routes and actions

Description	Action	Proposed path
Fetch patron's balance	GET	/patrons/{patron_id}/account

Object definition

Attribute	Description
balance	A signed integer, from $patron->account->balance.
outstanding_credits	An object representing the total outstanding credits, and the corresponding account line objects
outstanding_debits	An object representing the total outstanding debits, and the corresponding account line objects

Discussion

Does negative value mean the patron owes the library? It does sound more reasonable than the opposite, but the UI clearly does it the other way around, plus using colors to denote credits/debits.

Patron's credits

Routes and actions

Description	Action	Proposed path
Add a credit	POST	/patrons/{patron_id}/account/credits

Object definition

Attribute	Description
credit_type	Type of credit ('payment', 'writeoff', values of PAYMENT_TYPE )
amount	Credit amount
[ acount_line_ids ]	List of account line ids the credit goes against (Optional)
date	Date the credit was recorded
description	Description of the credit
note	Note

Patron's debits

Routes and actions

Description	Action	Proposed path
Add a debit	POST	/patrons/{patron_id}/account/debits

Object definition

Attribute	Description
debit_type	Type of debit ('lost_item', 'fine', 'account_management_fee', 'new_card', 'sundry', values of MANUAL_INV )
amount	Debit amount
date	Date the debit was recorded
description	Description of the debit
note	Note

Comments

Maybe we could use staff_id or user_id instead of manager_id. I think this might be the only spot in Koha where we refere to a manager. --Kfischer 16:08, 23 May 2018 (EDT)

Discussion (tcohen)

Specialized endpoints

We could have specialized endpoints for payments, writeoffs, fees and fines if found useful:

• /patrons/{patron_id}/account/payments: for creating payment-based account lines (both against account lines and fixed amounts).
• /patrons/{patron_id}/account/writeoffs: for creating writeoff-based account lines (both against account lines and fixed amounts).
• /patrons/{patron_id}/account/fees: for creating fee-based account lines.
• /patrons/{patron_id}/account/fines: for creating fine-based account lines.

Account types and negative values

The current DB schema includes:

• accountlines: each credit and debit operation is recorded here. The original value ('amount') is stored, and there's also 'amountstanding' which keeps the outstanding amount.
• account_offsets: this table records how credits and debits interact with each other (e.g. a payment is recorded as an account line, but affects existing lines that are debits, each 'decrese' action on those debits outstanding amounts is recorded as an offset).