From 860bf3729a823e23a4f71d2ba861fe35dd625b22 Mon Sep 17 00:00:00 2001 From: eileen <emcnaughton@wikimedia.org> Date: Fri, 25 Oct 2019 13:19:24 +1300 Subject: [PATCH] Flesh out information about financial items --- docs/financial/financialentities.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/financial/financialentities.md b/docs/financial/financialentities.md index cbb2e581..cc948bb8 100644 --- a/docs/financial/financialentities.md +++ b/docs/financial/financialentities.md @@ -61,3 +61,25 @@ Negative payments (or refunds) will have the bank or processor account on the ** Financial items exist to track how much has been paid against the various line items within an order / contribution. In an accounting system this might be called credit-matching. + +Each line item will have one or more financial items denoting payments made against it. On creation of the order there +will be a financial item for each line item and an additional item for every fee amount. Where the preferred flow is used +this item will have a status of 'Unpaid'. (Note that for historical reasons this may not always be true but it's the goal - [see](https://github.com/civicrm/civicrm-dev-docs/issues/712)) + +When a payment is made it might either pay off the line items, or a specific line item, in full. In that case the line item +status is updated to Paid and an EntityFinancialTrxn record is created in the civicrm_entity_financial_trxn table linking +the line item to the payment and specifying the amount paid. + +If the line item is paid in part then the status is not updated and the EntityFinancialTrxn table specifies the portion +of the line item that has been paid by that payment. + +If the line items change then the items financial items have to be updated. Generally the rule is to alter the zero out the +old line item, reverse the financial items and then create a new line item with new financial items. However, this is not +always possible as there are some scenarios where the schema does not permit this. The has led to +adjustment line items being created in these cases. The issue is that the civicrm_line_item table has a unique index for +entity_table + entity_id + contribution_id + price_field_value_id + price_field_id. + +This means that if a line item with no price_field_values (ie a text / enter quantity line item) is altered it is not possible +to create a reversal line and a new line within the schema. The same problem occurs when changing a line item with price_field_values +BACK to a price_field_value it previously held. In both these scenarios the work around is to have more than one 'valid' financial_item +against the resulting line item with an 'adjustment' entry - ie an additional financial_item. -- GitLab