When working with money in an application, ensuring everything is accounted for is important.
In this post, we will explore some common methods and best practices of handling money in your Ruby app, and see how you can use money-rails
to write maintainable money-handling code.
Let's get started!
Use Cases for Storing Money
There are several use cases where your Ruby app might need to handle money — for example, an e-commerce company that sells products, a SaaS maintaining users' subscriptions, etc.
In this post, we will walk through some examples of how to handle money in an e-commerce app.
Storing Money in a Ruby Database
First, let’s start with strategies for storing money in your database: using a float column, the numeric
type, and the integer
type.
Using a Float Column
The most obvious way to store money is to use a float column. However, because of the way floating-point numbers are stored, they do not guarantee exactness. Instead, they only approximate the actual value. While this might be sufficient for some applications, there are much better ways to store money.
Using the numeric
Type
The numeric
type can store arbitrary-precision numbers in a database.
A numeric column can store a large range of numbers (up to 131,072 digits before a decimal point and up to 16,383 digits after a decimal point) and is therefore perfectly suited to work with money.
But one important point to note here is that calculations on numeric types are very slow compared to integer/floating-point numbers.
Numeric types should be the go-to data type when you need arbitrary-precision numbers, but, depending on business logic, they are rarely needed unless it's for very specific use cases. Let’s see if we can do better in an e-commerce scenario.
Using the integer
Type
We need to store the prices of products, with the lowest unit being cents.
A product can be priced at $19.99
but never $19.9954321
.
This means that, instead of working at the dollar level, we will always have an integer value as the price at the cents level.
We can easily store an integer without any approximation in the database using one of the integer types (e.g., smallint
, integer
, bigint
).
But please note that this does constrain the represented values (as compared to the numeric
type) — the maximum integer
value on Postgres 2147483647
will be $21,474,836.47
.
This should normally be enough for any e-commerce product, but it’s good to know that there’s a limit.
If you require higher precision (for example, a 10th of a cent), this is possible by just storing the amount as a mill instead of cents.
Keep in mind that this will further decrease the range of values that can be represented in an integer column.
But an integer
's big advantage over a numeric
type is that calculations are very fast.
As long as you can work within the integer (or bigint
) range and have clear constraints set, using an integer
/bigint
is the recommended storage option.
Sorting out storage is just the first step to representing money in our Ruby application, though.
You might also need to handle different currencies, formatting the values based on the location of users (e.g., USD is formatted as $1,234.56
, whereas the same amount in Euros is formatted as €1.234,56
).
While it is possible to implement this manually, a gem like money-rails
can handle it out of the box for you.
Enter money-rails
for Ruby on Rails
Money-Rails integrates the money
gem in Rails.
It can handle automatic conversion between the database representation of money to Money
instances. These instances can then be used to access all helpers available from the money
gem (we will get to an overview of those helpers later in this post).
Additionally, money-rails
also has helpers for migrations and configurable validation options.
Let’s start by creating a product with a price.
We'll use the monetize helper to do that:
# db/migrate/20230803062226_create_products.rb class CreateProducts < ActiveRecord::Migration[7.0] def change create_table :products do |t| t.string :title, null: false t.monetize :price, null: false t.timestamps end end end
t.monetize :price
adds price_cents
and price_currency
columns to the table.
In addition to this, we need to mark the price_cents
column that money-rails
will control in the model.
# app/models/product.rb class Product < ApplicationRecord monetize :price_cents end
With just a few lines, we now have access to a lot of helpers.
We can create a new product by simply passing a price attribute.
The price
will automatically be converted to a cent value for the database. When accessing the price
later, we will have instances of Money
.
irb> product = Product.new(title: "Foo", price: 19.99) # => #<Product:0x0000000108ff9e30 id: nil, title: "Foo", price_cents: 1999, price_currency: "USD", created_at: nil, updated_at: nil> irb> product.price # => #<Money fractional:1999 currency:USD>
You can also pass the attributes directly:
irb> product = Product.new(title: "Foo", price_cents: 1999, price_currency: "EUR") # => #<Product:0x0000000108ff2130 id: nil, title: "Foo", price_cents: 1999, price_currency: "EUR", created_at: nil, updated_at: nil> irb> product.price.format # => "€19,99"
Currency in the money
Gem for Ruby
Currencies are consistently represented as instances of Money::Currency
.
This not only includes the name of the currency, but a lot of additional information like the name, symbol, iso code, etc.:
irb(main):042:0> product.price.currency # => #<Money::Currency id: usd, priority: 1, symbol_first: true, thousands_separator: ,, html_entity: $, decimal_mark: ., name: United States Dollar, symbol: $, subunit_to_unit: 100, exponent: 2, iso_code: USD, iso_numeric: 840, subunit: Cent, smallest_denomination: 1, format: >
Check out the money
gem's currency documentation.
Let's say you only have a single currency in your application and don’t need to track currency inside your database.
First, set a default currency for money
in an initializer:
# config/initializers/money.rb MoneyRails.configure do |config| # set the default currency config.default_currency = :usd end
In the migration, disable the currency column:
# db/migrate/20230803062226_create_products.rb class CreateProducts < ActiveRecord::Migration[7.0] def change create_table :products do |t| t.string :title, null: false t.monetize :price, null: false, currency: { present: false } t.timestamps end end end
There are many other Money-Rails migration helpers that allow null values for amounts or configure default amounts/currencies.
Validations with monetize
You can configure validations on money using the monetize
Active Record helper.
To do this, update your model to opt in for validations:
class Product < ApplicationRecord monetize :price_cents, numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1000 } end
Now, if you try to save a product with an invalid price, validation will fail:
irb> product = Product.new(title: "Foo", price: -10) irb> product.save! # => raise_validation_error: Validation failed: Price must be greater than or equal to 0 (ActiveRecord::RecordInvalid) irb> product.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=price, type=greater_than_or_equal_to, options={:allow_nil=>nil, :value=>-10, :count=>0}>]>
Localization
Money can be configured to either use the location information provided by i18n
or to localize based on the amount’s currency.
Use the locale_backend
to configure this — usually in an initializer like this:
# config/initializers/money.rb Money.locale_backend = :currency
In the above example, we set it to :currency
. This uses the formatting rules defined for each currency:
irb> product = Product.new(title: "Foo", price_cents: 15_999_00, price_currency: "USD") irb> product.price.format # => "$15,999.00" irb> product.price_currency = "EUR" irb> product.price.format # => "€15.999,00"
To configure a consistently formatted amount regardless of the amount’s currency, use the :i18n
locale backend:
irb> Money.locale_backend = :i18n irb> I18n.locale = :en irb> Product.new(title: "Foo", price_cents: 15_999_00, price_currency: "USD").price.format # => "$15,999.00" irb> Product.new(title: "Foo", price_cents: 15_999_00, price_currency: "EUR").price.format # => "€15,999.00"
When using the locale backend i18n
, it is also possible to configure the formatting using the translation files:
# config/locale/en.yml en: number: currency: format: delimiter: "," format: "%u%n" precision: 2 separator: "." significant: false strip_insignificant_zeros: false unit: "$"
Note that if you are using rails-i18n
, configuration is automatically available for many locales.
Computations
Money instances are usable as regular numerical values with all operators, so you can compare values and perform arithmetic operations (using +
, -
, *
, /
).
This makes it much more intuitive to perform operations on objects containing money.
# Comparisons - both value and currency must be equal for equality irb> p1 = Product.new(price_cents: 1000, price_currency: "USD") irb> p2 = Product.new(price_cents: 1000, price_currency: "USD") irb> p1.price == p2.price # => true
Since mathematical operators work as expected, you can easily compute sum/average or price discounts.
# Compute invoice total by summing all line item amounts irb> item = LineItem.new(amount_cents: 1000, amount_currency: "USD") irb> discount = LineItem.new(amount_cents: -250, amount_currency: "USD") irb> total = item.amount + discount.amount # => #<Money fractional:750 currency:USD> # Find the average price of a product irb> average = Product.sum(&:price) / Product.count # => #<Money fractional:1000 currency:USD>
If you need to access the underlying value from a Money instance, you can do that using amount
or cents
:
irb> Product.new(price_cents: 1000, price_currency: "USD").amount # => BigDecimal(10) irb> Product.new(price_cents: 1000, price_currency: "USD").cents # => 1000 (Integer)
Currency Exchange
If you are working with multiple currencies, you can automatically convert two different currencies based on exchange rates using exchange rate stores.
The default implementation is just an in-memory store.
It stores the exchange rates you provide using Money.add_rate
.
To use it, first add a rate. Then, you can use the exchange_to
method to convert a money object to another currency.
irb> Money.add_rate("USD", "EUR", 0.92) irb> Product.new(price_cents: 1000, price_currency: "USD").price.exchange_to("EUR") # => #<Money fractional:920 currency:EUR>
If a conversion rate is not present, it raises a Money::Bank::UnknownRate
exception.
irb> Product.new(price_cents: 1000, price_currency: "USD").price.exchange_to("EUR") # => No conversion rate known for 'USD' -> 'INR' (Money::Bank::UnknownRate)
So, if you are using this in production, you must provide the exchange rate before you perform any conversions.
You can provide a custom exchange rate store to handle this automatically. There are also some exchange rate implementations already available as gems.
For example, you can drop in the eu_central_bank
exchange rate store to fetch the latest exchange rates from the European Central Bank.
Once the gem is installed, you can set it as the default bank in the initializer:
# config/initializers/money.rb require 'eu_central_bank' eu_bank = EuCentralBank.new Money.default_bank = eu_bank # Update rates from the EU Central Bank # Ideally this should be performed periodically in a cron job. # If you need conversions rarely, you can call it before using exchange_to. eu_bank.update_rates
Once set up, you can simply exchange any currency, and it should work:
irb> Product.new(price_cents: 1000, price_currency: "USD").price.exchange_to("EUR") # => Money.from_cents(92, "EUR")
Wrap Up
In this post, we saw how to store and work with money in a Rails application.
Money-Rails greatly simplifies the whole process and provides helper methods that make working with money safer and more maintainable in the long run.
Many other options are available to customize this for your Ruby on Rails app.
Check out the full details in the money
and money-rails
guides.
Happy coding!
P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!