Ruby

Installation

Add this line to your application’s Gemfile:

gem 'metrifox-sdk'

And then execute:

bundle install

Or install it yourself as:

gem install metrifox-sdk

Quick Start

Configuration

require 'metrifox-sdk'

# Initialize with configuration
METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key"})

# Or set environment variable
ENV["METRIFOX_API_KEY"] = "your-api-key"
METRIFOX_SDK = MetrifoxSDK.init

Get your API key from Settings → API Keys in your Metrifox dashboard.

Customer Management

Create a Customer

# Individual customer
customer_data = {
  customer_key: "customer_123",  # Required - unique identifier
  customer_type: "INDIVIDUAL",   # Required - "INDIVIDUAL" or "BUSINESS"
  primary_email: "customer@example.com",  # Required
  first_name: "John",
  last_name: "Doe",
  primary_phone: "+1234567890",
  currency: "USD"
}

response = METRIFOX_SDK.customers.create(customer_data)

# Business customer
business_data = {
  customer_key: "company_abc123",
  customer_type: "BUSINESS",
  primary_email: "contact@acmecorp.com",
  legal_name: "ACME Corporation LLC",
  display_name: "ACME Corp",
  website_url: "https://acmecorp.com"
}

response = METRIFOX_SDK.customers.create(business_data)

Update a Customer

# Update customer (customer_key cannot be changed)
update_data = {
  display_name: "ACME Corporation",
  website_url: "https://acme.com"
}

response = METRIFOX_SDK.customers.update("customer_123", update_data)

The customer_key is immutable and cannot be changed after creation.

Get Customer Data

# Get customer
response = METRIFOX_SDK.customers.get_customer({ customer_key: "customer_123" })

# Get customer details
response = METRIFOX_SDK.customers.get_details({ customer_key: "customer_123" })

# Check for an active subscription
has_active_subscription = METRIFOX_SDK.customers.has_active_subscription?(customer_key: "customer_123")

# List customers
response = METRIFOX_SDK.customers.list

# List with pagination
response = METRIFOX_SDK.customers.list({ page: 2, per_page: 10 })

# List with filters
response = METRIFOX_SDK.customers.list({
  search_term: "TechStart",
  customer_type: "BUSINESS",
  date_created: "2025-09-01"
})

Delete a Customer

response = METRIFOX_SDK.customers.delete_customer({ customer_key: "customer_123" })

CSV Upload

# Upload customers via CSV
response = METRIFOX_SDK.customers.upload_csv("/path/to/customers.csv")

puts response["data"]["total_customers"]
puts response["data"]["successful_upload_count"]

Usage Tracking & Access Control

Check Feature Access

response = METRIFOX_SDK.usages.check_access({
  feature_key: "premium_feature",
  customer_key: "customer_123"
})

puts response["data"]["can_access"]  # true/false
puts response["data"]["balance"]

Access checks are served by the Metrifox Meter service (https://api-meter.metrifox.com).

Example response:

{
  "data": {
    "customer_key": "cust-mit7k5v8obzs",
    "feature_key": "feature_seats",
    "requested_quantity": 1,
    "can_access": true,
    "unlimited": false,
    "balance": 4,
    "used_quantity": 0,
    "entitlement_active": true,
    "prepaid": false,
    "wallet_balance": 0,
    "message": "Feature found"
  }
}

Record Usage Events

# Basic usage recording
response = METRIFOX_SDK.usages.record_usage({
  customer_key: "customer_123",
  event_name: "api_call",
  amount: 1,
  event_id: "evt_12345",  # Required idempotency key
  timestamp: (Time.now.to_f * 1000).to_i  # Recommended (milliseconds)
})

puts response["message"]  # "Event received"
puts response["data"]["quantity"]  # 1

You can send either an event_name or a feature_key when recording usage events.

Advanced Usage Recording

# With additional fields
response = METRIFOX_SDK.usages.record_usage({
  customer_key: "customer_123",
  event_name: "api_call",  # Or use feature_key
  amount: 1,
  event_id: "event_uuid_123",  # Required idempotency key
  credit_used: 5,
  timestamp: (Time.now.to_f * 1000).to_i,
  metadata: {
    source: "web_app",
    feature: "premium_search"
  }
})

# Using structured request object
usage_request = MetrifoxSDK::Types::UsageEventRequest.new(
  customer_key: "customer_123",
  feature_key: "feat_my_feat_234",  # OR use event_name
  amount: 1,
  credit_used: 5,
  event_id: "event_uuid_123",
  timestamp: (Time.now.to_f * 1000).to_i,
  metadata: { source: "mobile_app" }
)

response = METRIFOX_SDK.usages.record_usage(usage_request)

Sample response:

{
  "data": {
    "customer_key": "cust-mit7k5v8obzs",
    "quantity": 1,
    "feature_key": "feature_job_posts"
  },
  "message": "Event received"
}

Checkout & Billing

Generate Checkout URL

# Basic checkout URL generation
checkout_url = METRIFOX_SDK.checkout.url({
  offering_key: "your_offering_key"
})

# With optional billing interval
checkout_url = METRIFOX_SDK.checkout.url({
  offering_key: "your_offering_key",
  billing_interval: "monthly"
})

# With customer key for pre-filled checkout
checkout_url = METRIFOX_SDK.checkout.url({
  offering_key: "your_offering_key",
  billing_interval: "monthly",
  customer_key: "customer_123"
})

# Using structured config object
checkout_config = MetrifoxSDK::Types::CheckoutConfig.new(
  offering_key: "your_offering_key",
  billing_interval: "monthly",
  customer_key: "customer_123"
)

checkout_url = METRIFOX_SDK.checkout.url(checkout_config)

Type Safety with Structs

The SDK exposes lightweight structs for usage and checkout helpers:

# Usage events (event_id required for idempotency)
usage_request = MetrifoxSDK::Types::UsageEventRequest.new(
  customer_key: "customer_123",
  feature_key: "feature_seats",
  amount: 1,
  event_id: "event_uuid_123",
  timestamp: (Time.now.to_f * 1000).to_i,
  metadata: { source: "mobile_app" }
)

response = METRIFOX_SDK.usages.record_usage(usage_request)

# Checkout configuration
checkout_config = MetrifoxSDK::Types::CheckoutConfig.new(
  offering_key: "premium_plan",
  billing_interval: "monthly",
  customer_key: "customer_123"
)

checkout_url = METRIFOX_SDK.checkout.url(checkout_config)

Error Handling

begin
  response = METRIFOX_SDK.usages.check_access({
    feature_key: "premium_feature",
    customer_key: "customer_123"
  })
rescue MetrifoxSDK::APIError => e
  puts "API Error: #{e.message}"
rescue MetrifoxSDK::ConfigurationError => e
  puts "Configuration Error: #{e.message}"
end

Framework Integration

Rails

# config/initializers/metrifox.rb
METRIFOX_SDK = MetrifoxSDK.init({
  api_key: ENV['METRIFOX_API_KEY']
})

# app/controllers/premium_features_controller.rb
class PremiumFeaturesController < ApplicationController
  def use_feature
    access = METRIFOX_SDK.usages.check_access({
      feature_key: "premium_feature",
      customer_key: current_user.customer_key
    })

    unless access["data"]["can_access"]
      return render json: { error: "Access denied" }, status: :forbidden
    end

    # Process feature...

    METRIFOX_SDK.usages.record_usage({
      customer_key: current_user.customer_key,
      event_name: "premium_feature_used",
      event_id: SecureRandom.uuid
    })

    render json: { success: true }
  end
end

Sinatra

require 'sinatra'
require 'metrifox-sdk'

METRIFOX_SDK = MetrifoxSDK.init({ api_key: ENV['METRIFOX_API_KEY'] })

get '/api/premium/:customer_id' do
  access = METRIFOX_SDK.usages.check_access({
    feature_key: "premium_api",
    customer_key: params[:customer_id]
  })

  halt 403, { error: "Access denied" }.to_json unless access["data"]["can_access"]

  # Process request...

  METRIFOX_SDK.usages.record_usage({
    customer_key: params[:customer_id],
    event_name: "premium_api_call",
    event_id: request.env['HTTP_X_REQUEST_ID']
  })

  { data: "premium content" }.to_json
end

API Reference

Available Methods

Customers:

create(data) - Create a customer
update(customer_key, data) - Update a customer
get_customer(params) - Get a customer
get_details(params) - Get detailed customer information
list(params) - List customers with pagination and filters
delete_customer(params) - Delete a customer
has_active_subscription?(params) - Check for active subscription
upload_csv(file_path) - Upload customers via CSV

Usages:

check_access(params) - Check feature access
record_usage(params) - Record a usage event

Checkout:

url(params) - Generate a checkout URL

Type Structs

MetrifoxSDK::Types::UsageEventRequest
MetrifoxSDK::Types::CheckoutConfig

Configuration

Environment Variables

export METRIFOX_API_KEY=your_api_key_here

Custom URLs

METRIFOX_SDK = MetrifoxSDK.init({
  api_key: "your_api_key",
  base_url: "https://custom-api.metrifox.com/api/v1/",
  web_app_base_url: "https://custom-app.metrifox.com"
})

Default URLs

Production API: https://api.metrifox.com/api/v1/
Meter Service: https://api-meter.metrifox.com/
Web App: https://app.metrifox.com

Requirements

Ruby 2.7+

Support

Email: support@metrifox.com
Documentation: https://docs.metrifox.com
GitHub: https://github.com/metrifox/metrifox-ruby

The Ruby SDK follows Ruby conventions and integrates seamlessly with Rails, Sinatra, and other Ruby frameworks.

Overview

SDKs

Installation

Quick Start

Configuration

Customer Management

Create a Customer

Update a Customer

Get Customer Data

Delete a Customer

CSV Upload

Usage Tracking & Access Control

Check Feature Access

Record Usage Events

Advanced Usage Recording

Checkout & Billing

Generate Checkout URL

Type Safety with Structs

Error Handling

Framework Integration

Rails

Sinatra

API Reference

Available Methods

Type Structs

Configuration

Environment Variables

Custom URLs

Default URLs

Requirements

Support

Overview

SDKs

​Installation

​Quick Start

​Configuration

​Customer Management

​Create a Customer

​Update a Customer

​Get Customer Data

​Delete a Customer

​CSV Upload

​Usage Tracking & Access Control

​Check Feature Access

​Record Usage Events

​Advanced Usage Recording

​Checkout & Billing

​Generate Checkout URL

​Type Safety with Structs

​Error Handling

​Framework Integration

​Rails

​Sinatra

​API Reference

​Available Methods

​Type Structs

​Configuration

​Environment Variables

​Custom URLs

​Default URLs

​Requirements

​Support

Installation

Quick Start

Configuration

Customer Management

Create a Customer

Update a Customer

Get Customer Data

Delete a Customer

CSV Upload

Usage Tracking & Access Control

Check Feature Access

Record Usage Events

Advanced Usage Recording

Checkout & Billing

Generate Checkout URL

Type Safety with Structs

Error Handling

Framework Integration

Rails

Sinatra

API Reference

Available Methods

Type Structs

Configuration

Environment Variables

Custom URLs

Default URLs

Requirements

Support