Changeset - 8aa83cee1e89
[Not reviewed]
0 4 0
Bradley Kuhn (bkuhn) - 7 years ago 2017-02-24 00:19:41
bkuhn@ebb.org
E.g. of invoice for conference w/ split IncomeType

An example of an invoice for a conference where the income type is split
between RBI and Donations. Include a ledger reporting example that
shows the total of donations, and explain in the documentation why
that's useful.
4 files changed with 17 insertions and 2 deletions:
0 comments (0 inline, 0 general)
accounts/books.ledger
Show inline comments
 
; -*- ledger -*-
 
; -*- coding: utf-8 -*-
 

	
 
!include config/config-npo.ledger
 
!include org/main-org.ledger
 
!include fooproject/foo.ledger
accounts/config/config-tags.ledger
Show inline comments
 
; -*- ledger -*-
 
; -*- coding: utf-8 -*-
 
;
 
; config-tags.ledger: The Ledger CLI tag declarations for NPO use-case.
 

	
 
; Copyright © 2013, Bradley M. Kuhn.
 
;
 
; The copyright holders wish that this document could be placed into the
 
; public domain.  However, should such a public domain dedication not be
 
; possible, the copyright holders grant a waiver and/or license under the
 
; terms of CC0-1.0, as published by Creative Commons, Inc.  A copy of CC0-1.0
 
; can be found in the same repository as this README.md file under the
 
; filename CC0-1.0.txt.  If this document has been separated from the
 
; repository, a copy of CC0-1.0 can be found on Creative Commons' website at
 
; http://creativecommons.org/publicdomain/zero/1.0/legalcode
 

	
 
; ################################# TAGS ################################
 

	
 
; The Statement, Receipt, and Invoice tags' values should always a be a
 
; relative path names.  Note that we "check", but do not "assert" that the
 
; file name match a standard Unix-like path syntax, without spaces in the
 
; file name.
 

	
 
tag Statement
 
    assert value =~ /[^\/].+/
 
    check value =~ /[^\/][^ ]+(\/[^ ])+/
 

	
 
tag Receipt
 
    assert value =~ /[^\/].+/
 
    check value =~ /[^\/][^ ]+(\/[^ ])+/
 

	
 
tag Invoice
 
    assert value =~ /[^\/].+/
 
    check value =~ /[^\/][^ ]+(\/[^ ])+/
 

	
 
; IncomeType refers to the types of income a non-profit can receive.  In this
 
; example, it's for the categorizations on the USA Form 990.  This could be
 
; changed to accomodate other jurisdictions around the world.
 

	
 
tag IncomeType
 
    assert value =~ /^(Donations|RBI|UBTI)$/
 

	
 
; Program tag must match the general format of a ledger account as an
 
; assertion, but we at least check known names of programs, so that warnings
 
; are produced if a new program never seen before is encountered.
 

	
 
tag Program
 
    assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/
 
    check  value =~ /^(Main Org:(Overhead|Direct Fundraising|Software:Internal))$/
 
    check  value =~ /^((Foo|Main Org):(Overhead|Direct Fundraising|Software:Internal|Conference.*))$/
 

	
 

	
 
; Entity tag is just a string, but shouldn't have spaces, just letters,
 
; numbers and dashes.
 

	
 
tag Entity
 
    assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/
 

	
 

	
 
tag TaxImplication
 
    assert value =~ /^W2|1099|Accountant-Advises-No-1099|Bank-Transfer|Foreign-Corporation|Foreign-Individual-Contractor|Payroll|Refund|Reimbursement|Tax-Payment|USA-501c3|USA-Corporation|USA-LLC-No-1099$/
accounts/org/main-org.ledger
Show inline comments
 
; -*- ledger -*-
 
; -*- coding: utf-8 -*-
 

	
 
!include ../config/config-npo.ledger
 

	
 
2012-02-05 Office Supply Galore - Online Order
 
        ;Receipt: accounts/documentation/org/receipts/2012-02-05_office-supply-galore.txt
 
    Expenses:Main Org:Office Supplies         $35.00
 
        ;Program: Main Org:Overhead
 
    Liabilities:Credit Card:Visa             $-35.00
 

	
 
2011/05/28 My Bad Billing Hosting - NEVER CHARGED
 
    Liabilities:Credit Card:Visa            $-100.00
 
    Expenses:Main Org:Hosting                $100.00
 
        ;Program: Main Org:Overhead
 

	
 
2012/01/01 My Bad Billing Hosting - REVERSAL - NEVER CHARGED
 
    Liabilities:Credit Card:Visa             $100.00
 
    Expenses:Main Org:Hosting               $-100.00
 
        ;Program: Main Org:Overhead
 

	
 
2012-05-03 Sir Moneybags
 
        ;Entity: Sir-Moneybags
 
        ;Program: Main Org:Direct Fundraising
 
        ;Invoice: accounts/documentation/org/invoices/2012-05-30_moneybags-invoice_as-sent.txt
 
    Accrued:Accounts Receivable:Main Org  $100,000.00
 
    Income:Main Org:Donations            $-100,000.00
 
        ;IncomeType: Donations
 

	
 
2012-07-05 J. Developer
 
        ;Entity: Developer-J
 
        ;Invoice: accounts/documentation/org/expenses/developer/2012-07-05_developer-invoice.txt
 
    Accrued:Accounts Payable:Main Org  $-5,000.00
 
    Expenses:Main Org:Development       $5,000.00
 
        ;Program: Main Org:Software:Internal
 
        ;Statement: accounts/documentation/org/expenses/developer/2012-07-05_developer-report.txt
 

	
 
2012-08-03 (1) J. Developer
 
        ;Entity: Developer-J
 
    Accrued:Accounts Payable:Main Org  $5,000.00
 
        ;Invoice: accounts/documentation/org/expenses/developer/2012-07-05_developer-invoice.txt
 
    Asset:Checking                    $-5,000.00
 
        ;TaxImplication: 1099
 

	
npo-ledger-cli-tutorial.md
Show inline comments
...
 
@@ -362,166 +362,181 @@ The possible values for this field are:
 
The `Program` tag is used primarily to track program activity for `Income:`
 
and `Expenses:` accounts.  This allows for knowing what particular initiative
 
initiated the income (e.g., a specific fundraising campaign) and/or what
 
particular program activity an expense is toward (e.g., funding travel to
 
some specific conference).
 

	
 
The Program tag is always a string with the same format as a Ledger CLI
 
account (primarily for use with Ledger CLI's `--pivot` and `--group-by`,
 
[as described later](#testing-program-success)).
 

	
 
### Account Type Documentation Requirements
 

	
 
Each account type has different documentation requirements.  Based on the
 
type of the account, it requires a different set of tags.
 

	
 
When Ledger CLI's `--pedantic` option is used, these rules are enforced by
 
ledger itself via the configurations found in `config-tags.ledger` and
 
`config-accounts.ledger`.
 

	
 
#### Expense Account Documentation
 

	
 
Each `Expenses:` account entry must be tagged with the following tags:
 

	
 
* One of: [`Invoice:`](#invoice-tag) [`Receipt:`](#receipt-tag), or
 
  [`Statement`](#statement-tag).  (The only exception to this rule: an entry
 
  does not need an `Invoice:`, `Receipt`, nor a `Statement` tag if the
 
  [payee was never charged](#never-charged-payee).)
 

	
 
* A [`Program:`](#program-tag) tag.
 

	
 
#### NEVER CHARGED Payee
 

	
 
The only exception to the standard tagging requirement is when the payee has
 
been modified to indicate that the expense was `NEVER CHARGED`.  This is an
 
historical special-case.  The solution was originally design for the
 
following scenario:
 

	
 
Suppose an expense was expected — for example, a situation where you
 
gave a credit card number to charge something and the charge never came
 
through — but it turns out the charge never happened.
 

	
 
The recommended way to resolve this problem in the system is to just delete
 
the entry entirely from the Ledger file, and allow the VCS to log the fact
 
that the charge was expected, but the vendor never billed the credit card.
 

	
 
The reason the `NEVER CHARGED` payee text was added was to handle the
 
situation where the books included this charge, but the books were already
 
closed for the financial period (e.g., the books had already been audited).
 
Changing the payee was a method for documenting the expense.  You might use
 
it like this:
 

	
 
    2011/05/28 My Bad Billing Hosting - NEVER CHARGED
 
        Liabilities:Credit Card:Visa            $-100.00
 
        Expenses:Conservancy:Hosting             $100.00
 

	
 
    2012/01/01 My Bad Billing Hosting - REVERSAL - NEVER CHARGED
 
        Liabilities:Credit Card:Visa             $100.00
 
        Expenses:Conservancy:Hosting            $-100.00
 

	
 
However, going forward, you'd likely never enter anything the ledger
 
**until** you had real proof via an Invoice, Receipt or Statement that showed
 
the Expense did/should occur.  This use of `NEVER CHARGED` in the payee is
 
thus deprecated.
 

	
 
#### Income Account Documentation
 

	
 
Each `Income:` account must have the following tags:
 

	
 
* One of: [`Invoice:`](#invoice-tag),
 
  [`PurchaseOrder:`](#purchase-order-tag),
 
  [`Statement:`](#statement-tag) or
 
  [`Contract`](#contract-tag).  Exceptions to this requirement are as follows:
 
     + the income generated from the transaction is less than $800, or
 
     + the `IncomeType` is `RBI` and the income is for a defined, public
 
       program (such as conference registration)
 

	
 
* An [`Entity:`](#entity-tag) tag, *iff.* the Income for the transaction is
 
  for more than $800.
 

	
 
* An [`IncomeType:`](#incometype-tag) tag.
 

	
 
* A [`Program:`](#program-tag) tag.
 

	
 
Reports For Various Situations
 
------------------------------
 

	
 
When data is well formed as specified herein, there are various quick reports
 
that can be used to verify certain conditions or issues with accounting.
 
Here are a few examples:
 

	
 
### Verifying That An Invoice Is Paid
 

	
 
Assume for this example that the shell variables `entity`, `program`, and
 
`invoice` are set as follows:
 

	
 
    $ entity=Sir-Moneybags; program='Main.*Org:.*Direct'; invoice=2012-05-30
 

	
 
If the invoice was paid, this ledger command will have two lines of output,
 
and the second line will be a transaction on the payment date.  If only one
 
line appears, it's the receivable accrual and we see the invoice is not paid.
 

	
 
    $ ledger -f accounts/books.ledger  -V --sort d --limit 'tag("Entity") =~ /'$entity'/ and tag("Program") =~ /'$program'/ and tag("Invoice") =~ /'$invoice'/' reg /Accrued/
 

	
 
Alternatively, the following command will only have output if the invoice is unpaid:
 

	
 
    $ ledger -f accounts/books.ledger  -V --limit 'tag("Entity") =~ /'$entity'/ and tag("Program") =~ /'$program'/ and tag("Invoice") =~ /'$invoice'/' bal /Accrued/
 

	
 
### Calculating Donation Portion of Invoice
 

	
 
As described in
 
[IRS 501(c)(3) rules](https://www.irs.gov/charities-non-profits/substantiating-charitable-contributions),
 
a charity must substantiate portions of a contribution that are RBI, and
 
portions that are donations separately and inform the donor which portion was
 
a donation that may be eligible for tax deduction.  Use of the `IncomeType`
 
tag facilities collection of the necessary data to determine the total, and
 
the following command line will total up all the donation portions for a
 
particular invoice:
 

	
 
    $ entity=BigCorp; program=Foo.*Conf.*2017; invoice=2016-01-30
 
    $ ledger -f accounts/books.ledger  -V --sort d --limit 'tag("IncomeType") =~ /Donation/ and tag("Entity") =~ /'$entity'/ and tag("Program") =~ /'$program'/ and tag("Invoice") =~ /'$invoice'/' reg
 

	
 
Analysis of the Data
 
--------------------
 

	
 
If this methodology is followed, Ledger can be used to analyze the financial
 
data for the organization.
 

	
 
### Testing Program Success
 

	
 
If you use the [`Program`](#program-tag) tag effectively, you can easily test
 
the successes of various fundraising programs with a command like this:
 

	
 
    $ ledger -f accounts/books.ledger --pivot Program bal '/^Income/'
 

	
 
Meanwhile, using the  [`Program`](#program-tag) tag for Expenses can help
 
track what programs are costing with commands like these:
 

	
 
    $ ledger -f accounts/books.ledger --group-by 'tag("Program")' reg '/^Expenses/'
 

	
 
FIXME: example output
 

	
 
### Checking Integrity of a Tag
 

	
 
[As mentioned](#entity-tag), the `Entity:` tag is one example among many
 
where the value is a wide range, but since Ledger CLI isn't backed by a more
 
complete ERP system, it's possible during data entry for typos to make a
 
serious problem.  One work around to this flaw is to periodically run a
 
command like:
 

	
 
    $ ledger -f accounts/books.ledger -F '%(tag("Entity"))\n' reg|sort|uniq|less
 

	
 
which will show all unique `Entity:` values currently in use.
 

	
 
Copyright and License of This File
 
----------------------------------
 

	
 
This specific document, the README.md file for npo-ledger-cli, is copyrighted:
 
  Copyright © 2013, Bradley M. Kuhn
 

	
 
This document's license gives you freedom; you can copy, modify, convey,
 
propagate, and/or redistribute this software under the terms of either:
 

	
 
    * The GNU General Public License as published by the Free Software
 
      Foundation, Inc.; either version 3 of the License, or (at your option)
 
      any later version (aka GPLv3-or-later).
 

	
 
    * *or* the Creative Commons Attribution-ShareAlike 3.0 United States
 
      license, as published by Creative Commons, Inc. (aka CC-By-SA-USA-3.0)
 

	
 
In addition, when you convey, distribute, and/or propagate this document
 
and/or modified versions thereof, you may also preserve this notice so that
 
recipients of such distributions will also have both licensing options
 
described above.
 

	
 
A copy of GPLv3 and CC-By-SA-3.0-USA can be found in the same repository as
 
this file under the filenames GPLv3.txt and CC-By-SA-3.0-USA.txt.  If this
 
document has been separated from the repository, a
 
[copy of GPL can be found on FSF's website](http://www.gnu.org/licenses/gpl.txt)
 
and a
 
[copy of CC-By-SA-USA-3.0 can be found on Creative Commons' website](http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
 

	
0 comments (0 inline, 0 general)