Skip to content

killbill/killbill-client-ruby

master
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?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
bin
 
 
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 

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

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.