Rails engine for subscription management.


source "" do
  gem "billy", "~> 1.0"


Create a billy.rb file in the initializers folder.

You'll also need to download a copy of the public key file to the root of the Rails app.

Billy.setup do |config|

  config.app_name                 = ENV["APP_NAME"]
  config.app_email                = ENV["APP_EMAIL"]
  config.discord_path             = ENV["DISCORD_PATH"]

  config.paddle_vendor_id         = ENV["PADDLE_VENDOR_ID"]
  config.paddle_vendor_auth_code  = ENV["PADDLE_VENDOR_AUTH_CODE"]
  config.paddle_public_key_file   = Rails.env.production? ? "paddle.pem" : "paddle_sandbox.pem"
  config.paddle_environment       = Rails.env.production? ? "production" : "sandbox"

  config.lemon_squeezy_site         = ENV["LEMON_SQUEEZY_SITE"]
  config.lemon_squeezy_signing      = ENV["LEMON_SQUEEZY_SIGNING"]
  config.lemon_squeezy_access_token = ENV["LEMON_SQUEEZY_ACCESS_TOKEN"]


Then import the migrations.

bin/rails billy:install:migrations
bin/rails db:migrate



When creating plans, the processor is required and can be free, paddle or lemon_squeezy.

The processor_id is then the ID of the plan on that processor's service.

Billy::Plan.create name: "My Plan", interval: "month", amount: 500, processor: "paddle", processor_id: 123, features: {feature1: true}


To begin, add billy_account to the model of the main Account model in the Rails app. This links the models together.

There are a few types of account that can be created.

  • Free
  • Trial
  • Migrated - For old subscriptions migrated from other systems
  • Paddle - Using Paddle for subscriptions
  • Lemon Squeezy - Using Lemon Squeezy for subscriptions

Free Account

To create a Free account:

# Set the model the Billy Account will be created for
 = MyAccountModel.first

# Create a Billy free Account
. :free

Trial Account

To create a Trial account:

# Set the model the Billy Account will be created for
 = MyAccountModel.first

# Create a Billy trial Account and set the first plan as a 14 day trial
. :trial
  plan: Billy::Plan.first,
  trial_ends_at: 14.days.from_now,
  ends_at: 14.days.from_now


For Paddle and Lemon Squeezy, accounts and subscriptions are created/updated using their webhooks.

  • The webhook URL for Paddle is /_billy/webhooks/paddle
  • The webhook URL for Lemon Squeezy is /_billy/webhooks/lemon_squeezy


To grab all of an accounts' charges (such as migrated and paddle):

 = MyAccountModel.first

Billy::Charge.where(account: .billy_accounts).where.not(amount: 0).order(created_at: :desc)

Discord Notifications

This library can send Discord notifs for sending events. For example, new user.

Subscription creation, payment creation and cancellation types are sent automatically.

# Colour is the decimal value of a colour
# Use this site and grab DECIMAL value
Billy::DiscordJob.perform_now title: "👋  New Channel", description: "test", colour: 0, url: "