Ruby Invoicing Framework

Ruby Invoicing Gem version 0.2 — Now with generator

2009-04-21T00:00:00-07:00

Updated 2009-04-26: added video of the talk

Yesterday was a busy day: in the morning I released the new version 0.2 of the invoicing gem, and in the evening I presented a live demo of the latest version at the London Ruby User Group.

The format of my talk was an attempt to replicate a screencast, but given completely live. The result was pretty hilarious, and Skills Matter, who host the LRUG events, kindly recorded the talk and put it online:

Since I didn’t have any slides for the talk I will simply share the notes which I wrote for myself in preparation. You might be able to use them to follow along with what I was doing.

About the invoicing gem

Commercial app: start with paypal; gets complicated soon – VAT, resellers/affiliates, …
You don’t parse HTTP headers yourself; you shouldn’t need to juggle credits+debits yourself
Developer friendly AND accountant-friendly

Roadmap:

v0.1: get basics right (core ledger, multi-currency, time-dependent values)
v0.2: script/generate invoicing_ledger – render ledger/statement/invoice
v0.3: script/generate invoicing_taxable – support European VAT out of the box
v0.4: higher-level tools (subscriptions, price plans, affiliate programmes)

Cracktastic preparation

Cracktastic is a simple and contrived example Rails app into which we want to integrate the invoicing gem. Check out the head of the master branch. Start with a clean database and run rake db:migrate.

Set up ledger

Invoke generator:

script/generate invoicing_ledger billing --currency=GBP
rake db:migrate

Manually edit app/models/billing/ledger_item.rb:

belongs_to :sender, :class_name => 'Company'
belongs_to :recipient, :class_name => 'Company'

def sender_details
  sender.attributes.symbolize_keys
end

def recipient_details
  recipient.attributes.symbolize_keys
end

Create custom invoice type

Add new model classes:

module Billing
  class SubscriptionInvoice < Invoice
    def initialize(*args)
      super
      self.status ||= 'open'
      self.period_start ||= Time.now.utc.at_beginning_of_month
      self.period_end ||= period_start.next_month.at_beginning_of_month
      self.issue_date ||= period_end
      self.due_date ||= period_end + 14.days
      self.description ||= "Cracktastic subscription for " +
        period_start.strftime('%B %Y')
    end
  end
end

module Billing
  class MonthlySubscriptionCharge < LineItem
    before_validation :calculate_tax

    def initialize(*args)
      super
      self.tax_point ||= Time.now.utc
      self.description ||= "Monthly subscription, standard package"
    end

    def calculate_tax
      self.tax_amount = 0.15*net_amount
    end
  end
end

Integrate with `restful_authentication`

Edit generated billing_controller.rb:

before_filter :login_required

def index
  redirect_to ledger_url(current_user.company)
end
    
def ledger
  raise ActiveRecord::RecordNotFound unless current_user.company_id.to_s == params[:id]
  #...
end

def statement
  raise ActiveRecord::RecordNotFound unless current_user.company_id.to_s == params[:id]
  #...
end

def document
  @ledger_item = Billing::LedgerItem.sent_or_received_by(current_user.company_id).find(params[:id])
  #...
end

Add to main menu in app/views/layouts/application.html.erb:

<% if logged_in? -%>
  <li><%= link_to 'Billing', ledger_path(current_user.company) %></li>
<% end -%>

Create example records

Open up script/console:

ourselves = Company.find(1)
customer = Company.find(2)

# Closed invoice for last month
inv = Billing::SubscriptionInvoice.new(
  :period_start => Time.now.utc.last_month.at_beginning_of_month)
inv.sender = ourselves
inv.recipient = customer
inv.line_items << Billing::MonthlySubscriptionCharge.new(:net_amount => 99.95)
inv.save!
inv.status = 'closed'
inv.save!

# Payment for last month
pay = Billing::Payment.new :total_amount => 114.94, :status => 'cleared', 
  :description => 'Credit card payment', :issue_date => 3.days.ago.utc
pay.sender = ourselves
pay.recipient = customer
pay.save!

# Open invoice for current month
inv = Billing::SubscriptionInvoice.new
inv.sender = ourselves
inv.recipient = customer
inv.line_items << Billing::MonthlySubscriptionCharge.new(:net_amount => 99.95)
inv.save!

Then reload the mongrel and open /billing in the app to see the results.

Credit notes

ourselves = Company.find(1)
customer = Company.find(2)

note = Billing::CreditNote.new(
  :period_start => Time.now.utc.last_month.at_beginning_of_month,
  :period_end => Time.now.utc.at_beginning_of_month,
  :issue_date => Time.now.utc,
  :description => 'Refund', :status => 'closed')
note.sender = ourselves
note.recipient = customer
note.line_items << Billing::MonthlySubscriptionCharge.new(
  :net_amount => -50, :description => 'Special half-price offer')
note.save!

Note the negative amount on the line item.

CurrencyValue magic

In script/console:

inv = Billing::Invoice.new :currency => 'USD'
line = Billing::LineItem.new :net_amount => 12.34
inv.line_items << line
inv.save!

line.net_amount.to_s
# => "12.34"
line.net_amount_formatted
# => "$12.34"
line.tax_amount = 0.15 * line.net_amount
# => 1.851
line.tax_amount.to_s
# => "1.85"         <==== automatically rounded to 0.01 precision
line.tax_amount_formatted
# => "$1.85"

inv.currency = 'JPY' # Smallest currency unit in Japanese yen is 1
line.net_amount_formatted :symbol => 'JPY'
# => "12 JPY"       <==== automatically rounded to integer
line.tax_amount_formatted :symbol => 'JPY'
# => "2 JPY"

You can also leave away the :symbol => 'JPY' bit, in which case it will be rendered as “¥12” and “¥2” respectively.

Multi-currency support

In script/console:

ourselves = Company.find(1)
customer = Company.find(2)

inv = Billing::SubscriptionInvoice.new(
  :currency => 'JPY', :status => 'closed', :description => 'Commission charges')
inv.sender = customer
inv.recipient = ourselves
inv.line_items << Billing::MonthlySubscriptionCharge.new(
  :net_amount => 23, :description => 'Referral commission')
inv.save!

See the results in a web browser. Also demonstrates customer charging ourselves, i.e. acting as supplier to us.

UBL support

Append .xml to the URL of an invoice document.

Automatic tax calculation

NOTE: This is a feature from the upcoming 0.3 release of the gem. It will not work with the version currently released to Rubyforge.

Run the generator:

script/generate invoicing_taxable UK
rake db:migrate

In file app/models/billing/line_item.rb, add:

belongs_to :tax_rate
acts_as_taxable :net_amount, :tax_logic => Invoicing::Countries::UK::VAT.new

def initialize(*args)
  super
  self.tax_point ||= Time.now.utc      
  self.tax_rate ||= TaxRate.default_record_at(tax_point)
end

From app/models/billing/monthly_subscription_charge.rb, remove the calculate_tax stuff.

In script/console:

ourselves = Company.find(1)
customer = Company.find(2)

inv = Billing::SubscriptionInvoice.new :period_start => '2008-11-01', :status => 'closed'
inv.sender = ourselves
inv.recipient = customer
nov = Billing::LineItem.new(:description => 'random 1',
  :net_amount => 10, :tax_point => '2008-11-30')
dec = Billing::LineItem.new(:description => 'random 2',
  :net_amount => 10, :tax_point => '2008-12-01')
inv.line_items << nov
inv.line_items << dec
inv.save!

nov.amount_formatted
# => "10.00"
nov.amount_taxed_formatted
# => "11.75"
nov.amount_with_tax_info
# => "11.75 (inc. VAT)"
nov.amount_with_tax_details
# => "11.75 (including VAT at 17.5%)"
dec.amount_formatted
# => "10.00"
dec.amount_taxed_formatted
# => "11.50"
dec.amount_with_tax_info
# => "11.50 (inc. VAT)"
dec.amount_with_tax_details
# => "11.50 (including VAT at 15%)"

And that’s it

Open /thankyou in web browser to show my contact details on the projector.

If you’re thinking of using the invoicing gem, or have any questions, or want to submit patches, or anything… let me know!

Please help me spread the word, tag your tweets with #invgem, subscribe to the invoicing gem feed, give the gem a try, browse the docs and the source, and let me know what you think!

Ruby Invoicing Gem version 0.1 released

2009-02-12T00:00:00-08:00

Here it is, the first public release of the Ruby Invoicing Framework gem! In case you don’t know what it is, check the website – in a nutshell, it is a bunch of tools and a structure which can be used inside commercial (web) applications to handle billing of customers, tax calculations, and other financial matters.

The core of the invoicing gem was born in mid-2008 while I was working on the Rails app Bid for Wine, an eBay-style auction site specifically for wine, alongside Patrick Dietrich, Conrad Irwin and Michael Arnold. Our client required a very flexible invoicing system for the site: not only should the site be able to invoice sellers for listing fees and commissions, but sellers should also be able to send invoices to their buyers, directly via the site. Some sellers are VAT registered while others are not, which adds another dimension. What’s more, due to UK alcohol trade licensing legislation, some transactions must be handled with Bid for Wine as intermediary – i.e. the seller invoices Bid for Wine, and Bid for Wine invoices the buyer. Add in-bond wine to the mix (wine on which duty has not yet been paid – it is stored in a special warehouse and the taxman gets his money when you take it out of the warehouse), and you end up with a massively confusing array of different transactions.

Natural, therefore, that we would build a system which was flexible and generalised enough to cope with a wide variety of different transaction types.

Since Bid for Wine launched in November 2008, I have found myself wanting to use such a framework for financial transactions in other applications too. I realised that even if you have a simple web app with, say, a monthly subscription model, you will inevitably end up adding complexity over time: for example, if you want to partner with resellers (and pay them a commission, or invoice them at a preferential rate), if you want to trade in other currencies, and of course you may have to implement whatever new tax regulations the political forces may dream up.

I knew nothing about bookkeeping and accountancy until a year or so ago, when I started doing the accounts for my company. It was a fairly painful process, because I am very much a developer and a computer scientist, and the accountants’ way of thinking first made no sense to me whatsoever. The principles of accrual accounting and double-entry bookkeeping are perfectly sensible and sound, but the terminology and practical implementation I found just plain confusing.

After learning the basics of accounting, I still find it dead boring. And that is really the reason why I took the Bid for Wine code in January 2009 and started extracting a general-purpose finance handling framework out of it: I wanted to find a neat representation of the data, one which made both me as a developer happy and also satisfied the accountants; and I wanted to package it up so that I wouldn’t have to think about the financial stuff any more than necessary: I wanted to make it go away, not by ignoring it, but by automating it as much as possible, and by explaining it in a way which doesn’t require you to know any accounting jargon.

What I have now released, the Invoicing gem version 0.1.0, is the combination of all the experience we gathered while developing Bid for Wine with several weeks of my full-time work. Despite the young version number, this is already a pretty solid and stable framework. I waited with the first release until I felt that the core API was well enough thought out that I could minimize the number of backwards-incompatible changes in the upcoming minor versions up to 1.0.

And even this very first public release is thoroughly documented and tested. In fact, about half of the 3,300 lines of library code are actually documentation, and the code has 100% rcov coverage through unit tests. Databases currently supported are MySQL and PostgreSQL, and the gem depends on ActiveRecord 2.1 or higher.

The feature list includes a lot of things which you know you ought to have, but you probably wouldn’t bother implementing yourself. For example, when we first developed Bid for Wine, the VAT rate was set in a constant; however, within a month of launching, the UK government decided to change the VAT rate (with one week’s notice!), and I had a bit of a panic to implement a tax rate change feature in our application. (It’s not as simple as changing the value of the constant, because the VAT applied to the price of an auction is the rate applicable at a point in time in the future, namely the time when the auction ends – so you can have different items taxed at different rates on the site simultaneously.)

Needless to say, the invoicing gem includes a feature for handling tax rate changes neatly out of the box. And that was just an example. See the invoicing gem overview page for a list of features.

Yesterday I met up with Ben Summers, who is using the invoicing gem in his soon-to-be-launched online information management system OneIS. He is delighted at how much time it is saving him, and at the future possibilities which the invoicing gem already offers now.

And I have plenty of plans for the future. But more on that another day.

Please help me spread the word, tag your tweets with #invgem, subscribe to the invoicing gem feed, give the gem a try, browse the docs and the source, and let me know what you think!

Ruby Invoicing Framework

Ruby Invoicing Gem version 0.2 — Now with generator

About the invoicing gem

Cracktastic preparation

Set up ledger

Create custom invoice type

Integrate with restful_authentication

Create example records

Credit notes

CurrencyValue magic

Multi-currency support

UBL support

Automatic tax calculation

And that’s it

Ruby Invoicing Gem version 0.1 released

Integrate with `restful_authentication`