Fetching contributors…
Cannot retrieve contributors at this time
124 lines (86 sloc) 5.28 KB

Gratipay Finances

This is Gratipay's financial accounting system, which uses Beancount and a workflow here on GitHub. While we catch up on our books, our budget and old data are available in our old spreadsheet.


How Our Books are Organized

The biggest reality in our finances is that we have operationsour money—and then we have escrowother people's money. Never the twain shall meet (more or less). Beyond the basic accounting principle that assets must equal liabilities plus equity, nearly as important for Gratipay is that escrow assets must always equal escrow liability: when people think we're holding their money, we'd better be holding their money!

Actually, though, our operating income from processing fees comes to us from our upstream processors commingled with escrow, and (as of June, 2013) we want to keep our fee income as close to our fee expenses as possible (our true operating income, of course, comes through Gratipay just like any other project on Gratipay). To deal with this dual reality, we use a fee buffer. Ideally the balance in the fee buffer is zero, but in practice it fluctuates.

You'll see, then, that the assets on our balance sheet are broken down according to three second-level categories: Escrow, Fee-Buffer, and Operations. Whereas the second-level asset categories are logical, our actual physical bank and processor accounts end up as third-level categories. So, for example, our actual balance at New Alliance Federal Credit Union is equal to the sum of these three balance sheet accounts:

  • Assets:Escrow:New Alliance
  • Assets:Fee-Buffer:New Alliance
  • Assets:Operations:New Alliance

Fiscal Year

Our fiscal year runs from January 1 through December 31.

How This Repo is Organized

There is a directory for each fiscal year, named FYNNNN (note that fiscal years are specified by the calendar year in which they end). Inside are two kinds of files:

  • NNNN-MM.beancount, containing a single month's worth of transactions; and
  • FYNNNN.beancount, containing the opening and closing transactions for the year, and including all of the month files.

A gratipay.beancount file ties these together, setting options, and including the transactions from all fiscal years. That's where you want to point Beancount's scripts.

Working on the Finances

First, you'll need a text editor, a command line, and Beancount. Then basically what you're gonna do is edit the file for the month you're working on, and then, from the root of your clone of this repo, run ./ That'll check for errors (we also have CI set up at Travis). To review the balance sheet and income statement, run bean-web gratipay.beancount.


Each month gets a PR entitled account for YYYY-MM, with a branch named YYYY-MM. We close the month by merging the PR. Inside of an open month, we should overwrite transactions as needed (changes are tracked in Git commits and GitHub comments). Outside of an open month, we must make any correcting transactions in the current month, rather than overwriting transactions in an old file.

Each fiscal year also gets a PR entitled close FYNNNN and/or audit FYNNNN (we haven't done this yet so who knows? :). We close the year by merging the PR(s). Once a year is closed, we mustn't edit it at all, apart from comments.

It's always okay to add or clarify comments.


Here are some style notes for the *.beancount files, based on a conversation with our accountant:

  1. Group transactions together conceptually.
  2. Transactions should be generally date-sorted, but it's okay to fudge that a little for the sake of (1).
  3. Record debits first.
  4. Symmetry is nice.
  5. Explicate all transaction amounts (don't depend on Beancount's amount interpolation).
  6. Use comments! Especially for weird stuff.


Many accounting tasks require access to Gratipay's bank and payment processor statements. If you're interested in helping out with such tasks and would like access to our statements, start with Inside Gratipay.


Open an issue if you're having problems.


The scripts and data in this repo are released into the public domain to the extent possible under CC0, and if you don't accept that then you may also use them under the CC or OSI license of your choosing.