shopify-money

When using Money::Allocator#allocate, you can specify a rounding strategy to determine how leftover subunits are distributed. Strategies include:

• :roundrobin: Assigns leftover subunits from left to right.
• :roundrobin_reverse: Assigns leftover subunits from right to left.
• :nearest: Assigns leftover subunits to the nearest whole subunit.

You can set a global default via Money.configure or pass the strategy as an argument to the allocate method.

# Global default
Money.configure do |config|
  config.default_allocation_strategy = :nearest
end

# Per-call strategy
m = Money.new(10.55, "USD")
m.allocate([0.25, 0.5, 0.25], :nearest)

# Assigns leftover subunits left to right
m = Money::Allocator.new(Money.new(10.55, "USD"))
monies = m.allocate([0.25, 0.5, 0.25], :roundrobin)

# Assigns leftover subunits right to left
m = Money::Allocator.new(Money.new(10.55, "USD"))
monies = m.allocate([0.25, 0.5, 0.25], :roundrobin_reverse)

# Assigns leftover subunits to the nearest whole subunit
m = Money::Allocator.new(Money.new(10.55, "USD"))
monies = m.allocate([0.25, 0.5, 0.25], :nearest)

To store money in a database, use a decimal column. The money_column method generates methods for ActiveRecord models to handle the conversion between the database decimal and Money objects.

Database Requirement: money_column expects a DECIMAL(21,3) field.

Implementation Example

# Migration
create_table :orders do |t|
  t.decimal :sub_total, precision: 21, scale: 3
  t.decimal :tax, precision: 21, scale: 3
  t.string :currency, limit: 3
end

# Model
class Order < ApplicationRecord
  money_column :sub_total, :tax
end

money_column Options

While Money::NullCurrency is available for backwards compatibility, it is a placeholder currency that behaves like a dollar. Using it can lead to unexpected behavior in database validations or GraphQL enums because its string representation may not be supported.

Preferred Alternatives:

1. For comparisons: If you are unsure of the currency, use Numeric predicate methods like #positive?, #negative?, #zero?, or #nonzero?. You can also use standard comparison operators (==, !=, <=, >=, <, >) against Numeric values.
2. For zero values: Prefer using Money.new(0, currency) instead of using NullCurrency to ensure better currency safety and compatibility with external systems.

Unique Behavior: Unlike standard currencies, performing arithmetic between a NullCurrency object and another currency will result in a Money object using the other currency.

# Preferred comparison approach
Money.new(1, 'CAD').positive? #=> true
Money.new(2, 'CAD') >= 0      #=> true

# Arithmetic with NullCurrency results in the other currency
Money.new(0, Money::NULL_CURRENCY) + Money.new(5, 'CAD')
#=> #<Money value:5.00 currency:CAD>

You can extend the supported currencies via configuration.

Crypto Currencies

Enable support for currencies defined in crypto.yml:

Money.configure do |config|
  config.experimental_crypto_currencies = true
end

Custom Currencies

Load custom currency definitions from a YAML file:

Money.configure do |config|
  config.experimental_custom_currency_path = Rails.root.join("config/custom_currencies.yml")
end

Example custom_currencies.yml format:

credits:
  iso_code: "CREDITS"
  name: "Loyalty Points"
  symbol: "CR"
  disambiguate_symbol: "CR"
  subunit_to_unit: 1
  smallest_denomination: 1
  decimal_mark: "."

# Enable crypto
Money.configure do |config|
  config.experimental_crypto_currencies = true
end

# Load custom YAML
Money.configure do |config|
  config.experimental_custom_currency_path = Rails.root.join("config/custom_currencies.yml")
end

The library provides advanced methods for dividing money without losing pennies due to rounding errors.

Splitting evenly

split(n) divides money into n parts. If the division isn't perfect, leftover subunits are assigned to the first chunks.

m = Money.new(1000, "USD")
m.split(3).map(&:value) == [333.34, 333.33, 333.33]

Proportional allocation

allocate(proportions) distributes money based on an array of weights (numbers or Rationals).

m = Money.new(1000, "USD")
m.allocate([0.50, 0.25, 0.25]).map(&:value) #=> [500, 250, 250]

Allocation up to a cutoff

allocate_max_amounts(amounts) attempts to allocate up to the specified maximum for each recipient.

m = Money.new(1000, "USD")
m.allocate_max_amounts([500, 300, 300]).map(&:value) #=> [454.55, 272.73, 272.72]

m = Money.new(1000, "USD")
# Splitting money evenly
m.split(2)              == [Money.new(500, "USD"), Money.new(500, "USD")]
m.split(3).map(&:value) == [333.34, 333.33, 333.33]

# Allocating money proportionally
m.allocate([0.50, 0.25, 0.25]).map(&:value)               == [500, 250, 250]
m.allocate([Rational(2, 3), Rational(1, 3)]).map(&:value) == [666.67, 333.33]

# Allocating up to a cutoff
m.allocate_max_amounts([500, 300, 200]).map(&:value) == [500, 300, 200]
m.allocate_max_amounts([500, 300, 300]).map(&:value) == [454.55, 272.73, 272.72]

Money objects support standard comparison and arithmetic operators. Comparisons are currency-aware; objects with different currencies are not equal even if their values are the same.

Comparisons

Money.new(1000, "USD") == Money.new(1000, "USD")   #=> true
Money.new(1000, "USD") == Money.new(1000, "EUR")   #=> false

Arithmetic

Money.new(1000, "USD") + Money.new(500, "USD") == Money.new(1500, "USD")
Money.new(1000, "USD") - Money.new(200, "USD") == Money.new(800, "USD")
Money.new(1000, "USD") * 5                     == Money.new(5000, "USD")

# Comparisons
Money.new(1000, "USD") == Money.new(1000, "USD")   #=> true
Money.new(1000, "USD") == Money.new(100, "USD")    #=> false
Money.new(1000, "USD") == Money.new(1000, "EUR")   #=> false
Money.new(1000, "USD") != Money.new(1000, "EUR")   #=> true

# Arithmetic
Money.new(1000, "USD") + Money.new(500, "USD") == Money.new(1500, "USD")
Money.new(1000, "USD") - Money.new(200, "USD") == Money.new(800, "USD")
Money.new(1000, "USD") * 5                     == Money.new(5000, "USD")

Currencies are represented by Money::Currency instances. Most Money APIs accept either a String (ISO code) or a Money::Currency object.

Currency Properties

currency = Money.new(1000, "USD").currency
currency.iso_code #=> "USD"
currency.name     #=> "United States Dollar"
currency.symbol   #=> "$"

Setting Default Currency

By default, Money uses Money::NullCurrency. You can change the global default:

Money.configure do |config|
  config.default_currency = Money::Currency.new("USD")
end

In Rails, it is recommended to set the currency per-request using Money.with_currency(currency) { yield } within an around_action.

Money.new(1000, "USD") == Money.new(1000, Money::Currency.new("USD"))
Money.new(1000, "EUR").currency == Money::Currency.new("EUR")

currency = Money.new(1000, "USD").currency
currency.iso_code #=> "USD"
currency.name     #=> "United States Dollar"
currency.to_s     #=> 'USD'
currency.symbol   #=> '$'
currency.disambiguate_symbol #=> 'US$'