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
)

# Access top-level resources
accounts = client.accounts.list
account = client.accounts.get('account_id')

# Access nested biller resources
events = client.biller.events.list
meters = client.biller.meters.list
plans = client.biller.plans.list
subscriptions = client.biller.subscriptions.list

# Access nested seller resources
products = client.seller.products.list
orders = client.seller.orders.list

# Create resources
new_account = client.accounts.create(
  name: 'Acme Corp',
  email: 'billing@acme.com'
)

# Update resources
updated_account = client.accounts.update(
  'account_id',
  name: 'Acme Corporation'
)

# Delete resources
client.accounts.delete('account_id')

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}"
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.