Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Kill Bill Ruby client library.

Kill Bill compatibility

Client version Kill Bill version
0.x.y 0.16.z
1.x.y 0.18.z
2.x.y 0.20.z
3.x.y 0.22.z


Get the killbill-client gem:

gem install killbill-client

Alternatively, add the dependency in your Gemfile:

gem 'killbill-client'


A username and password can be set directly in the options hash (accepted by each API method):

options = {
  :username => 'admin',
  :password => 'password'

These credentials are validated by Kill Bill either directly (users managed by Kill Bill) or via a third-party (LDAP, Okta, Auth0, etc.).

Alternatively, a bearer token can be passed as such:

options = {
  :bearer => 'token'

The security token would be validated by Kill bill via a third-party (e.g. Auth0).

By default, Kill Bill won't maintain sessions, except when calling the API /1.0/kb/security/permissions (JSESSIONID, present in the Set-Cookie response header). This session id can be passed instead:

options = {
  :session_id => 'JSESSIONID'

Using this session mechanism is recommend for user interfaces or to minimize the runtime dependency with a third-party provider.

Note: if a timed out session is re-used (last_access_time older than 60 minutes by default), a HTTP/1.1 401 Unauthorized is returned with Set-Cookie: JSESSIONID=deleteMe, and the session is deleted from the database (and cache) on the server side.


Here is a snippet creating your first account and subscription:

require 'killbill_client'

KillBillClient.url = ''

# Multi-tenancy and RBAC credentials
options = {
  :username => 'admin',
  :password => 'password',
  :api_key => 'bob',
  :api_secret => 'lazar'

# Audit log data
user = 'me'
reason = 'Going through my first tutorial'
comment = 'I like it!'

# Create an account
account = = 'John Doe'
account.first_name_length = 4
account.external_key = 'john-doe'
account.currency = 'USD'
account = account.create(user, reason, comment, options)

# Add a subscription
subscription =
subscription.account_id = account.account_id
subscription.product_name = 'Sports'
subscription.product_category = 'BASE'
subscription.billing_period = 'MONTHLY'
subscription.price_list = 'DEFAULT'
subscription = subscription.create(user, reason, comment, nil, true, options)

# List invoices
account.invoices(true, options).each do |invoice|
  puts invoice.inspect

The following script will tag a list of accounts with OVERDUE_ENFORCEMENT_OFF and AUTO_PAY_OFF:

require 'killbill_client'

KillBillClient.url = ''

AUDIT_USER = 'pierre (via ruby script)' + '/accounts.txt') do |kb_account_id|
  account = KillBillClient::Model::Account.find_by_id kb_account_id
  puts "Current tags for #{} (#{account.account_id}): #{', ')}"

  account.add_tag 'AUTO_PAY_OFF', AUDIT_USER

  puts "New tags for #{} (#{account.account_id}): #{', ')}"

We have lots of examples in our integration tests.


To run the integration tests:

rake test:remote:spec

You need to set in spec/spec_helper.rb the url of your instance, e.g. KillBillClient.url = '' and the username and password to authenticate the API, e.g. KillBillClient.username = 'admin' and KillBillClient.password = 'password'


The Kill Bill Ruby client is released under the Apache license.