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

Archive / Unarchive a Customer

# Archive a customer (preserves their full history)
response = METRIFOX_SDK.customers.archive("customer_123")
puts response["data"]["archived_at"]

# Restore an archived customer
response = METRIFOX_SDK.customers.unarchive("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"
}

List Usage Events

# List events with optional filters and pagination
response = METRIFOX_SDK.usages.list_events(
  customer_key: "customer_123",   # optional
  feature_key: "feature_seats",   # optional
  page: 1,                        # optional
  per_page: 25                    # optional
)

response["data"].each do |event|
  puts "#{event['feature_key']}: #{event['quantity']} at #{event['timestamp']}"
end

puts "Page #{response['meta']['current_page']} of #{response['meta']['total_pages']}"

Compute Quantity Price

Compute the price for a given quantity of a feature for a customer, based on their plan. Useful for previewing upgrade costs or showing customers the cost of additional usage before they commit.

response = METRIFOX_SDK.usages.quantity_price(
  customer_key: "customer_123",
  feature_key: "feature_interview_booking",
  quantity: 500
)

puts "#{response['data']['price']} #{response['data']['unit']}"

# For tiered pricing, inspect the per-tier breakdown
response["data"]["applied_tiers"].each do |tier|
  puts "  Tier #{tier['first_unit']}-#{tier['last_unit']}: #{tier['units_consumed']} units -> #{tier['tier_price']}"
end

Only available to tenants whose plan includes the finance API feature.

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)

Card Collection URL

Generate a hosted URL for collecting a payment method against an existing subscription or order. Useful for trial-to-paid conversions and re-collecting card details after expiry.

# For a subscription
url = METRIFOX_SDK.checkout.card_collection_url(subscription_id: "sub_uuid_123")

# For an order
url = METRIFOX_SDK.checkout.card_collection_url(order_id: "order_uuid_456")

Wallets & Credit Allocations

# List a customer's credit wallets
response = METRIFOX_SDK.wallets.list("customer_123")
response["data"].each do |wallet|
  puts "#{wallet['name']}: #{wallet['balance']} #{wallet['credit_unit_plural']}"
end

# List allocations for a wallet (optionally filter by status)
response = METRIFOX_SDK.wallets.list_credit_allocations("wallet_uuid_123")
response = METRIFOX_SDK.wallets.list_credit_allocations("wallet_uuid_123", status: "active")

# Get a single allocation with its transaction history
response = METRIFOX_SDK.wallets.get_credit_allocation("alloc_uuid_123")
response["data"]["transactions"].each do |txn|
  puts "  #{txn['amount']} at #{txn['created_at']}"
end

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
archive(customer_key) - Archive a customer
unarchive(customer_key) - Restore an archived customer
has_active_subscription?(params) - Check for active subscription
upload_csv(file_path) - Upload customers via CSV
bulk_create(params) - Create multiple customers in one call

Usages:

check_access(params) - Check feature access
record_usage(params) - Record a usage event
list_events(...) - List recorded usage events with optional filters and pagination
quantity_price(customer_key:, feature_key:, quantity:) - Compute the price of a usage quantity (requires finance API feature)

Checkout:

url(params) - Generate a checkout URL
card_collection_url(subscription_id:, order_id:) - Generate a hosted card-collection URL

Wallets:

list(customer_key) - List a customer’s credit wallets
list_credit_allocations(wallet_id, status:) - List credit allocations for a wallet
get_credit_allocation(allocation_id) - Get a single allocation with transaction history

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",
  meter_service_base_url: "https://custom-meter.metrifox.com/"
})

# The meter service URL can also be set via env var
ENV["METRIFOX_METER_SERVICE_BASE_URL"] = "https://custom-meter.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
Discord https://discord.gg/GGMHDDBdw

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

Archive / Unarchive a Customer

CSV Upload

Usage Tracking & Access Control

Check Feature Access

Record Usage Events

Advanced Usage Recording

List Usage Events

Compute Quantity Price

Checkout & Billing

Generate Checkout URL

Card Collection URL

Wallets & Credit Allocations

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

​Archive / Unarchive a Customer

​CSV Upload

​Usage Tracking & Access Control

​Check Feature Access

​Record Usage Events

​Advanced Usage Recording

​List Usage Events

​Compute Quantity Price

​Checkout & Billing

​Generate Checkout URL

​Card Collection URL

​Wallets & Credit Allocations

​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

Archive / Unarchive a Customer

CSV Upload

Usage Tracking & Access Control

Check Feature Access

Record Usage Events

Advanced Usage Recording

List Usage Events

Compute Quantity Price

Checkout & Billing

Generate Checkout URL

Card Collection URL

Wallets & Credit Allocations

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