JavaScript / Node.js

Installation

npm install metrifox-js

Quick Start

The Metrifox SDK supports a modern client-based architecture for better organization and type safety.

Configuration

Node.js:

import { init } from "metrifox-js";

const metrifoxClient = init({
  apiKey: process.env.METRIFOX_API_KEY,
});

Vite/React:

import { init } from "metrifox-js";

const metrifoxClient = init({
  apiKey: import.meta.env.VITE_METRIFOX_API_KEY,
});
window.metrifoxClient = metrifoxClient;

Alternative - Direct Initialization:

import { MetrifoxSDK } from "metrifox-js";

const sdk = new MetrifoxSDK({
  apiKey: "your_api_key_here",
});

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

Customer Management

Create a Customer

// Individual customer
const customer = await client.customers.create({
  customer_key: "user_12345",  // Required: unique identifier
  customer_type: "INDIVIDUAL",  // Required: "INDIVIDUAL" or "BUSINESS"
  primary_email: "john.doe@example.com",  // Required
  first_name: "John",
  last_name: "Doe",
  primary_phone: "+1234567890",
  currency: "USD"
});

// Business customer
const customer = await client.customers.create({
  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"
});

Update a Customer

const response = await client.customers.update("user_12345", {
  primary_email: "newemail@example.com",
  first_name: "Jane",
  currency: "EUR"
});

The customer_key cannot be changed after creation.

Get Customer Data

// Get basic customer data
const customer = await client.customers.get("customer_123");

// Get detailed customer information
const customerDetails = await client.customers.getDetails("customer_123");

// List customers with pagination
const customerList = await client.customers.list({
  page: 1,
  per_page: 50,
  search_term: "john@example.com",  // Optional
  customer_type: "INDIVIDUAL",  // Optional
  date_created: "2025-09-01"  // Optional
});

// Check active subscription
const isActive = await client.customers.checkActiveSubscription("customer_123");

Delete a Customer

const response = await client.customers.delete("customer_123");

Archive / Unarchive a Customer

// Archive a customer (preserves their full history)
const response = await client.customers.archive("customer_123");
console.log(response.data.archived_at);

// Restore an archived customer
await client.customers.unarchive("customer_123");

Bulk CSV Upload

// File input from your form
const csvFile = document.getElementById("csv-input").files[0];

const response = await client.customers.uploadCsv(csvFile);
console.log(`Processed ${response.data.total_customers} customers`);
console.log(`Successful: ${response.data.successful_upload_count}`);

Usage Tracking & Access Control

Check Feature Access

const access = await client.usages.checkAccess({
  featureKey: "premium_feature",
  customerKey: "customer_123",
});

if (access.can_access) {
  console.log(`Access granted. Balance: ${access.balance}`);
} else {
  console.log(`Quota exceeded. Used: ${access.used_quantity}/${access.quota}`);
}

Record Usage Events

// Simple usage (amount = 1)
await client.usages.recordUsage({
  customerKey: "customer_123",
  eventName: "api_call",
});

// Custom amount for bulk operations
await client.usages.recordUsage({
  customerKey: "customer_123",
  eventName: "bulk_upload",
  amount: 50,
});

// Advanced usage with metadata
await client.usages.recordUsage({
  customerKey: "customer_123",
  eventName: "premium_feature_used",
  amount: 1,
  credit_used: 25,  // Optional: credits consumed
  event_id: "evt_abc123",  // Optional: unique identifier
  timestamp: Date.now(),  // Optional: custom timestamp
  metadata: {  // Optional: additional context
    feature_type: "advanced_analytics",
    session_id: "sess_xyz789"
  }
});

List Usage Events

Retrieve usage events with optional filters and pagination:

const events = await client.usages.listEvents({
  customerKey: "customer_123",
  featureKey: "premium_feature",
  page: 1,
  perPage: 25,
});

events.data.forEach((event) => {
  console.log(`${event.feature_key}: qty=${event.quantity} at ${event.timestamp}`);
});

console.log(`Page ${events.meta.current_page} of ${events.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.

const price = await client.usages.quantityPrice({
  customerKey: "customer_123",
  featureKey: "feature_interview_booking",
  quantity: 500,
});

console.log(`${price.data.price} ${price.data.unit}`);

// For tiered pricing, inspect the per-tier breakdown
price.data.applied_tiers.forEach((tier) => {
  console.log(
    `  Tier ${tier.first_unit}-${tier.last_unit}: ` +
    `${tier.units_consumed} units -> ${tier.tier_price}`
  );
});

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

Complete Usage Example

async function useFeature(metrifoxClient, customerKey, featureKey, eventName) {
  try {
    // 1. Check if customer has access
    const access = await metrifoxClient.usages.checkAccess({
      featureKey,
      customerKey,
    });

    if (access.can_access) {
      // 2. Perform the actual feature logic
      const result = performFeatureLogic();

      // 3. Record usage after successful completion
      await metrifoxClient.usages.recordUsage({
        customerKey,
        eventName,
        amount: result.unitsUsed || 1,
        event_id: result.transactionId,
        metadata: {
          execution_time_ms: result.duration
        }
      });

      return { success: true, data: result };
    } else {
      return {
        success: false,
        error: "Quota exceeded",
        balance: access.balance,
      };
    }
  } catch (error) {
    return { success: false, error: error.message };
  }
}

Checkout & Billing

Embed Checkout Pages

// Embed checkout pages within your application
await client.checkout.embed({
  productKey: "your_product_key",
  container: "#checkout-container",  // CSS selector or DOM element
});

Generate Checkout URL

// Basic checkout URL
const url = await client.checkout.url({
  offeringKey: "premium_plan"
});

// With billing interval
const url = await client.checkout.url({
  offeringKey: "premium_plan",
  billingInterval: "monthly"
});

// With customer key for pre-filled checkout
const url = await client.checkout.url({
  offeringKey: "premium_plan",
  billingInterval: "monthly",
  customerKey: "customer_123"
});

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
const url = await client.checkout.cardCollectionUrl({
  subscriptionId: "sub_uuid_123",
});

// For an order
const url = await client.checkout.cardCollectionUrl({
  orderId: "order_uuid_456",
});

Wallets & Credit Allocations

// List a customer's credit wallets
const wallets = await client.wallets.list("customer_123");
wallets.data.forEach((w) =>
  console.log(`${w.name}: ${w.balance} ${w.credit_unit_plural}`)
);

// List allocations for a wallet (optionally filter by status)
const allocations = await client.wallets.listCreditAllocations("wallet_uuid_123");
const active = await client.wallets.listCreditAllocations("wallet_uuid_123", {
  status: "active",
});

// Get a single allocation with its transaction history
const allocation = await client.wallets.getCreditAllocation("alloc_uuid_123");
allocation.data.transactions.forEach((t) =>
  console.log(`  ${t.amount} at ${t.created_at}`)
);

Framework Integration

React/Vite

Setup in main.jsx:

import { init } from "metrifox-js";

const metrifoxClient = init({
  apiKey: import.meta.env.VITE_METRIFOX_API_KEY,
});
window.metrifoxClient = metrifoxClient;

Use in components:

function FeatureButton({ customerKey }) {
  const handleClick = async () => {
    const client = window.metrifoxClient;
    const access = await client.usages.checkAccess({
      featureKey: "premium_feature",
      customerKey,
    });

    if (access.can_access) {
      await client.usages.recordUsage({
        customerKey,
        eventName: "button_clicked",
      });
    }
  };

  return <button onClick={handleClick}>Use Feature</button>;
}

Next.js

Setup in _app.js:

import { init } from "metrifox-js";

const metrifoxClient = init({
  apiKey: process.env.METRIFOX_API_KEY,
});

export { metrifoxClient };

Express

import { init } from "metrifox-js";
import express from "express";

const app = express();
const metrifoxClient = init({
  apiKey: process.env.METRIFOX_API_KEY,
});

app.get("/api/premium/:customerId", async (req, res) => {
  const access = await metrifoxClient.usages.checkAccess({
    featureKey: "premium_api",
    customerKey: req.params.customerId,
  });

  if (!access.can_access) {
    return res.status(403).json({ error: "Access denied" });
  }

  await metrifoxClient.usages.recordUsage({
    customerKey: req.params.customerId,
    eventName: "premium_api_call",
  });

  res.json({ data: "premium content" });
});

API Reference

Client Architecture

const client = init(config);

// Available modules:
client.usages;        // Usage tracking and access control
client.customers;     // Customer management
client.checkout;      // Embedded checkout
client.subscriptions; // Subscription management
client.wallets;       // Credit wallets and allocations

Functions

Initialization:

init(config?) - Initialize and return the SDK client. config accepts apiKey, baseUrl, webAppBaseUrl, and meterServiceBaseUrl.

Usage Module (client.usages):

checkAccess(request) - Check feature access for a customer
recordUsage(request) - Record a usage event
listEvents(params?) - List recorded usage events with optional filters and pagination
quantityPrice(request) - Compute the price of a usage quantity (requires finance API feature)

Customers Module (client.customers):

create(request) - Add a customer
update(customerKey, request) - Update a customer
list(params?) - Get a paginated list of customers
get(customerKey) - Get a customer
delete(customerKey) - Delete a customer
archive(customerKey) - Archive a customer
unarchive(customerKey) - Restore an archived customer
getDetails(customerKey) - Get detailed customer information
uploadCsv(file) - Upload a CSV list of customers
bulkCreate(request) - Create multiple customers in one call
checkActiveSubscription(customerKey) - Check for active subscription

Checkout Module (client.checkout):

embed(config) - Embed checkout pages in your application
url(config) - Generate a checkout URL
cardCollectionUrl(config) - Generate a hosted card-collection URL

Wallets Module (client.wallets):

list(customerKey) - List a customer’s credit wallets
listCreditAllocations(walletId, options?) - List credit allocations for a wallet (optionally filtered by status)
getCreditAllocation(allocationId) - Get a single allocation with transaction history

TypeScript Support

All TypeScript types are available for import:

import {
  AccessCheckRequest,
  UsageEventRequest,
  AccessResponse,
  CustomerCreateRequest,
  CustomerUpdateRequest,
  CustomerListRequest,
  APIResponse,
} from "metrifox-js";

Error Handling

try {
  const access = await client.usages.checkAccess({ featureKey, customerKey });
} catch (error) {
  // Handle network errors, invalid API key, etc.
  console.error("Metrifox API error:", error.message);
}

Configuration

Environment Variables

Node.js:

METRIFOX_API_KEY=your_api_key_here

Vite:

VITE_METRIFOX_API_KEY=your_api_key_here

Create React App:

REACT_APP_METRIFOX_API_KEY=your_api_key_here

Custom URLs

const client = init({
  apiKey: "your_api_key",
  baseUrl: "https://custom-api.metrifox.com/api/v1/",
  webAppBaseUrl: "https://custom-app.metrifox.com",
  meterServiceBaseUrl: "https://custom-meter.metrifox.com/",
});

The meter service URL can also be overridden via the METRIFOX_METER_SERVICE_BASE_URL environment variable.

Default URLs

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

Support

Email: support@metrifox.com
Documentation: https://docs.metrifox.com
GitHub: https://github.com/metrifox/metrifox-js
Discord https://discord.gg/GGMHDDBdw

The JavaScript SDK works seamlessly across all modern JavaScript environments including Node.js, React, Next.js, Vue, and more.

Overview

SDKs

JavaScript / Node.js

Installation

Quick Start

Configuration

Customer Management

Create a Customer

Update a Customer

Get Customer Data

Delete a Customer

Archive / Unarchive a Customer

Bulk CSV Upload

Usage Tracking & Access Control

Check Feature Access

Record Usage Events

List Usage Events

Compute Quantity Price

Complete Usage Example

Checkout & Billing

Embed Checkout Pages

Generate Checkout URL

Card Collection URL

Wallets & Credit Allocations

Framework Integration

React/Vite

Next.js

Express

API Reference

Client Architecture

Functions

TypeScript Support

Error Handling

Configuration

Environment Variables

Custom URLs

Default URLs

Support

​Installation

​Quick Start

​Configuration

​Customer Management

​Create a Customer

​Update a Customer

​Get Customer Data

​Delete a Customer

​Archive / Unarchive a Customer

​Bulk CSV Upload

​Usage Tracking & Access Control

​Check Feature Access

​Record Usage Events

​List Usage Events

​Compute Quantity Price

​Complete Usage Example

​Checkout & Billing

​Embed Checkout Pages

​Generate Checkout URL

​Card Collection URL

​Wallets & Credit Allocations

​Framework Integration

​React/Vite

​Next.js

​Express

​API Reference

​Client Architecture

​Functions

​TypeScript Support

​Error Handling

​Configuration

​Environment Variables

​Custom URLs

​Default URLs

​Support

Installation

Quick Start

Configuration

Customer Management

Create a Customer

Update a Customer

Get Customer Data

Delete a Customer

Archive / Unarchive a Customer

Bulk CSV Upload

Usage Tracking & Access Control

Check Feature Access

Record Usage Events

List Usage Events

Compute Quantity Price

Complete Usage Example

Checkout & Billing

Embed Checkout Pages

Generate Checkout URL

Card Collection URL

Wallets & Credit Allocations

Framework Integration

React/Vite

Next.js

Express

API Reference

Client Architecture

Functions

TypeScript Support

Error Handling

Configuration

Environment Variables

Custom URLs

Default URLs

Support