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

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

Overview

SDKs

Documentation Index

​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