Navigation
On this page

Getting Started

UsageFlow is a usage-based billing infrastructure designed for SaaS products that charge customers based on product usage.

It allows you to:

  • Track product usage through APIs
  • Define flexible pricing models
  • Generate invoices automatically
  • Notify external systems using webhooks
  • Manage organizations and team members

This guide will help you integrate UsageFlow into your product step-by-step.

Who Should Use UsageFlow

UsageFlow is ideal for platforms that charge customers based on usage such as:

  • API platforms
  • AI / LLM services
  • SaaS applications
  • Storage services
  • Internal billing infrastructure

If your product needs usage tracking + billing automation, UsageFlow provides the infrastructure.

High Level Workflow

The UsageFlow billing pipeline works like this:

Usage Event
↓
Aggregation Worker
↓
Aggregated Usage
↓
Invoice Generation
↓
Webhook Notification
↓
Payment / Subscription Update

Your application sends usage events, and UsageFlow handles billing automation.

Step 1 — Create an Organization

After signing up, create an organization.

An organization represents your company or team using UsageFlow.

Example:

Organization Name: CloudAI

Organizations allow:

  • Multi-tenant billing
  • Team collaboration
  • Role-based access control

Step 2 — Define Billing Metrics

Metrics define what kind of usage you want to track.

Example metrics:

  • API_CALL
  • ACTIVE_USER
  • STORAGE_GB
  • AI_TOKEN

Example metric creation:

Name: API Calls
Key: API_CALL
Unit: calls

Metrics are reusable across pricing plans.

Step 3 — Create a Pricing Plan

Plans define how customers will be charged.

Example plan:

Plan Name: Pro
Base Price: $100/month

Plans act as the pricing template for subscriptions.

Step 4 — Attach Metrics to the Plan

Now attach pricing rules to the plan.

Example:

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

Meaning:

  • First 10,000 API calls are included
  • Additional calls cost $0.01 each

Plans can contain multiple metrics.

Step 5 — Activate a Subscription

A subscription links an organization to a pricing plan.

Example:

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

Once activated, UsageFlow begins tracking usage for billing.

Step 6 — Generate an API Key

API keys allow your application to send usage data.

Navigate to:

Dashboard → Api Keys → Generate Key

Example Key:

uf_live_xxxxxxxxxxxx

This key authenticates your usage events.

Step 7 — Send Usage Events

Your backend records usage by calling the UsageFlow ingestion API.

Example request:

POST /api/track

Headers:

  • x-usageflow-api-key: <api_key>
  • Idempotency-Key: unique-event-id

Request Body:

{
  "metric": "API_CALL",
  "amount": 1000,
  "customerId": "user_123",
  "metadata": {
    "endpoint": "/v1/chat"
  }
}

Each request represents a single usage event

Step 8 — Usage Aggregation

UsageFlow automatically aggregates raw usage events into summarized records.

Example aggregation:

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

Aggregation improves performance and enables accurate billing.

Step 9 — Invoice Generation

At the end of the billing cycle, UsageFlow calculates billing using:

Plan Base Price + Overage Charges

Example:

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

An invoice is created and stored as a financial record.

Step 10 — Webhook Notifications

UsageFlow can notify your application when billing events occur.

Example webhook events:

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

Example payload:

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

This allows your system to automate billing workflows.

Step 11 — Manage Your Team

UsageFlow supports team collaboration.

Roles include:

OWNER
ADMIN
DEVELOPER
VIEWER

Admins and owners can invite users via email and manage organization access.

Next Steps

Continue exploring the documentation: