Navigation
On this page

Core Concepts

This page explains the core concepts behind UsageFlow.

Understanding these concepts will help you configure billing correctly and integrate UsageFlow into your application.

Organization

An organization represents a company or team using UsageFlow.

Organizations allow multiple users to collaborate while maintaining isolated billing environments.

Each organization can:

  • Define its own metrics
  • Create pricing plans
  • Track usage
  • Manage subscriptions
  • Invite team members

Example:

Organization: CloudAI

All billing data in UsageFlow is scoped to an organization.

Members & Roles

Organizations support role-based access control (RBAC) to manage team permissions.

Available roles:

OWNER
ADMIN
DEVELOPER
VIEWER

Role permissions:

RolePermissions
OWNERFull control including billing and member management
ADMINManage billing, metrics, plans, and invites
DEVELOPERManage API keys and integrations
VIEWERRead-only access

Admins and owners can invite users via email.

Metrics

Metrics define what kind of usage your product tracks.

Examples include:

API_CALL
ACTIVE_USER
STORAGE_GB
AI_TOKEN
EMAIL_SENT

Example metric definition:

  • Name: API Calls
  • Key: API_CALL
  • Unit: calls

Metrics are reusable and can be attached to multiple pricing plans.

Plans

Plans define the pricing structure for your product.

A plan includes:

  • A base price
  • Pricing rules for usage metrics

Example:

  • Plan Name: Pro
  • Base Price: $100/month

Plans can contain multiple metrics with different pricing rules.

Plan Metrics

Plan Metrics define how a metric is priced within a plan.

Example:

  • Metric: API_CALL
  • Included Units: 10,000
  • Overage Price: $0.01 per call

This means:

  • The first 10,000 API calls are included
  • Additional usage costs $0.01 per call

Plan metrics allow flexible billing models.

Subscription

A subscription links an organization to a pricing plan.

Example:

  • Organization: CloudAI
  • Plan: Pro
  • Billing Cycle: Monthly
  • Status: ACTIVE

Once a subscription is active, UsageFlow begins tracking usage and calculating invoices.

Subscription statuses include:

ACTIVE
SUSPENDED
CANCELLED

Subscriptions may be suspended if invoices fail.

API Keys

API keys allow your application to send usage data to UsageFlow.

Example key:

uf_live_xxxxxxxxxxxxxxxxx

Your backend includes the key when sending usage events.

Example request header:

x-usageflow-api-key: YOUR_API_KEY

API keys are stored securely using hashing.

Usage Events

Usage events represent raw usage data sent by your application.

Example event:

{
  "metric": "API_CALL",
  "amount": 1,
  "customerId": "user_123"
}

Each event records:

  • which metric was used
  • how much usage occurred
  • which customer triggered the event

Usage events are stored as the source of truth for billing.

Aggregated Usage

UsageFlow periodically aggregates raw usage events into summarized records.

Example aggregation:

Metric: API_CALL
Total Usage: 12,000
Billing Period: March 1 → March 31

Aggregation improves performance and enables efficient billing calculations.

Invoices

Invoices represent the financial record of usage for a billing period.

Example invoice calculation:

Base Price: $100
Usage: 12,000 API calls
Included: 10,000
Overage: 2,000 × $0.01
Total: $120

Invoice statuses:

PENDING
PAID
FAILED

Invoices are immutable once generated.

Webhooks

Webhooks notify external systems when important events occur.

Supported events include:

invoice.created
invoice.paid
invoice.failed
subscription.suspended

Example webhook payload:

{
  "type": "invoice.created",
  "data": {
    "invoiceId": "inv_123",
    "amount": 120
  }
}

Webhooks allow UsageFlow to integrate with your backend systems.

The Billing Lifecycle

The full billing pipeline in UsageFlow works like this:

Usage Event
↓
Usage Aggregation
↓
Invoice Generation
↓
Webhook Notification
↓
Payment Processing

Your application sends usage data, and UsageFlow handles the billing infrastructure.

Summary

UsageFlow is built around a few core building blocks:

Organization
↓
Metrics
↓
Plans
↓
Subscriptions
↓
Usage Events
↓
Aggregated Usage
↓
Invoices
↓
Webhooks

These components work together to provide a complete usage-based billing platform.

Next Steps

Continue exploring the documentation: