Skip to main content
Sign in

Event-Based Usage Billing and Meters

Danielle
  • Updated

Contents

What is Event-Based Usage Billing?

Event-Based Usage Billing allows you to send raw usage data (events) directly to Ordway, where flexible meters transform this data into billable quantities. Instead of pre-processing usage data before sending, it to Ordway. You can now send raw events and let our metering system handle all calculations.

Example: Instead of calculating total API calls per customer yourself, simply send each API call as an event. Create a meter to count these events and automatically bill customers based on their usage.

Key Concepts

Events

Events are raw data points that capture how customers interact with your product. Each event contains:

  • Customer ID: Links the event to a specific customer
  • Event Type: What action this represents (e.g., "api_call", "compute_heartbeat")
  • Timestamp: When the event occurred
  • Data: Additional properties specific to the event

Example Event

{
 "timestamp": "2024-08-07T01:03:34+08:00",
 "customer_id": "C-00001",
 "event_type": "compute_heartbeat",
 "data": {
   "compute_hours": "0.238",
   "storage_gb": "128",
   "cloud_provider": "AWS",
   "region": "US-EAST"
 }
}

Meters (Billable Metrics)

Meters transform raw event data into billable quantities by defining:

  • What to measure: Filter rules to select relevant events
  • How to measure: Aggregation method (SUM, MAX, MIN, COUNT, etc.)
  • Grouping: Optional dimensions for breaking down usage

Getting Started

Step 1: Create a Meter

  1. Go to Products & Plans > Meters.
  2. Click Add on the Meter List page.
  3. Provide a name and a description.
  4. Write your SQL query to define how usage should be calculated in the Filter and Aggregation.

Example

Total API Calls

SELECT COUNT(*) FROM events WHERE event_type = 'api_call'

Peak Storage Usage

SELECT MAX(CAST(data->>'storage_gb' AS DECIMAL)) 
FROM events 
WHERE event_type = 'compute_heartbeat'

5. Save your meter

Step 2: Send Events to Ordway

Via API - Single Event

POST /api/v1/usage_events

{
 "event_type": "api_call",
 "customer_id": "C-00001",
 "date": "2025-08-01",
 "data": {
   "endpoint": "/users",
   "method": "GET"
 }
}

Via API - Bulk Events

POST /api/v1/usage_events/bulk

{
 "type": "create",
 "events": [
   {
     "event_type": "api_call",
     "customer_id": "C-00001",
     "date": "2025-08-01",
     "data": {"endpoint": "/users"}
   },
   {
     "event_type": "api_call",
     "customer_id": "C-00002",
     "date": "2025-08-01",
     "data": {"endpoint": "/orders"}
   }
 ]
}

Via Import

1. Navigate to Operations > Usage Events

2. Click Import.

3. Upload CSV file (max 1M records or 200MB).

4. Review validation report and process.

Example: CSV Format

Event Id,Event Name,Event Date,Customer Id,Data

evt_001,api_call,2025-08-01,C-00001,"{""endpoint"":""/users""}"

Step 3: Assign Meters to Charges

1. Create or edit a plan with usage-based charges

2. In the charge configuration:

  • Select Usage Based charge type
  • Choose your meter from the Meter dropdown
  • Configure pricing 

3. Save your plan.

Step 4: Create Subscriptions

1. Create subscriptions using plans with metered charges

2. Optionally override meter selection at subscription level


3. Events will automatically be processed and billed according to your meter configuration

Managing Events

Editing Events

Update event properties via API:

PUT /api/v1/usage_events/:id

{
 "data": {
   "region": "US-WEST",
   "instance_type": "xlarge"
 }
}

Note: Only the `data` property can be modified after event creation.

Delete Events

Single Event Deletion:

Via API

DELETE /api/v1/usage_events/:id

Via UI

1. Navigate to Operations > Usage Events. The Usage Events page is displayed. 

2. Click three-dot (⋮) icon next to the events and click Delete.

3. Click Delete in the confirmation modal. A confirmation message "The event was deleted successfully” appears to indicate completion.

Bulk Event Deletion

Via API: POST /api/v1/usage_events/bulk

{
 "type": "delete",
 "events": [
   {
     "event_id": "3301d222-8f7c-417f-9874-cf91c0359728"
   }
 ]
}

Via UI

  1. In the left navigation pane, select Operations > Usage Events.
  2. Use the checkboxes to select one or more usage events you want to delete.
  3. In the Actions menu, click Delete Selected.

  1. In the confirmation modal, click Delete (n) Records to proceed.

Important

  • When deleting processed events, the system automatically checks whether the associated Billing Service Lines (BSLs) have been invoiced.
  • If the BSLs have not been invoiced, the related usage events are marked as pending and reprocessed to update billing calculations.

Export Events

Export your event data:

  1. Navigate to Operations > Usage Events. Apply any desired filters.
  2. Click Export Selected.

  1. Select the format.
  2. Click Export.

Event Processing States

Events go through several processing states:

  • Pending: Newly ingested, awaiting processing
  • Processing: Currently being metered
  • Processed: Successfully metered and ready for billing
  • Failed: Processing error (check error messages)

Error Tracking

When events fail to process:

  • Error messages are displayed in the event details
  • Use the Error Message filter to quickly identify failed events
  • Edit the event to correct issues and trigger reprocessing
  • Error messages are automatically cleared when events successfully reprocess

Audit Trail

All event actions (create, update, delete) are automatically logged in the audit trail for compliance and troubleshooting purposes.

Work with Meters

SQL Mode Features

  • Full SQL editor with syntax highlighting for complex calculations
  • Support for SUM, MAX, MIN, AVG, COUNT, and UNIQUE aggregations
  • Advanced features like window functions and CASE statements

Example

SELECT 
SUM(CAST(data->>'compute_hours' AS DECIMAL)) as total_hours,
MAX(CAST(data->>'storage_gb' AS DECIMAL)) as peak_storage
FROM events
WHERE event_type = 'compute_heartbeat' 
AND data->>'cloud_provider' = 'AWS'

Best Practices

Event Design

  • Use consistent event naming conventions
  • Include all relevant properties for future flexibility
  • Always include customer identification
  • Add idempotency keys to prevent duplicate events

Meter Creation

  • Start with simple aggregations before building complex SQL
  • Test meter logic thoroughly before assigning to charges
  • Document meter logic for team understanding

API Reference

Event Endpoints

  • POST /api/v1/usage_events - Create single event
  • POST /api/v1/usage_events/bulk - Bulk operations (create, update, delete up to 100 events)
  • GET /api/v1/usage_events - List events with filtering
  • GET /api/v1/usage_events/:event_id - Get specific event
  • PUT /api/v1/usage_events/:id - Update event
  • DELETE /api/v1/usage_events/:id - Delete single event

Bulk Operations Response Format

{
 "success_count": 1,
 "error_count": 0,
 "failed": {}
}

Enhanced Plan or Charge APIs

  • Plan and charge APIs now include meter field support
  • Import/export templates support meter assignments

Limitations

  • Meter changes apply to future events only (no retroactive updates)
  • Event backfilling will not trigger invoice updates
  • Maximum 100 events per bulk API request
  • Maximum 1M records or 200MB for file imports
Was this article helpful?
0 out of 0 found this helpful
Please sign in to submit a request.
Return to top

Related articles

Comments

0 comments

Please sign in to leave a comment.