killbill-client-ruby

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
4.x.y	0.24.z

Installation

Get the killbill-client gem:

gem install killbill-client

Alternatively, add the dependency in your Gemfile:

gem 'killbill-client'

Authentication

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.

Examples

Here is a snippet creating your first account and subscription:

require 'killbill_client'

KillBillClient.url = 'http://127.0.0.1:8080'

# 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 = KillBillClient::Model::Account.new
account.name = '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 = KillBillClient::Model::Subscription.new
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
end

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

require 'killbill_client'

KillBillClient.url = 'http://127.0.0.1:8080'

AUDIT_USER = 'pierre (via ruby script)'

File.open(File.dirname(__FILE__) + '/accounts.txt').readlines.map(&:chomp).each do |kb_account_id|
  account = KillBillClient::Model::Account.find_by_id kb_account_id
  puts "Current tags for #{account.name} (#{account.account_id}): #{account.tags.map(&:tag_definition_name).join(', ')}"

  account.add_tag 'OVERDUE_ENFORCEMENT_OFF', AUDIT_USER
  account.add_tag 'AUTO_PAY_OFF', AUDIT_USER

  puts "New tags for #{account.name} (#{account.account_id}): #{account.tags.map(&:tag_definition_name).join(', ')}"
end

We have lots of examples in our integration tests.

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 = 'http://127.0.0.1:8080' and the username and password to authenticate the API, e.g. KillBillClient.username = 'admin' and KillBillClient.password = 'password'

License

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