Invoices API

The Invoices API allows your application to retrieve invoices generated by UsageFlow.

Invoices represent the financial record of usage for a specific billing period. They are generated based on the organization’s active subscription, pricing plan, and aggregated usage.

This endpoint is useful for:

displaying billing history
exporting invoices to accounting systems
syncing billing data with your internal dashboards

Endpoint

GET /api/invoices

This endpoint returns invoices associated with the authenticated organization.

Authentication

Requests must include a valid API key.

Generate an API key from:

Dashboard → API Keys → Generate Key

Example key:

uf_live_abc123xyz

Include the key in the request header.

Headers

Header	Required	Description
`x-usageflow-api-key`	Yes	API key used to authenticate the request
Content-Type	Yes	Must be `application/json`

Example:

x-usageflow-api-key: YOUR_API_KEY
Content-Type: application/json

Example Request:

GET /api/invoices

Using curl:

curl https://your-domain.com/api/invoices \
 -H "x-usageflow-api-key: YOUR_API_KEY"

Using JavaScript:

const res = await fetch("https://your-domain.com/api/invoices", {
  headers: {
    "x-usageflow-api-key": process.env.USAGEFLOW_API_KEY,
  },
});
const invoices = await res.json();

Example Response:

{
  "invoices": [
    {
      "id": "inv_123",
      "amount": 120,
      "status": "PENDING",
      "periodStart": "2025-03-01T00:00:00.000Z",
      "periodEnd": "2025-03-31T00:00:00.000Z",
      "createdAt": "2025-04-01T00:00:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the invoice
amount	number	Total amount due
status	string	Invoice status
periodStart	string	Start of the billing period
periodEnd	string	End of the billing period
createdAt	string	Timestamp when the invoice was generated

Invoice Status

Invoices can have one of the following statuses:

PENDING
PAID
FAILED

PENDING

The invoice has been generated but not yet paid.

PAID

Payment for the invoice has been completed.

FAILED

Payment failed or the invoice could not be processed.

If an invoice fails, the subscription may be suspended depending on billing settings.

Example Billing Scenario

Imagine your organization has the following pricing configuration:

Plan: Pro
Base Price: $100
Metric: API_CALL
Included Units: 10,000
Overage Price: $0.01

During the billing period your application records:

API Calls: 12,000

UsageFlow calculates the invoice:

Base Price: $100
Overage: 2,000 × $0.01
Total: $120

This invoice will appear when calling the Invoices API.

How Invoices Are Generated

Invoices are generated using the following pipeline:

Usage Events
↓
Usage Aggregation
↓
Invoice Calculation
↓
Invoice Record Created
↓
Webhook Notification

Invoices are immutable financial records, meaning they are not recalculated after creation.

Best Practices

Sync Invoices with Your System

Use the Invoices API to sync billing data with your internal dashboards or analytics systems.

Combine with Webhooks

For real-time updates, use the webhooks system alongside the Invoices API.

Example webhook events:

invoice.created
invoice.paid
invoice.failed

Your system can listen for these events and update billing records immediately.

Next Steps

Continue exploring the documentation: