Recurring invoices

Starting with version 2.0, ccInvoices now supports (automated) recurring invoices! To start using the recurring invoice functionality, you need to update to ccInvoices 2.0 or higher and enable the “ccInvoices – Invoice updates” plugin.

Disclaimer

Before you start using the recurring invoice functionality, please take note of our disclaimer.

Although we strive to create stable and useful software, you should realise that the correct initial configuration, and occasional review of your ccInvoices installation is completely your responsibility. We expect that you review your normal and recurring invoices occasionally to make sure that invoices are being automatically created and sent correctly. We also expect that you review and are known with the contents of this manual.

We do not take responsibility for invoices not being generated (automatically) for any reason. Due to the fact that our software is downloadable and installed on your own hosting account/server, we do not have backend access to your site and in no way can keep track of the correct functioning of recurring invoices on your specific server setup. This disclaimer is an extension of our Terms & Conditions and the GPL software license.

Getting started with recurring invoices

• Updating to the latest ccInvoices version is explained in our manual. It should be relatively safe to update, but we advise always creating a backup!
• After updating, go to Extensions > Plugin Manager  and search for “ccInvoices”
• Find the “ccInvoices – Invoice updates” plugin and enable it
• Now, go to Components > ccInvoices where you should notice a new menu option in the sidebar, called “Recurring”

How do the recurring invoices work?

Recurring invoices are invoices that automatically repeat every “repeat interval”, where the “repeat interval” is defined by the user (that’s you!) in a dropdown. Possible repeat intervals at this moment are: Weekly, Monthly, Quarterly and Yearly. There can be multiple recurring invoices with a different repeat time in every ccInvoices installation.

The “Invoices” section in ccInvoices remains unchanged compared to past versions. The recurring invoices process is developed as a separate section with a few differences compared to the normal invoices section. At the “Invoice date” specified for a recurring invoice, a new invoice will be created using the details of the recurring invoice as template, and that new invoice will be added to the “Invoices” section. The recurring invoice will then be updated to be ready for the next invoice on the new “Invoice date”.

Let’s repeat the process again, just to be clear:

1. User creates a recurring invoice in “Recurring” section
2. On the correct “Invoice date” a new invoice is created in “Invoices” section based on “Recurring invoice” details
3. The recurring invoice “Invoice date” is updated to the next repeat time, to generate a new invoice on the new “Invoice date”

So the “Recurring” section is actually a database with “source” or “template” invoices that repeat (or recur), they are not actual invoices themselves, they do not have an invoice number in the same #__ccinvoices_invoices database. New invoices created by a recurring invoices are added in #__ccinvoices_invoices and not in #__ccinvoices_recurring.

To handle a few of the automatic functions we have developed a plugin called the “ccInvoices – Invoice updates” plugin.

Overview video of recurring invoices

In this short video you will see David de Boer, the developer of ccInvoices
explaining the How To.

• David logs in to the Joomla! administrator
• ccInvoices is installed in Extensions  > Extension Manager > Install
• In ccInvoices (Components > ccInvoices > Invoices) there are no regular invoices at this moment
• A recurring invoice is created via Components > ccInvoices > Recurring, you see the options specific to recurring invoices like the “Repeat” dropdown with options Weekly, Monthly, Quarterly, Yearly. You also see that the “Invoice date” is 2015-02-27. This is the date on which the new invoice should be created, and this date will be automatically adjusted to the next “Repeat” date (2015-03-27 because the recurring invoice is set to Monthly).
• Under Extensions > Plugin Manager David searches for the “ccInvoices – Invoice updates” plugin and enable it, so it can start automatically creating the invoices (you only need to do this once)
• David goes back to ccInvoices via Components > ccInvoices > Invoices and you will see there is a new invoice, just created by ccInvoices
• The “Invoice date” in the “Recurring” section is indeed now 2015-03-27, and this is the date a new invoice will be automatically created again

Thank you David!

Creating a new recurring invoice

To create a new recurring invoice, go to Components > ccInvoices > Recurring and hit the “New” button in the toolbar. We have added a little question mark “help” icon behind the options in the details section, that explain what every option does.

If you like reading (who doesn’t, right?), here is a list of things that are different in “Recurring edit” compared to the regular “Invoice edit”.

• There is no “This invoice has already being sent” message in the recurring invoice edit view at all. This message normally shows in the “Edit invoice” view when the invoice is already sent to the contact and you open it afterwards.
• By far the coolest change: the “Repeat” dropdown! Options are: Weekly, Monthly, Quarterly and Yearly. The dropdown allows you to tell ccInvoices how often an invoice needs to be repeated.
• There is no “Invoice number” field because the invoice number is only set when the invoice is created and saved in “Invoices” database. Recurring invoice “templates” do not have invoice numbers.
• There is an “Recurring ID” field in the spot where normally the “Invoice number” would be, the “Recurring ID” can not be changed and is unique and sequential.
• You can completely disable a recurring invoice with the “Active” field and selector with options Yes/No
• Compared to the “Edit invoice” view the “Due date” in “Edit recurring” is called “Due days” and is auto-populated with the amount from “Due days” in the configuration. It can be changed per recurring invoice. We use a field with an amount instead of a date picker so it is easier to calculate the due date for future invoices created by this recurring invoice.
• Status dropdown should only show options “DRAFT” and “OPEN”
• The options “Re-send invoice to contact” and “Send reminder to contact” should not be shown in Recurring Edit.

Invoice status and (automatic) emails

The invoice status is important, because different statuses can be used in recurring invoices. Almost all statuses should be ignored by the email process, except OPEN invoices where “Send invoice to contact” is selected. Examples:

• You might want to review an invoice created by a recurring invoice before sending it or doing anything else with it. In that case, set the recurring invoice status to DRAFT, and the generated invoice by the plugin will be DRAFT as well and shall be ignored by the email process of the plugin and not receive an invoice number (DRAFT invoices never have an invoice number).
• You might want the generated invoice to have status “OPEN” but not email it to your customer. In that case set status to “OPEN” but do not select “Send invoice to contact” in the recurring invoice. That setting wil also not be selected in the generated invoice. The invoice shall be ignored by the email process of the plugin.
• If you want the invoice to be sent to the customer by e-mail immediately on creation, set the recurring invoice to status “OPEN” and select “Send invoice to contact”. This will also be copied to the generated invoice. The plugin will send the normal “Invoice email” template to the customer.

Don’t worry about ghost invoices

We have added a small warning under “Details” in the “Edit invoice” view. This will help you see where an invoice came from, so you do not have to wonder:

• Is it created by a recurring invoice?
• Did I create this invoice and forget about it?
• Do I need to call the Ghostbusters?

The message “This invoice was auto-generated from Recurring #0000X” will only be shown when an invoice is automatically created by a recurring invoice. It also has a link to the recurring invoice (if the recurring invoice was not deleted after doing it’s job) so you can quickly check out it’s details.

The “ccInvoices – Invoice updates” plugin

The “ccInvoices – Invoice updates” loads on every page load and checks the recurring invoice database to see whether there is a recurring invoice that needs to be generated. When installed only on new websites or updating from ccInvoices versions before 2.x, the plugin will be disabled by default. When upgrading from ccInvoices 2.0, the status of the plugin will not be adjusted.

The plugin loads (unlimited) on every page load of the Joomla! site (onAfterInitialise). On every page load, it searches for recurring invoices and processes one if it finds any. The plugin checks the #__ccinvoices_recurring database, and checks if there are recurring invoices with a “Invoice date” that matches the current date or older and is “Active”. That means it also processed recurring invoice from yesterday, or 3 weeks ago. When there is a match it runs the below process.

• Copy recurring invoice details to invoices database table
• Take contact details “fresh” from contact database table
• Add recurring ID to the newly created invoice as a reference
• Generate due date in newly created invoice  (current date + due days)
• Update recurring invoice “invoice date” to next repeat time (invoice date + repeat interval)
• Send invoice email depending on invoice status and “Send to contact” setting

Disabling the “Invoice updates” plugin from the database

So, generating an invoice from a recurring invoice happens via the “ccInvoices – Invoice updates” plugin. If, for whatever reason, this plugin fails to work and/or creates (PHP) errors on your site, you can disable it via the Joomla! Plugin Manager or directly in the database. To disable it in the database:

• Login to your database, for example with PHPMyAdmin
• Search for the table xyz_extensions (where xyz_ is the custom database prefix for your site)
• In the list of extensions, search for “ccInvoices – Invoice updates” in the “name” column
• Open the row belonging to “ccInvoices – Invoice updates” and in the “enabled” column set 1 to 0
• The “ccInvoices – Invoice updates” plugin is now disabled