Billingrails Ruby SDK

Official Ruby SDK for the Billingrails API - Flexible, composable, and intuitive API-first commerce platform.

Installation

Add this line to your application's Gemfile:

gem 'billingrails'

And then execute:

bundle install

Or install it yourself as:

gem install billingrails

Usage

require 'billingrails'

# Initialize the client
client = Billingrails::Client.new(
  api_key: 'your_api_key_here',
  base_url: 'https://api.billingrails.com/v1' # optional
)

list_response = client.accounts.list
puts list_response['accounts']

# Create account
create_response = client.accounts.create(
  name: 'Acme Corp',
  email: 'billing@acme.com'
)
puts create_response['account']

# Get account
retrieve_response = client.accounts.get('account_id')
puts retrieve_response['account']

# Update account
update_response = client.accounts.update(
  'account_id',
  name: 'Acme Corporation'
)
puts update_response['account']

# Get account balances
balances_response = client.accounts.get_balances('account_id')
puts balances_response['balances']

# Debit an account
debit_response = client.accounts.debit('account_id', amount: 1000, currency: 'USD')
puts debit_response['balances']

Error Handling

The SDK provides specific error classes for different types of errors:

begin
  client.accounts.get('invalid_id')
rescue Billingrails::NotFoundError => e
  puts "Resource not found: #{e.message}"
rescue Billingrails::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Billingrails::RateLimitError => e
  puts "Rate limit exceeded: #{e.message}"
rescue Billingrails::ApiError => e
  puts "API error: #{e.message}"
  puts "Status: #{e.status}"
  puts "Code: #{e.code}"
  puts "Details: #{e.details}"
rescue Billingrails::ConnectionError => e
  puts "Connection error: #{e.message}"
end

Configuration

You can configure the client with the following options:

client = Billingrails::Client.new(
  api_key: 'your_api_key',
  base_url: 'https://api.billingrails.com/v1', # Custom base URL
  timeout: 60 # Request timeout in seconds (default: 30)
)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/billingrails/billingrails-ruby.

License

The gem is available as open source under the terms of the MIT License.

Support

For support, please contact ugo@billingrails.com or visit our documentation.