This was documentation that was written for our old self-hosted member invoicing system (Simple Invoices). As of 2022 we use FreshBooks so this document no longer applies.
Detailed description of how our dues collection aka invoicing system works, checks in place to save time, and the general way people have come to expect things to work. Simple Invoices easily saves 20 hours of work a month, but it has quirks.
There is also the Dues Collection QuickStart which is a short set of directions of how cash dues are collected and processed in our system.
From here on out we call this Invoicing.
Hard Rules of Invoicing
First rule of invoicing
(For processing new members):
If a new member has not yet paid then we don’t process their membership, clear and simple.
Once money is in our hands we move forwards. We’ve had way too many folks get 3 visits in, be all excited and ready to go, promise to pay next week, then they never show up again. Then you are left with a bunch of cleanup you have to do both in the invoicing system and other places, and not even a single dues payment to show for it (and you are out 1 RFID fob too).
Second rule of invoicing
Thou shall never mark an invoice as being paid for more than the value of the invoice.
This only applies as long as we use Simple Invoices. You can make multiple sub-payments on a single invoice that equals the total. You can edit the value of the invoice (before marking it as paid) to reflect the correct payment being made if they overpaid their dues on purpose. You can ignore the actual amount paid and just mark the invoice as being paid for the amount due (if they over paid on purpose). But you will only cause yourself future problems and grief if you ever mark an invoice as being paid for more than the value of the invoice. Consider yourself warned, SI just doesn’t handle this well. This also means that if someone makes a single payment that is the total of multiple invoices, you must still mark each individual invoice as being paid.
Third rule of invoicing
Reconcile paid-ahead members by the 4th of each month.
On the morning of the 5th of each month nanny emails are sent nagging folks who are behind on their dues. Get invoices marked as paid for members who have paid ahead before this happens or you will get angry responses from people who are not actually behind. The google spreadsheet allows us to track who has paid ahead. The reason for having to do this is explained further down, our invoicing system does not gracefully handle payments for invoices that don’t exist yet.
Fourth rule of invoicing
Invoices are sent out on the 1st each month. They become due on the 15th of the same month. Dues are considered late if the payment comes after the 15th. If members only have 1 outstanding invoice, we don't nag them until it goes past the end of the current month. If members have more than 1 outstanding invoice, we fully enforce the 15th as a cut-off date.
The members have been trained to expect this. Adhere to this and there will be less confusion.
What we use for invoicing and why
We use an open source web-based invoicing system called Simple Invoices. At the time (early 2012) when I was looking for an automatic invoicing solution SI was the only one which was 1) free, 2) web-based (so members could check their balances without having to consult the accounts receivable dude), 3) actually worked, and 4) is automatically updated when payments are made via PayPal. There were two other projects which I recall testing out and were completely DOA (code was incomplete and projects were dead). SI, while having some quirks, was the only solution at that time. In practice, item 2 (letting users keep track of their dues balance on their own) has turned out to not be needed because everyone still asks the accounts receivable dude for their balance.
However, another item has turned out to be extremely useful with choosing SI: scripting of processes through the web interface. This is done with shell scripts running on the server that hosts our install of SI and is completely custom. This is now how members get notified when they are behind on dues and threatens to disable their RFID access unless imminent payment occurs. Beyond the time-savings of just the automatic updates when PayPal is used, the automatic notification to users by how much they are behind has shaved several hours of manual work off each month of the accounts receivable dude.
Lastly, the new members management web page has shaved time off of the process of adding members to Bloominglabs via some background automation much like the above paragraph spells out. Among other things, this page reduces the manual work of adding a new member to SI down to 3 check boxes and the manual process of marking the members first invoice as paid.
- Invoicing that is automatically updated when members pay via PayPal saves a lot of time
- Automated nag emails that show how far they are behind are another big time saver
- Chaining other actions by setting an end-date on their invoice recurrence can save even more time when members leave
Wait, there's a spreadsheet too??
Because of the single fact that SI does not handle payments well which have been paid in advance, we have to keep the spreadsheet. The moment SI starts handling payments in advance aka credit balances properly we can ditch the spreadsheet. So, we have to keep the spreadsheet updated when people pay their dues. Once a month the accounts receivable person (by the 4th of the month) has to go through and see which members have "paid ahead" which means the current month's dues are already paid for. Go down the list and then mark the invoice for each member in this condition as being paid.
- User - The account you log in with
- Biller - Bloominglabs
- Customer - Members
- Recurrence - This is an entry, linked to an initial invoice, which generates new invoices on a periodic basis as specified in the entry.
- Statement of invoices - Report listing invoices for a specified member for a given date range
Quirks of Simple Invoices
Something to understand about SI is that there is no native way through the native web interface to remove Customers, paid invoices, payments, and recurrences. Unpaid invoices are one of the few things which can be removed easily as there is a menu item for that. On the same vein, Customers, unpaid invoices, and recurrences may all be edited. However once a payment is registered for an invoice, neither item may be changed.
If there is a screw up in entering something, then phpmyadmin/mysql client can be used to manually clean things up. But don’t make mistakes as it takes time to fix.
The world will not stop spinning if these things are not done as described, it just makes things cleaner for us down the road.
I prefer that when manually marking someone’s invoice as paid, from the Payment menu for a specific invoice, always start at the bottom of the drop-down list and go up. The list of invoices in the drop-down menu are always in chronological order, so choosing the bottom-most one will ensure the members oldest invoice gets paid first. This is a personal preference thing, but helps make things orderly for us when members are chronically behind.
I also only enter the Members name and email in the invoicing system. This is to prevent technical debt later on in the form of outdated address info. I really don’t want to maintain member home addresses across a half-dozen separate systems. This info is fine to live only on their membership app for the time being.
Marking an invoice as paid
This is done via the “Money/Payments” menu. When someone pays with cash, check, or by square you must manually update their invoice as paid. Also if someone makes what I call a “manual paypal payment” you must also go in and update their invoice as paid. This occurs when someone does not use the PayPal link in their invoice, but rather initiates a direct payment to email@example.com for their dues. Currently the default behavior in the default PDF viewer in OSX Mavericks and above is to not open URL’s in PDF’s so there are legitimate reasons some members don’t use the PDF link in their invoice (however they can choose to use an alternative PDF viewer to circumvent this).
Please note that once an invoice is marked as paid it is “locked in”. Before it is paid it can be deleted or the amount changed. However SI does not allow backing out changes though once a payment occurs. If a mistake is made here then phpmyadmin must be used to manually delete the bogus invoice
Lastly, if someone pays more than the dues amount specified on their invoice I edit their invoice amount to match the payment before marking it paid. This keeps things straight and correct with regards to their total balance over time. Also, as in rule of invoicing #2, marking an invoice as paid more than the amount is a nightmare. It will throw off their balance from that point forwards - forever. The next monthly invoice they get will ignore their credit balance even though the system knows it's there. Don't be tempted to do this.
Changing someone from one dues rate to another rate
Lets say a member wants to change their monthly dues rate from $40 a month to $20. So their current recurrence is normally based on their very first invoice in the system. However, to do this properly we have to make a new invoice with his new monthly dues rate ($20 from $40). This is because there are no existing invoices for them in the amount of $20 which we can change this recurrence to.
I could have just changed their February invoice to be $20, then update their recurrence to be based on this invoice (so all future invoices are created with the same value). However they want to still pay the existing February invoice of $40. So instead I created a new invoice for them dated March 1st (and emailed it to them manually from within SI). Next I updated their recurrence to point to the March 1st invoice). Lastly, I changed the start date of the recurrence to be April 1st since there is already a legitimate March 1st invoice in the system. That way they won’t get a second March invoice generated on 3-1.
Also, finding recurrences is tricky because they are only listed by invoice number, the member name is only listed on the edit panel for each one. I lookup someones “statement of invoices” from the “Home/Dashboard” panel to find their very first invoice number then I can find their recurrence from the “Money/Recurrence” panel. It’s a minor nuisance which hopefully will be fixed in a future version of SI.
Making a change to an invoice recurrence
Sometimes you need to make a change to an invoice recurrence for a member. One situation is when you need to change the start date of a new member. This can happen when a new member joins at the end of the month and we agree to apply their first dues towards the coming month. If the person filling out the new-member application didn’t get the memo and leaves in the default date, it will set the new member up to get an automatic invoice at the first of the next month (which they have already paid). Also, there can be an intermittent bug in the new-member app where even though you’ve changed the start-date correctly, it still just uses the next month as the starting date. Either way, you need to manually change the start date of the invoice.
Another situation is when someone changes the amount of dues they are paying monthly, in that case you have to point their recurrence to a different invoice which has the new amount. The second issue is covered here: #Changing_someone_from_one_dues_rate_to_another_rate.
Ok, so here is how we find the correct invoice recurrence. Figuring out which recurrence belongs to which member is tricky because they are only listed by invoice number, the member name is only listed on the edit panel for each recurrence. First I lookup someones “statement of invoices” from the “Home/Dashboard” panel to find their very first invoice number. Then I usually open a second browser tab and go to the recurrence panel under “Money/Recurrence”. Now you can move through the pages until you find the correct invoice number. If you are correcting a recurrence which was just created for a new member then you can probably avoid all of this and just edit the very first recurrence listed. Once you go into the recurrence edit panel, the name of the member will be listed in a drop-down box. This will verify if you have the correct recurrence. You can now make the necessary changes and save them.
Changing the start date of an invoice recurrence
Ending a membership - Stopping automatic invoicing
There are two ways someone’s membership ends
The best way is when someone speaks up and tells us they are ending their membership. Usually this happens before they are behind in dues. This is easy, just set an end date on their recurrence of the last day of the current calendar month (or a future month if they are paid ahead). If they still owe dues, just work with them to get that collected.
The second way people leave is to go silent on the wire and disappear. They never tell us they want to end their membership, late-dues emails are not responded to, and then after they rack up 3 months of back dues it’s time to tie these folks off. Before cutting someone off like this I always try to at least give them a phone call (via number on their membership app), but usually they can’t be reached. Set an end date on their recurrence and remove their outstanding invoices. There’s no need to dick around with them any further, and we’re way too small to litigate over the membership funds we are owed each time someone does this.
Stopping automatic invoicing
The first thing to do is stop their invoice recurrence by setting an end date for it. Start by running a “Statement of invoices” report for the member. Look up their very first invoice. I like to keep this list up until I’m done (by opening a second browser tab for this next step). Next go to the “Money/Recurrence” menu and search for this invoice number (customer names are not listed here which is a pain in the ass). If you don’t find that invoice number, then it means their recurrence is based on one of their other invoices for some reason. Either way, you will have to find an invoice in their “Statement of invoices” which shows up in the recurrence listing before going any further.
Once you find their recurrence, click to edit it, and set an appropriate end date. If they are paid up through the end of the current month, then set the last day of the current month as their end date. If they are past-due and you are disabling their membership with haste, then choose the current date. Just remember that other actions are chained off of this end date. Background scripts will remove them from the members email list (runs weekly on Sundays), and possibly some day we may have RFID access disabled by this end date.
Once the recurrence is handled, if necessary there may be further cleanup needed. If they left unpaid invoices, those can be removed, that can be done manually. When viewing an individual UNPAID invoice, there is an option to delete it (this is not available on the edit menu, only the view menu). However, this is slow and painful if handling a bunch of these at once. Assuming you have shell access to the SI host, the script /home/dosman/bin/cleanup_unpaid_invoices.sh can be used to automatically remove a specific members unpaid invoices for you in one fell swoop.
Lastly, I don’t recommend disabling the member name under the “Customer” menu. The reason is that certain functions are disabled when you do that, like being able to run a statement of invoices for the member (to see how many outstanding invoices they have).
Resending an invoice to a member
Sometimes a member looses track of old unpaid invoices and needs them resent. First, you need to locate their unpaid invoices so run a “Statement of invoices”. Then I like to open a second browser window and then look for their specific invoice number. Note: invoice id’s are different from invoice numbers. Invoice id’s are SI internal references to the invoice, some menus show this number for some reason, don’t get confused. Also, sadly you will have to page through the invoice list to find their invoice number. Once found, from the invoice list there is an email icon next to the invoice which can be clicked, this will take you to another menu where you can complete this process. Also, if you click and view the invoice, there is also an email option from within this menu that can be used.
Manually adding someone to Simple Invoices
This should normally be handled by the new members web page. However it may be required to add new members manually for some reason. This is how to do this.
- Go to the “People” menu and click “Customers”. Then add their details. Please only enter their name and email address, this way we have less information that can get out of sync as it ages.
- Now create their first invoice from the “Money/Invoices” menu.
- Next, you can mark the invoice as paid via the “Money/Payments” menu assuming they have paid.
Lastly, setup a recurrence for them. This way they will get a new invoice every month. Go to the “Money/Recurrence” menu and choose to create a new recurrence. From this menu, choose the new members invoice which should be at the very top of the list in the drop-down menu. Set a start date for the recurrence of the following month. If desired, you can bump the start date up by 2 months if they are joining at the end of a month. This makes it more fair by not penalizing them for joining late in the month.
Updating a members email address
This is simple. Go to “People/Customers” and find the members name. Click to edit their info, and update their email address. Obviously this is important to get right or else the member will not get their monthly dues invoice, nor will they get any nag reminders that they are behind.
Adding a new member who is/was a former Bloominglabs member
This is not a common thing to happen, but it does sometimes. More than likely they already have a "Customer" entry in the system. In this case, when using the New Member Application, un-check the boxes to create a new SI account and recurrence for them. You may need to manually create their first new invoice for this "go-around" and also manually create a new recurrence for them. It's likely they already have a recurrence setup though and it just has an end-date set. You should find their old recurrence and just remove the end-date. Most of the time this will take care of everything, assuming they are paying the same dues rate as they were before. If they are paying a different dues amount now you will need to point the recurrence to a new invoice for them with the current dues rate. See #Changing someone from one dues rate to another rate. Also, it's ok if they have multiple recurrences (one old one that has an end-date and one new one for the current active membership). However I advise you to avoid this just to keep the system free of cruft. But it's not a problem as far as I know.
Also, as stated somewhere in the above directions, you should not mark the SI account of former members as "disabled". If they have an old account that is disabled for some reason, you will need to change that before you can make any new invoices for them or change their old recurrence.
Last but not least, if you accidentally create a 2nd SI account for them then there are two options. 1) ignore it. 2) dredge up phpmyadmin and edit the database to remove the 2nd account. There is no native way in SI to do this. The same goes for recurrences, phpmyadmin is the only way to remove duplicate entries.
#1: The case of the double payments
Once I started running into a problem where someone had invoices due but their balance was different from the total of the outstanding invoices. I finally figured out how it kept happening each month. At the time I didn't even realize you could make multiple payments to a single invoice. But anyway, this member had paid ahead in cash. So at the first of the month I marked their invoice as paid per the usual custom of reconciling the spreadsheet to SI as in Rule #3. However afterwords, the member was still paying their invoice through PayPal via the link in their invoice and I didn't notice this. So now there were two $40 payments on a single $40 invoice. I believe they got one month behind at one point. The nag system spotted this and emailed them about the unpaid invoice, but it showed their balance in the system which did not match the outstanding invoices, this is how I found the problem to begin with.
To fix this I had to use phpmyadmin to remove the second payments to each invoice. Since they missed a month and they were actually paid ahead a month that stopped the problem in this case. But it's a weird edge-case to know about - even if you mark an invoice as paid manually, the member can accidentally cause a problem by paying their invoice AGAIN through PayPal if you haven't communicated what you are doing with them.
Our extensions to SI
This is not intended to be a technical document so I've put this info on the technical Simple Invoices page at the bottom (Scripts we have bolted on to SI). This is basically a number of external helper scripts that provides the nag emails and other notification functionality that is lacking in SI.
So you wanna switch to something else
Some words of advice for anyone coming in who wants to make things better. If there's something better than SI that's great (I'm sure it has to exist out there). Just make sure these things are handled when you go-live or else you are signing yourself up for many hours of additional work each month:
- Automatic nag emails that include how far they are behind - if you don't have this in place you just signed up for a minimum of 10 hours of manual work each month.
- We essentially have 4 separate nag emails that are sent out at different times of the month, details can be found here: Simple_Invoices#Scripts_we_have_bolted-on_to_SI. You don't have to replicate this exactly, but you need SOMETHING that does most of this for you automatically. Consider yourself warned.
- Automatic invoices sent via email - nuff said.
- Accepts PayPal - 2/3rds of our members are already trained to use paypal via the invoice they get, don't make life harder for the good ones.
- Ability to chain events off of memberships that end - automatic disabling of RFID and removal from the members email list is a time saver, but not a huge deal as our turnover isn't that huge.