Creem Ruby SDK

Ruby SDK for the Creem payment platform API — a Merchant of Record for SaaS and digital businesses.

Installation

Add to your Gemfile:

gem "creem"

Or install directly:

gem install creem

Quick Start

require "creem"

# Global configuration
Creem.configure do |config|
  config.api_key = "creem_YOUR_API_KEY"
  config.test_mode = true  # Use sandbox environment
end

client = Creem::Client.new

# Or pass options directly
client = Creem::Client.new(api_key: "creem_YOUR_API_KEY", test_mode: true)

Usage

Products

# List products
products = client.products.list(page_number: 1, page_size: 10)

# Get a product
product = client.products.retrieve("prod_123")

Checkouts

# Create a checkout session
checkout = client.checkouts.create(
  product_id: "prod_123",
  success_url: "https://yoursite.com/success"
)

puts checkout["checkout_url"]  # Redirect customer here

Subscriptions

# List subscriptions
subs = client.subscriptions.list

# Get a subscription
sub = client.subscriptions.retrieve("sub_123")

# Update a subscription
client.subscriptions.update("sub_123",
  items: [{ product_id: "prod_456", units: 3 }],
  update_behavior: "proration-charge"
)

# Cancel a subscription
client.subscriptions.cancel("sub_123", mode: "immediate")

Customers

# List customers
customers = client.customers.list

# Get by ID or email
customer = client.customers.retrieve(customer_id: "cust_123")
customer = client.customers.retrieve(email: "user@example.com")

# Generate billing portal link
portal = client.customers.billing_portal("cust_123")
puts portal["customer_portal_link"]

Licenses

# Activate a license
license = client.licenses.activate(key: "ABC-123", instance_name: "My Device")

# Validate a license
license = client.licenses.validate(key: "ABC-123", instance_id: "inst_456")

# Deactivate a license
client.licenses.deactivate(key: "ABC-123", instance_id: "inst_456")

Transactions

transactions = client.transactions.list(page_number: 1, page_size: 10)

Discounts

discounts = client.discounts.list(page_number: 1, page_size: 10)

Webhook Verification

# Verify webhook signature
payload = request.body.read
signature = request.headers["creem-signature"]
secret = "whsec_your_webhook_secret"

# Returns parsed event or raises Creem::WebhookSignatureError
event = Creem::Webhook.construct_event(
  payload: payload,
  secret: secret,
  signature: signature
)

case event["event"]
when "checkout.completed"
  # Handle checkout completion
when "subscription.active"
  # Handle new subscription
end

Error Handling

begin
  client.products.retrieve("prod_invalid")
rescue Creem::AuthenticationError => e
  puts "Invalid API key: #{e.message}"
rescue Creem::NotFoundError => e
  puts "Resource not found: #{e.message}"
rescue Creem::BadRequestError => e
  puts "Bad request: #{e.message}"
rescue Creem::RateLimitError => e
  puts "Rate limited: #{e.message}"
rescue Creem::ServerError => e
  puts "Server error: #{e.message}"
rescue Creem::ApiError => e
  puts "API error (#{e.status}): #{e.message}"
end

Test Mode

Toggle between production and sandbox environments:

# Via configuration
Creem.configure do |config|
  config.test_mode = ENV["RAILS_ENV"] != "production"
end

# Or per-client
client = Creem::Client.new(api_key: "key", test_mode: true)

	Production	Test Mode
Base URL	https://api.creem.io/v1	https://test-api.creem.io/v1
Payments	Real charges	Simulated

Development

make install    # Install dependencies
make test       # Run tests
make lint       # Run linters
make format     # Auto-fix formatting
make console    # Interactive console

License

MIT License. See LICENSE for details.