2012-02-05 Office Supply Galore - Online Order

         Expenses:Main Org:Office Supplies     $35.00

             ;Receipt: accounts/documentation/org/receipts/2012-02-05_office-supply-galore.txt

         Liabilities:Credit Card:Visa         -$35.00

shows that a purchase was made at Office Supply Galore's online store for

$35.00, and the file

`accounts/documentation/org/receipts/2012-02-05_office-supply-galore.txt`

contains the receipt from that purchase.

#### Receipt Tag

document that shows clear confirmation that the transaction has already

repository to the document, [as described above](#documentation-tags).

* a point-of-sale credit card receipt from a purchase, given by a cashier or

  sent via email after the purchase has occurred.

* a deposit slip given at the bank upon making an over-the-counter deposit of

  paper checks.

* a confirmation document showing an outgoing wire transfer made by a bank.

* a confirmation document showing transfer of funds between two bank

  accounts.

* A pay advice document generated upon payment of an invoice.

#### Invoice Tag

organization or received by the organization.  Typically, this is a document

that is a request for payment, rather than documenting an actual payment that

repository to the document, [as described above](#documentation-tags).

* an actual invoice as sent by a vendor to the organization.

* a request for payment sent by the organization to someone else.

* a reimbursement request submitted by an employee, contractor, or volunteer

  for expenses they've already incurred and would like the organization to

  reimburse (e.g., an expense report, requesting for reimbursement of travel

  expenses).

#### Statement Tag

external party (or even perhaps generated internally) that provides document,

insight, or other information about the transaction.  The value of the

document, [as described above](#documentation-tags).

* bank statements, as received from the banking institution.

* written reports of travel.

* blog posts made by a contractor documenting their work.

* written organizational policies about the expense.

* just about anything that is clearly not an [invoice](#invoice-tag) nor a

  [receipt](#receipt-tag), but definitely is valid backup documentation for

  the transaction.

being paid.  For a individual foreign contractor, the `TaxReporting` might

link to a

[W8-BEN](https://www.irs.gov/uac/form-w-8ben-certificate-of-foreign-status-of-beneficial-owner-for-united-states-tax-withholding)

for the payee.

### Information Tags

In contrast to documentation tags, information tags can more traditionally be

considered pure "meta-data" for a ledger entry.

#### Entity Tag

company, person, or legal entity that is the external party for the

transaction.

Note that there is no database of these monikers, so typos can cause

trouble.  However, you could implement checks in

`accounts/config/config-tags.ledger` using a regular expression to verify no

typos have occurred.  This would be somewhat cumbersome, since Ledger CLI

would likely require that the monikers be encoded into a regular expression.

Barring that, the

[integrity of your data should be periodically checked](#checking-integrity-of-a-tag).

#### IncomeType Tag

Since this particular system is designed for USA non-profit entities who file

USA Form 990, the following `IncomeType` values are supported:

* `Donations`, which refers to standard charitable donations.

* `RBI`, which refers to "related business income".

* `UBTI`, which refers to "unrelated business taxable income".

Not that donor-advised funds and government grants don't currently have their

own `IncomeType`.  It's possible this might be necessary; the authors aren't

familiar with how to handle those items on the Form 990.  It would be a

relatively simple change to `config-tags.ledger`, though, to support other

income types, or to change it entirely to handle use-cases other than USA

Form 990 filing.

#### TaxImplication Tag

transaction includes a payment of $10.00 or more leaving the account.  This

tag catalogs any tax implications that might occur on outgoing funds.

The most important USA-related issue tracked by this tag are contractors who

go along with a TaxImplication tag.

The possible values for this field are:

* `1099`, indicating the amount paid requires issuance of a USA Federal Form

  1099 for the `Entity` involved.

* `W2`, indicating the amount paid will be part of a USA Federal income, as

  reported on Form W2 report for the `Entity` involved.

* `Retirement-Pretax`, indicating the amount paid was made to a W2 employee

  as part of pre-tax retirement plan, such as a 401(k) or 403(b) plan.

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:

  [`Statement`](#statement-tag).  (The only exception to this rule: an entry

  [payee was never charged](#never-charged-payee).)

Expense accounts can have the following optional 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 a

historical special-case.  The solution was originally designed 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.

        Liabilities:Credit Card:Visa             $100.00

        Expenses:Conservancy:Hosting            $-100.00

However, going forward, you'd likely never enter anything into 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:

  [`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)

  for more than $800.

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:

    $ 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

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

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)