` on your code, with the class amberflo and a `data-amberflo-type` attribute to setup the element. This `data-amberflo-type` attribute is responsible for rendering the different views that we support.
You can further personalize each component by adding attributes to the `
`:
- `data-amberflo-colors` – Set a HEX or color name to define the primary brand color. Defaults to Amberflo's color palette.
- `data-amberflo-font-size` – Set a base font size (e.g., 16). Component fonts will scale proportionally.
- `data-amberflo-font-family` – Provide a comma-separated list of fonts. The browser will use the first available font.
- `data-amberflo-font-custom` – Import a Google Font if it’s not already supported. This must be used together with data-amberflo-font-family.
- `data-amberflo-with-container` – "true" or "false". If "true", a container box is displayed around the widget.
- `data-amberflo-with-title` – "true" or "false". If "true", the widget title is shown (container must also be enabled).
- `data-amberflo-title` – Set a custom title for the widget. If omitted, the default title is used.
All customization attributes are optional. If not specified, Amberflo’s default design system will be applied.
```html
```
Some views may require additional attributes depending on the data they display. These attributes can be updated programmatically at any time to render a different view or change the current state.
For example, you can initially display a **Usage Table** for one meter and then update the view dynamically—such as when a user clicks a button—to show data for a different meter without reloading the page.
## Get Session Token
To interact with Amberflo—whether through the API or the AmberfloSDK—you must first create a session token.
The recommended approach is to retrieve this token from a backend endpoint on your server using the browser’s `fetch` function on the client side. This method works particularly well for single-page applications, especially those built with modern frontend frameworks like React.
For more information check out our [Create a session API](docId\:p_45dCxEKUOsbG4vBhz06)
This example shows how to create the **server endpoint** that serves the client secret:
```javascript
const express = require('express');
const app = express();
const request = require('request');
app.get('/amberflo-session', async (req, res) => {
request({
method: 'POST',
uri: 'http://app.amberflo.io/session',
body: {
"customerId": "{{DESIRED_CUSTOMER_ID}},
"expirationEpochMilliSeconds": {{EXPIRATION_DATE_IN_MILLISECONDS}}
},
headers: {
"X-API-KEY": "{{YOUR_API_KEY}}"
}
}, function (error, response, body) {
if (!error && response.statusCode == 200) {
res.json({ sessionToken: response.sessionToken })
}
}
);
})
```
📘 The above example is in Node.js.
You can get `X-API-KEY` from the Amberflo site inside **Settings -> Account Configurations -> API keys.**
You can also get the `customerId` from Amberflo site inside **Customers → Click on one customer → Copy Customer ID.**
This example demonstrate how to **fetch the session token** with JavaScript in the client side:
```javascript
const response = fetch('/amberflo-session').then(function(response) {
return response.json();
}).then(function(responseJSON) {
const sessionToken = responseJson.sessionToken
})
```
## Using an Event
As you explore the [Available Views](docId\:kIPKru3tyXh4axofLKCFG) , you’ll notice that some of them support events. For example, the Usage Table view includes a `datechange` event that fires when the date is changed using the date picker.
These events give you the flexibility to trigger additional actions in your app whenever a supported interaction occurs within an Amberflo view.
Here is an example of how to use an event using the `datechange` event with the Usage Table view:
```html
```
## Invoice-related Options
Several views in Amberflo—such as the Invoices List and Invoice Details—display invoice-related data. You can customize how this data appears by adjusting settings under [Amberflo → Settings → Invoice](https://ui.amberflo.io/settings/invoice).
There are currently two configurable options:
**Displaying cached invoices**
You can choose whether the data shown in invoice views is retrieved in real-time or from a cached version. Using cached data helps improve performance and speeds up invoice rendering.
**Grouping product items on invoices**
Amberflo allows you to organize product items into categories. These categories appear on the invoice to make it easier to understand grouped usage and charges.
## SDK Versions
***📘 ***Releases
***01/19/2024 - Version 1.0.30***
***01/16/2024 - Version 1.0.29***
***01/10/2024 - Version 1.0.28***
***08/04/2023 - Version 1.0.27***
***08/04/2023 - Version 1.0.26***
***07/12/2023 - Version 1.0.25***
***02/06/2023 - Version 1.0.24***
***01/09/2023 - Version 1.0.23***
***12/27/2022 - Version 1.0.22***
***12/20/2022 - Version 1.0.21***
***12/15/2022 - Version 1.0.20***
***12/08/2022 - Version 1.0.19***
***11/24/2022 - Version 1.0.18***
***10/20/2022 - Version 1.0.17***
***10/12/2022 - Version 1.0.16***
***10/04/2022 - Version 1.0.15***
***09/14/2022 - Version 1.0.14***
***09/12/2022 - Version 1.0.13***
***09/01/2022 - Version 1.0.12***
***08/29/2022 - Version 1.0.11***
***07/29/2022 - Version 1.0.10***
***07/12/2022 - Version 1.0.9***
***07/07/2022 - Version 1.0.8***
***07/06/2022 - Version 1.0.7***
***06/07/2022 - Version 1.0.6***
***05/09/2022 - Version 1.0.5***
***05/07/2022 - Version 1.0.4***
***04/26/2022 - Version 1.0.3***
***04/21/2022 - Version 1.0.2***
***04/20/2022 - Version 1.0.1***
***04/13/2022 - Version 1.0.0***
## Available Views
### Usage Table
| **Attribute** | **Value** |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data-amberflo-type | usage-table |
| data-amberflo-meters | Comma separated meters apiNames you want to see on the table.
e.g.:
ApiCalls,cluster\_count,cluster\_instance\_hours,cluster\_partitions,cluster\_reads,cluster\_storage,cluster\_writes,CpuHours,DataVolumeGb,number\_of\_runs |
| | |
Example:
```html
```
### Usage Graph
Example
```html
```
### Cost Table
Example
```html
```
### Invoice Details
Example
```html
```
### Invoices List
Example
```html
```
### Orders Usage Graph and Table
Example
```html
```
### Prepaid Summary
Example
```html
```
### Prepaid Wallet
Example
```html
```
### Stripe Payment Method
```html
```
### Notes
Ensure that the page specified in `data-amberflo-return-url` includes the Amberflo script and properly initializes the SDK, just like the page where the component is originally hosted. This ensures continuity in rendering and functionality when the user is redirected.
Add the script:
```html
```
And make sure you instantiate it:
```javascript
```
### Pricing Plan
```html
```
### Included Units
### Order List
Example:
```html
```
### Order Details
```html
```
### Order Create
```html
```
### Order Usage Graph and Table
```html
```
## How to get the Stripe publishable key
- Go to to [stripe.com ](https://stripe.com/)and login with your username and password
- Once inside Stripe, go to [Dashboard](https://dashboard.stripe.com/)
- Inside the dashboard copy the publishable key. Check the image below for reference:
**Appendix 1: Full Code Example**
```html
```
[title] AWS S3
[path] Metering/Ingestion Options/
# Write events directly to an Amberflo supplied and secured AWS S3 bucket
Amberflo provisions an **AWS S3 bucket** for your account with the necessary **access rights and permissions** to write meter data.
- **Meter files are automatically picked up** for processing as soon as they arrive in the bucket.
- If processing fails, **error reports are written back** into the same bucket for review.
There are several ways to write data to S3, including:
- **AWS S3 SDK**
- **AWS Glue**
- **Logstash**
- **Fluentd**
- And other ingestion tools
To get your S3 bucket provisioned, please contact us.
## Format
The **meter records** you send to the S3 bucket should be of the same standardized format as accepted by the ingest meter API Here are some examples:
```json
[{
"customerId": "customer-123",
"meterApiName": "ComputeHours",
"meterValue": 5,
"meterTimeInMillis": 1619445706909,
"dimensions": {
"region": "us-west-2",
"az": "az1"
}
}]
```
We also support [NDJSON](https://github.com/ndjson/ndjson-spec) format (JSON separated by a newline)
```json
{ "customerId": "customer-123", "meterApiName": "ComputeHours", "meterValue": 5, "meterTimeInMillis": 1619445706909 }
{ "customerId": "customer-321", "meterApiName": "ComputeHours", "meterValue": 4, "meterTimeInMillis": 1619445712341 }
{ "customerId": "customer-123", "meterApiName": "ComputeHours", "meterValue": 1, "meterTimeInMillis": 1619445783456 }
```
## Code Example
The S3 object key should have the date to allow easier troubleshooting (e.g.: `/ingest/amberdata/06-07-2022/0000a2e4-e6ad-11ec-8293-6a8da1c4f9f0`);
```python
import json
from uuid import uuid1
from datetime import date
import boto3
records_to_send = [{
'customerId': 'customer-123',
'meterApiName': 'ComputeHours',
'meterValue': 5,
'meterTimeInMillis': 1619445706909,
'dimensions': {
'region': 'us-west-2',
'az': 'az1'
}
}]
bucket_name = '183-amberflo'
date = datetime.now().strftime(r'%m-%d-%Y')
object_key = 'ingest/amberdata/' + date + '/' + str(uuid1())
s3 = boto3.resource('s3')
s3.Object(bucket_name, object_key).put(Body=json.dumps(records_to_send), ACL='bucket-owner-full-control')
```
## Troubleshooting
If you encounter issues while ingesting data through S3, Amberflo will generate a **failure report **in the following S3 path:
`s3://
/failed-requests//.reason.txt`
This file contains the reason for the failure and can help you diagnose and resolve the issue.
## Compression (gzip support)
Amberflo supports ingesting **gzip-compressed files**.
- Simply upload files with the **.gz extension**
- Amberflo will **automatically decompress** these files during ingestion
[title] Meter Rates (Cost Calculation)
[path] Cost Tracking/
Meter rates define how usage is converted into **cost**.
This page explains how to configure cost rates on a meter so that all incoming usage can be translated into accurate spend.
This assumes you have already created one or more meters.
## **How Meter Rates Work**
When usage is ingested into a meter, Amberflo:
1. Matches the usage to a **meter**
2. Applies a **rate** defined on that meter
3. Calculates the resulting **cost**
The rate is the rule that determines how each unit of usage is valued.
Rates can change over time. When they do, you create a new rate configuration and apply it going forward.
## **Navigate to Meter Rates**
1. Go to **Cost → Configure → Meters**
2. Select the meter you want to configure
3. On the meter details page, click the **Rate** tab (middle tab)
4. Click **Create Meter Rate** (top right)
## **Create a Meter Rate**
### **Basic Fields**
- **Label**
A name for the rate configurationSince rates may change over time, use a label that reflects the version or context.
Examples:
- OpenAI Pricing - Jan 2026
- v1 Cost Rates
- GPT Model Pricing Q1
- **Description (optional)**
Add context about what this rate represents
## **Choose a Rate Model**
Amberflo supports two primary models for cost calculation.
### **1. Per Unit**
Each unit of usage has the same cost.
**Example:**
- Every API call costs $0.005
- Every job execution costs $0.10
This model is appropriate when cost does not vary based on context.
### **2. Per Unit with Dimensions (Recommended)**
Cost varies based on attributes of the usage.
This is the standard approach for most real-world systems.
**Why Use Dimensions**
In many systems, cost is not uniform. It depends on factors such as:
- Type of operation
- Resource used
- Configuration of the request
For example, with token-based usage:
- **Input tokens** and **output tokens** have different costs
- Different **models** have different pricing
These differences are captured using dimensions.
## **Build the Rate Table**
When using **Per Unit with Dimensions**, you define a table of rates.
- Each **column** represents a dimension
- Each **row** represents a unique combination of dimension values
- Each row has a **per-unit cost**
### **Example Structure**
If your meter includes:
- model
- token\_type
Your table might include rows like:
- model = A, token\_type = input → cost X
- model = A, token\_type = output → cost Y
- model = B, token\_type = input → cost Z
Each combination can have a different cost.
## **Configuring the Table**
- Remove any dimensions that are not relevant to cost calculation
(for example, workload is typically used for attribution, not pricing)
- Use **Add Row** to define new combinations
- Use **Add Column** if you need to include additional dimensions
For each row:
1. Set the dimension values
2. Enter the corresponding **cost per unit**
## **Automation Options**
You do not need to configure rates manually in the UI.
Amberflo supports:
- **API-based configuration**
- **CSV import**
This allows you to:
- Sync rates from external pricing sources
- Update rates programmatically
- Manage large pricing tables efficiently
## **Saving and Applying Rates**
Once your rate configuration is complete:
- Click **Save**
From that point forward:
- All new usage events for that meter will use this rate configuration
- Cost will be calculated automatically based on the defined rules
## **Updating Rates Over Time**
Rates change. When they do:
1. Create a **new meter rate**
2. Use a clear label to indicate the new version
3. Apply it going forward
Do not overwrite previous configurations if you need historical accuracy.
## **Summary**
Meter rates are the foundation of cost calculation in Amberflo.
They:
- Define how usage translates into cost
- Support both simple and complex pricing logic
- Allow variation based on dimensions
- Can be managed manually or programmatically
Accurate rates ensure that your cost data reflects the real behavior of your systems.
[title] Billing for LLM tokens
[path] Common Use Cases/
This guide shows how to bill customers for an AI chatbot product using:
- **API calls (per request)**
- **LLM tokens (input + output, priced differently by model)**
This is a real-world billing pattern used by most AI products.
By the end, you will have:
- Multiple meters (API calls + tokens)
- A pricing plan with **multiple rate types**
- Dimensional pricing (model + token type)
- A customer receiving a fully broken-down invoice
## **The Scenario**
You are building an **AI chatbot SaaS**.
Your pricing model:
- $0.01 per API request
- Token usage billed based on:
- **Model** (Model A vs Model B)
- **Token type** (input vs output)
This reflects how real AI systems are priced.
## **What You’ll Build**
You will implement:
:::BlockQuote
API Request → Flat charge
LLM Tokens → Dimensional pricing (model + type)
→ Combined into a single invoice
:::
## **Step 1: Create Meters**
You need **two meters**.
### **1A. API Calls Meter (Simple)**
### **Navigate**
- Go to **Meters**
- Click **Create Meter**
### **Configure**
- **Label**: API Calls
- **API Name**: auto-generated
- **Meter Type**: Count
No dimensions required.
Note:
You *can* add dimensions (endpoint, region, etc.) for analytics or cost tracking, but they are not needed for billing here.
Click **Create**.
### **1B. LLM Tokens Meter (Dimensional)**
### **Navigate**
- Go to **Meters**
- Click **Create Meter**
### **Configure**
- **Label**: LLM Tokens
- **Meter Type**: Count
### **Add Dimensions**
Add:
- model
- type (input, output)
These are **required** for realistic AI pricing.
Click **Create**.
## **Step 2: Create a Pricing Plan**
### **Navigate**
- Go to **Pricing**
- Click **Create Pricing Plan**
### **Configure**
- **Name**: Chatbot Usage Plan
- **Billing Period**: Monthly
Click **Continue**.
## **Step 3: Add Rates**
You will add **two rates** to the same plan.
### **3A. API Calls Rate (Per Unit)**
- Click **Add Rate**
- Select **Usage-Based**
Configure:
- **Meter**: API Calls
- **Rate Model**: Per Unit
- **Price**: 0.01
This means:
- Every API request = $0.01
### **3B. LLM Tokens Rate (Dimensional)**
- Click **Add Rate** again
- Select **Usage-Based**
Configure:
- **Meter**: LLM Tokens
- **Rate Model**: Dimensions
- **Tier Model**: Per Unit
### **Define Pricing Matrix**
You will define rates based on:
- model
- type
Example:
| **model** | **type** | **price per token** |
| --------- | -------- | ------------------- |
| model\_a | input | 0.00001 |
| model\_a | output | 0.00002 |
| model\_b | input | 0.000005 |
| model\_b | output | 0.00001 |
Each row is a separate pricing rule.
### **Important**
- You are pricing **each combination independently**
- This is how real AI pricing works
Click **Save**.
## **Step 4: Create a Customer**
### **Navigate**
- Go to **Customers**
- Click **Create Customer**
### **Configure**
- **Customer Name**: Test Customer
- **Customer ID**: test\_customer
Click **Save**.
## **Step 5: Assign Pricing Plan**
- Open the customer
- In **Pricing Plans**, click **Assign Plan**
Configure:
- **Plan**: Chatbot Usage Plan
- **Start Date**: Now
Click **Assign Plan**.
## **Step 6: Send Usage**
Now you simulate real usage.
### **Navigate**
- Go to **Meters**
- Open **LLM Tokens**
- Click **Event Upload**
### **Example Event (Tokens)**
:::BlockQuote
\[
\{
"meterApiName": "llm\_tokens",
"meterValue": 1000,
"dimensions": \{
"model": "model\_a",
"type": "input"
}
}
]
:::
Send multiple events for different combinations:
- model\_a + input
- model\_a + output
- model\_b + input
### **API Calls Event**
Send another event using the API Calls meter:
:::BlockQuote
\[
\{
"meterApiName": "api\_calls",
"meterValue": 10
}
]
:::
## **Step 7: View the Invoice**
### **Navigate**
- Go to **Customers**
- Open your customer
### **What You’ll See**
Your invoice will include:
- API call charges
- Token usage charges
By default, token charges are broken down by:
- Model
- Token type
Example:
:::BlockQuote
Model A - Input Tokens → $X
Model A - Output Tokens → $Y
Model B - Input Tokens → $Z
API Calls → $W
Total → $T
:::
### **Important Note**
You **do not have to expose this level of detail** to your customers.
- This breakdown is the default
- You can simplify how invoices are presented
### **If You Don’t See Data**
- Refresh the page
- Amberflo does not auto-refresh
If still empty:
- Confirm events were sent
- Confirm dimensions match pricing
- Confirm plan is assigned
## **What You Just Built**
You implemented a real AI billing system:
- Multiple meters
- Mixed pricing models
- Dimensional pricing
- Unified invoice
## **Why This Matters**
This pattern lets you:
- Price different models differently
- Charge input vs output tokens separately
- Combine request-based and usage-based billing
This is how modern AI products monetize.
## **Next Steps**
- Add **tiered pricing** for tokens
- Introduce **discounts or credits**
- Connect to **cost tracking** for margin visibility
For internal cost attribution, see:
[Workloads](docId\:XToRHVsoI2AOK1BZPwfDU)
[title] Billing Overview
[path] Billing & Monetization/
Amberflow gives you a single platform to observe AI usage, understand true costs, and monetize AI-powered features. Know exactly what your AI usage costs you, what you charge customers, and how margins change as usage scales.
## Why It Matters
AI usage has real costs, and if you are offering AI-powered features to customers, those costs need to be recovered and monetized. Without a usage-aware billing system, teams either undercharge and absorb unpredictable AI costs, or overcharge with blunt pricing that discourages adoption.
Amberflow’s built-in rating and billing engine allows you to turn AI usage into revenue. By combining precise usage data, accurate cost information, and flexible pricing models, you can bill customers fairly, track margins in real time, and confidently scale AI-driven products.
This is how AI moves from a cost center to a revenue engine.
## How to Use It
Use Monetization when you want to charge customers based on how they actually consume AI-powered features.
### Define usage-based pricing plans
Amberflow allows you to create pricing plans that reflect how your product is used.
You can define plans based on:
- AI usage metrics such as requests or tokens
- Tiered or volume-based pricing
- Multiple dimensions, such as model, provider, or feature
This flexibility allows you to align pricing with customer value instead of relying on static seat-based models.
### Rate usage automatically
All incoming usage is passed through Amberflow’s rating engine.
The rating engine:
- Applies your defined pricing rules
- Calculates what each customer owes based on actual usage
- Accounts for discounts, promotions, or negotiated terms
This ensures that billing is consistent, auditable, and directly tied to real consumption.
### Integrate with Stripe for customer payments
With this integration, you can:
- Automatically generate usage-based charges
- Bill customers on a calendar-month basis
- Bill customers on a fixed monthly anniversary date
This supports both traditional SaaS billing models and modern usage-based billing approaches.
### Track revenue, cost, and margin
Because Amberflow already tracks the underlying cost of AI usage, monetization goes beyond invoicing.
You can:
- See how much revenue is generated from AI usage
- Compare revenue to underlying AI costs
- Understand profit margins at a granular level
This visibility allows you to price confidently and adjust plans based on real economics, not assumptions.
### Apply discounts and promotions
Pricing plans can include:
- Discounts for specific customers
- Promotional pricing
- Volume-based incentives
These adjustments flow through the same rating and billing pipeline, ensuring that promotions do not break reporting or margin analysis.
### Scale without manual reconciliation
All monetization flows from the same usage data used for observability, budgets, and cost controls.
This means:
- No duplicate tracking systems
- No manual reconciliation between usage, cost, and billing
- A single source of truth for AI consumption and revenue
- As usage grows, billing scales automatically with it.
## When to Use This Page
Use Monetization when:
- You are offering AI-powered features to external customers
- You want to charge based on real usage instead of fixed pricing
- You need visibility into revenue and profit margins for AI
- You want billing to scale with usage without operational overhead
This page shows how Amberflow helps you turn AI usage into sustainable revenue.
[title] Prometheus
[path] Metering/Ingestion Options/
# Ingesting Meters with Prometheus Remote Write
Amberflo supports ingesting metrics directly from Prometheus using its native remote write functionality. This enables real-time ingestion of usage data as meter events, allowing you to monitor and allocate infrastructure costs with precision.
This approach works particularly well for environments where Prometheus is already deployed, such as in Kubernetes clusters, but it is not limited to Kubernetes. You can send any relevant Prometheus metrics from your infrastructure or applications.
Why Use Prometheus for Meter Ingestion?
- **Low-lift integration:** No custom agent or Amberflo library required. Simply configure remote\_write in Prometheus.
- **Real-time metering:** Prometheus pushes events directly to Amberflo as they are generated.
- **Flexible attribution:** Use dimensions like namespace, node, tenant, or application to enable fine-grained usage tracking and cost allocation.
- **Custom metrics:** Supports ingestion of both built-in system metrics and any custom metrics sent to Prometheus from your IT environment.
### Example Use Case: Kubernetes
Prometheus is often used to monitor Kubernetes clusters. With Amberflo, you can ingest metrics such as:
- **Kube-state metrics:** For example, pod states, resource requests, and limits.
- **Node metrics:** CPU, memory, disk, and I/O usage from underlying nodes.
- **Kubelet metrics:** Container-level metrics like actual resource consumption.
- **Custom application metrics:** Data sent to Prometheus by in-cluster apps.
Amberflo uses the namespace label as the customerId by default, which allows for accurate cost allocation by namespace (or by other dimensions if preferred).
## To use Prometheus remote write with Amberflo, you need the following:
**You provide:**
- Any Prometheus-monitored system (e.g. a Kubernetes cluster)
- Prometheus deployed and collecting metrics
- Outbound internet access from Prometheus
**Amberflo provides:**
- An API to accept the remote write
- Ability to set custom ingestion schema for metric data
## Prometheus Remote Write Configuration
Below is an example configuration snippet to enable remote\_write in your Prometheus setup:
```yaml
remote_write:
- url: https://app.amberflo.io/ingest/prometheus
name: amberflo
write_relabel_configs:
- source_labels: [__name__, pod]
separator: ":"
regex: 'kube_pod_info:coredns(.+)'
action: keep
- action: replace
source_labels: [namespace]
target_label: customerId
- regex: 'customerId|node|pod|helm_sh_chart|__name__'
action: labelkeep
headers:
x-api-key: XXX-XXX-XXX
```
This configuration:
- Keeps only relevant metrics based on name and pod.
- Maps the Prometheus namespace label to Amberflo’s customerId.
- Limits which labels are sent to Amberflo for ingestion.
- Authenticates using your Amberflo API key.
[title] Databases and JDBC
[path] Metering/Ingestion Options/
## Ingest Meters from a JDBC Enabled Source
Using metering data from an existing **JDBC-compatible source** is a common practice.
Many systems support JDBC, including:
- **MongoDB**
- **Elasticsearch**
- **MySQL**
- **PostgreSQL**
- And many more
### **Options for Ingesting JDBC Data into Amberflo**
You can choose one of the following methods to ingest meter records from your JDBC source:
**1. Use Amberflo SDKs**
Write custom code using one of our **official SDKs** to extract data from your JDBC source and ingest it into Amberflo.
- SDKs are available in multiple languages (e.g., **Python**, **JavaScript**)
- Code samples are available to get you started quickly
[https://github.com/amberflo/metering-python-sample](https://github.com/amberflo/metering-python-sample)
**2. Use Logstash with the JDBC Plugin**
You can use **Logstash** and its **JDBC input plugin** to extract data from your JDBC source and upload it to **Amberflo's S3 bucket**.
**3. Use an ETL Tool**
Any **ETL tool **capable of pushing data into **S3** can be used.
Once data lands in your Amberflo S3 bucket, **Amberflo will automatically ingest it**.
[title] Ingestion Options
[path] Metering/
A successful usage-based business model with metered billing is built on the foundation of an **accurate usage data collection strategy**.
Amberflo provides multiple easy ways to begin collecting data without the need to re-tool your systems.
## SDK
Using the Amberflo SDK gives you:
- More control
- Immediate feedback via response codes
- Support for batching records
- Flush-on-demand functionality
**Batching Records**
Amberflo SDKs are designed to support **high-throughput environments**.
You can confidently:
- Send **hundreds of meter records per second**
- Deploy the SDK on web servers handling **high volumes of traffic**
- Ensure accuracy and availability **from day one**
**How it works:**
Each call is **queued in memory**, not sent immediately over HTTP. Messages are **batched and flushed in the background**, allowing for much faster performance.
You can configure the **batch size **and the** flush rate.**
**Flush on demand (Blocking call)**
You can **flush the queue manually**—for example, at the end of your program—to ensure no data is left unsent. Just call the flush method:
`metering.flush()`
**Important:**
This is a **blocking call**—it will pause the calling thread until the queue is empty.
We recommend using it only in **cleanup scripts**, not during request processing.
## Non-SDK
We **strongly recommend using our SDK for AWS S3**, as it offers the best of both worlds:
1. Access to **rich SDK features** (see above)
2. Guaranteed **AWS S3 uptime SLA** for meter ingestion
However, we fully support cases where using a third-party SDK isn’t possible or preferred. In such scenarios, Amberflo offers multiple alternatives:
**Amberflo Application**
The Amberflo web application provides a **rich set of real-time dashboards** for visualizing:
- **Usage**
- **Revenue**
Dashboards can be filtered by:
- **Customer**
- **Meter name**
- **Custom dimensions**
**Amberflo API**
Amberflo is an **API-first platform**. Every feature and object can be accessed programmatically via our APIs and SDKs.
**AWS S3**
Amberflo provides access to an **Amazon S3 bucket** with predefined **permissions and controls **to write meter data directly.
**Logging Systems**
Many companies already use **centralized logging infrastructure** (e.g., **AWS CloudWatch**) for operational insights.
While logging systems aren't built specifically for metering, they can serve as a **"catch-all"** for usage data streams because they’re deeply integrated into your systems.
Amberflo supports this approach by:
- Allowing you to **write meter events to your logging system**
- **Extracting** meter events from it using supported connectors
We currently provide a connector for **AWS CloudWatch** . We’re continuously adding **new out-of-the-box integrations**—check the **Integrations **section for updates.
If you have a specific request, please contact us.
[title] Files
[path] Metering/Meter Integration Options/
## Ingesting Meters from File Sources
Metering data is often generated and stored in **files** by other systems.
These files may be in formats such as:
- **CSV**
- **JSON**
- Other structured or semi-structured types
In many cases, the data needs to be **transformed** before it can be ingested into Amberflo’s metering system.
**Options for Ingesting File-Based Metering Data**
You have several methods available:
1. **Write code using our SDKs to:**
Read data from files, Transform the data if needed and Send it to Amberflo for ingestion
2. **Use Logstash to: **
Parse and transform the file contents and Upload the transformed data to Amberflo's **S3** **bucket**.
3. **Use an ETL Tool**
Any **ETL tool** that can push data to **S3** is supported.
Amberflo will automatically pick up the files and ingest them once they’re in your assigned bucket.
[title] Meter Dimensions
[path] Metering/
# Dimensions
Amberflo’s Metering Service enables you to answer key questions in real time with precision: **What was used, by whom, when, where, and how much?**
Amberflo Meter Event data structure encapsulates this in the following way -
| What | Meter name and API name |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| Whom
When
How much
Where | Customer ID or Business Unit ID
Timestamp
Meter value
Dimensions |
To support this, you can add **dimensions** to your meter definitions. Dimensions are **custom key-value pairs** included with each meter event, allowing you to **enrich the event data with contextual metadata.**
## **What Are Dimensions?**
**Dimensions are the schemaless portion of a meter definition.** They provide a flexible way to customize the payload of a meter event without predefined constraints.
This allows you to capture and associate metadata such as:
- Where the usage originated (e.g., cloud provider, region, zone)
- Additional attribution beyond customer ID (e.g., cluster, project, department)
- Event state or status
- Any other business-specific markers
You are free to define any number of dimensions that reflect the context of your usage data.
**Important note**: If Dimensions are not defined ahead of time, new ones are automatically created upon ingestion.
## **How Dimensions Are Used**
**Grouping and Filtering**
Amberflo automatically groups and filters meter events by their dimension values. For example, if you define a dimension called cloud\_provider with values such as AWS, Azure, or Google, Amberflo will automatically sort, group, and make those values filterable in the UI and APIs.
**Pricing and D****iscount****s**
Dimensions are not only useful for analytics but also play a key role in constructing pricing plans and discount rules. You can use them to create pricing tiers, apply discounts, or define rate overrides based on specific dimension values.
**Usage Explorer**
Amberflo’s Usage Explorer provides real-time visibility into aggregated meter events, grouped and pivoted by dimension. This helps you analyze trends, drill into usage patterns, and segment your customers more effectively.
**Query API**
The Query API allows you to extract aggregated usage data by dimension, enabling integration with external tools or downstream billing systems.
Below are some common dimension types, but you are free to **create any dimensions specific to your use case** and domain:
1. Additional resource or application IDs
2. Department name
3. Cluster name or Project name
4. Cloud Region, Zone, etc.
5. Deployment environment
6. Customer type
7. Service version
more...
### For Public Cloud and Department Chargebacks
```json
{
"meter_name":"cloud_bedrock_input_tokens",
"meter_value":1725,
"time":1619445706909,
"dimensions":{
"business_unit_id":"us-east-2",
"region":"us-east-2",
"model":"anthropic_claude_3.7_sonnet"
}
```
### For Customer Billing:
```json
{
"customerId":"Wayne Enterprises, Inc.",
"meter_name":"ApiCalls",
"meter_value":575,
"time":1619445706909,
"dimensions":{
"region":"us-east-2",
"tenant_type":"Tech"
}
```
[title] Untitled
[path] /
[title] AI Usage
[path] Cost Tracking/
## Why It Matters
AI costs do not grow randomly. They grow because usage changes. More requests, different models, new teams, inefficient integrations, or silent failures all show up in usage data before they show up on a bill.
AI Usage gives you direct visibility into the activity behind your AI spend. Instead of guessing why costs increased, you can see exactly what changed, when it changed, and who or what is responsible.
This is the layer that connects financial reporting to real operational behavior. Without it, cost control is reactive. With it, cost control becomes predictable.
## How to Use It
Use this page when you want to understand what is actually happening with AI usage across your organization.
### Start with the overview
At the top of the page, you see:
- Total spend on AI activity for the selected time range
- The top resources driving spend
- The resources with the fastest-changing usage
This gives you immediate context. You should be able to tell quickly whether usage looks normal or if something needs investigation.
### Review active usage metrics
Below the overview, you see time-series data for AI usage metrics such as tokens, API calls, and errors.
By default:
- Only metrics with usage are shown
- The time range is set to the last seven days
This provides a fast operational snapshot without noise. You can optionally show metrics with no usage if you want to see everything that is available.
### Drill into a specific meter
When something stands out, open the detailed view for that meter. Click on the button in the upper right of the graph that has two arrows. This can be used to expand the graph into the full page and provide many ways to dig into the data.
From there, you can:
- Change the time range to focus on when usage changed
- Adjust how data is grouped over time (hourly, daily, weekly, monthly)
- Choose whether values are shown as totals, peaks, minimums, or averages
These controls help you distinguish between steady growth, short-lived spikes, and bursty behavior.
### Break usage down by Workload
Usage can be viewed:
- Combined across the organization
- Broken out by Workload
Workloads are flexible and can represent teams, applications, projects, pipelines, etc. You can also select only specific Workloads to compare, keeping the view focused.
This makes it easy to identify ownership and isolate where changes are coming from.
### Filter to isolate the cause
You can filter usage by dimensions such as model or provider.
For example:
- View usage for a single model only
- Compare behavior across providers
- Isolate production traffic from everything else
Filters apply consistently to both charts and tables, so the data always matches what you see.
### Identify top consumers
Alongside the charts, you can see which Business Units are responsible for the most usage or spend over the selected period.
This helps you quickly answer who is driving usage, not just how much is being used.
### Inspect and export the data
Every chart is backed by a table showing the exact data points used in the visualization.
When needed, you can:
- Export the data as CSV
- Save the current configuration as a reusable view
Saved views are useful for recurring reviews or investigations and they can be found under the "Saved Views" navigation link.
## When to Use This Page
Use AI Usage when:
- Spend increased and you need to explain why
- You want to catch abnormal usage early
- You need to understand which teams, models, or providers are driving activity
- You want operational answers before financial escalation
This is how you move from reacting to AI costs to understanding them.
[title] Outcome Based
[path] Common Use Cases/
This guide explains how to implement **outcome-based pricing**.
Instead of charging for underlying activity (API calls, tokens, etc.), you charge for a **business outcome**.
## **The Scenario**
You are building an **AI-powered customer support platform**.
Instead of billing for:
- API calls
- LLM tokens
You charge customers based on:
**Support tickets successfully resolved**
### **Pricing Model**
- $2.00 per support ticket resolved
Customers are charged based on results, not underlying usage.
## **Core Concept**
:::BlockQuote
System Activity (calls, tokens, etc.)
→ Produces an Outcome
→ Meter the Outcome
→ Bill the Customer
:::
The key shift:
You are metering the **result**, not the individual steps that produce it.
## **Step 1: Define the Outcome**
Start by identifying the business event you want to charge for.
In this example:
- **Support Tickets Resolved**
This becomes your **meter**.
## **Step 2: Create the Meter**
### **Where to Configure**
- Go to **Meters**
- Click **Create Meter**
### **Configure**
- **Label**: Tickets Resolved
- **Meter Type**: Count
No dimensions required.
Each time a ticket is resolved, you will send:
- Meter value = 1
## **Step 3: Create a Pricing Plan**
### **Where to Configure**
- Go to **Pricing**
- Create a new pricing plan
### **Configure**
- **Name**: Support Outcome Plan
- **Billing Period**: Monthly
## **Step 4: Add a Usage-Based Rate**
### **Where to Configure**
- Add a **Usage-Based** rate
### **Configure**
- **Meter**: Tickets Resolved
- **Rate Model**: Per Unit
- **Rate**: $2.00
## **Step 5: Assign the Plan to a Customer**
### **Where to Configure**
- Go to **Customers**
- Assign the pricing plan to a customer
Once assigned, all metered outcomes will be billed.
## **Step 6: Sending Usage (Conceptual)**
Each time your system resolves a support ticket:
- Send a meter event with value = 1
If 50 tickets are resolved:
- Total usage = 50
## **Example Outcome**
If a customer resolves:
- 120 tickets in a month
### **Billing Calculation**
:::BlockQuote
120 tickets × $2.00 = $240
:::
## **Why Outcome-Based Pricing**
This model aligns pricing directly with **value delivered**.
Instead of charging for system activity:
- You charge for **what the customer actually cares about**
## **Important Distinction**
Outcome-based billing does **not replace** tracking underlying usage.
You should still track:
- API calls
- LLM tokens
- Other system activity
These are useful for:
- Cost tracking
- Optimization
- Internal visibility
For internal cost tracking and attribution, see:
[Workloads](docId\:XToRHVsoI2AOK1BZPwfDU)
[title] Prepaid Credits
[path] Billing & Monetization/Credits & Drawdowns/
Amberflo supports modern usage-based billing models such as **bulk-buy** and **wallet-based billing**, helping deliver predictability for both customers and internal accounting teams.
Customers can **pre-purchase Credits** by paying upfront for a specific amount of usage.
Each purchase adds a **Prepaid Credit Card** to the customer's **Wallet**, reflecting the available balance.
As usage occurs, charges are drawn down from the Wallet in real-time.
Invoices will still display the usage details and line item costs. However, no payment will be due on the invoice until the Wallet balance is fully depleted.
This approach allows for flexible, transparent billing while supporting prepayment and commitment-based pricing strategies.
The screenshot below shows how Prepaid Credits are applied to the subtotal on an **Invoice.**
## Adding Prepaid Credits
To add prepaid credits to a customer’s account:
1. Navigate to the **Customers** tab.
2. Select the customer by clicking on their **name**.
3. Go to the **Credits** tab within the customer profile.
4. Click **Add Prepaid Credits**.
You’ll be presented with a form to define:
- The **amount of prepaid credits**
- Any **conditions** or **expiration rules** (if applicable)
Once saved, the prepaid credit amount will be added to the customer’s **Wallet**, and usage will begin drawing down from this balance in real time.
A screenshot of the screen to define the Prepaid Credit amount with any conditions is shown below:
When adding prepaid credits, you'll need to provide the following details:
- **Transaction Name** – A descriptive name for easy reference
- **Number of Credits** – The total amount of prepaid credits to add
- **Charge Amount** (optional) – If left blank, a 1:1 credit-to-charge conversion will be applied by default
You can also choose the **transaction type**:
- **One-Time** – A single, non-recurring credit addition
- **Recurring** – Credits will be added on a regular schedule, based on the configured time frame
By selecting the checkbox **"Apply a Condition to Prepaid Credits"**, you can restrict the usage of these credits to:
- A specific meter
- A particular dimension combination
This is useful for limiting prepaid credits to certain features, products, or customer behaviors.
### **Charging the Customer**
You must also select how the customer will be billed for this transaction:
- **Now** – If your Stripe account is connected and the customer's payment information is available, the charge will be processed immediately.
- **Reconcile Later** – If Stripe is not configured or you prefer to charge manually at a later time
If Reconcile Later is selected, the transaction will be saved as **pending**.
### **Post-Save Behavior**
Once saved, return to the **Customer Profile** view.
You’ll see the pending prepaid credit transaction marked with a **"Requires Action"** tag, indicating that follow-up is needed to complete the charge.
See the screenshot below:
Once payment is received in your third-party payment system, go back to the pending prepaid credit transaction and select **Activate**. You will be prompted to provide the **Transaction ID** as confirmation of the payment. This step is important, as Amberflo uses the provided information to reconcile the prepaid credit purchase.
You can also activate the transaction programmatically using the APIs. See [Update an external prepaid card status](docId:9KYpmkXiAcSXvOXE7gkzx) for details.
After the activation is saved, the prepaid credits become available and will be automatically drawn down as usage is recorded.
## Credits Expiration
Amberflo automatically manages the balance of prepaid credits, deducting from it in real time based on billable usage. Each prepaid credit card includes an expiration date. Once that date is reached, any remaining credits on the card are no longer valid and will be removed from the available balance.
To configure or extend the expiration date for a specific prepaid credit card, go to the **Credits tab** within the customer’s profile. From there, open the details of the card in question and adjust the expiration settings as needed.
You can also configure the default expiration date for all purchased prepaid credit cards in the system. To do this, simply visit the **Credits **page under the **Settings** tab and configure the default duration of the prepaid credit cards.
[title] Margin Dashboard
[path] Billing & Monetization/
The Margin Dashboard gives you a clear, real-time view of your business profitability by combining revenue and cost from the same underlying usage data. Because Amberflo meters usage once and applies both pricing and cost rates to those events, you can accurately track how much you earn, how much you spend, and how your margins evolve over time.
This eliminates the disconnect between billing systems and cost tracking tools, and provides a single source of truth for understanding unit economics across your AI-powered services.
## Why This Matters
For AI-driven products, costs are variable and tightly coupled to usage. Without visibility into both sides of the equation, it is difficult to answer critical questions:
- Are we profitable at the workload or product level?
- How are AI costs impacting our margins?
- Are costs growing faster than revenue?
- Where should we optimize pricing or usage?
The Margin Dashboard answers these questions by showing revenue, cost, and margin together in a unified view.
## Overview Cards
At the top of the page, you will see four summary cards based on the last 3 months of activity:
- **Revenue**: Total billed revenue across all customers.
- **Metered Cost**: Total cost calculated from metered usage. This includes AI usage such as tokens, as well as any other metered infrastructure or services.
- **Margin**: Revenue minus metered cost.
- **Margin %**: Margin expressed as a percentage of revenue.
These metrics provide a quick snapshot of overall business performance and profitability.
## Rolling 12-Month Trend
Below the summary cards, the dashboard displays a rolling 12-month trend that combines:
- Revenue
- Metered Cost
- Margin %
This view allows you to track how your business is evolving over time:
- Identify whether revenue growth is outpacing cost growth
- Monitor margin compression or expansion
- Spot trends driven by changes in usage, pricing, or infrastructure
By visualizing these metrics together, you can quickly understand the relationship between usage-driven costs and your billing model.
## How It Works
The Margin Dashboard is powered by Amberflo’s metering and rating engine:
1. Usage is captured through meter events (e.g., API calls, tokens, compute time)
2. Costs are calculated by applying cost rates to those events
3. Revenue is calculated by applying pricing plans to the same events
4. Margins are derived directly from these aligned datasets
Because cost and revenue are based on the same underlying usage, the resulting metrics are consistent, accurate, and real-time.
## Benefits
- Unified visibility into revenue, cost, and margin
- Real-time profitability tracking for AI and usage-based services
- Accurate cost attribution tied directly to usage
- Faster identification of margin risks and optimization opportunities
- A foundation for pricing strategy and financial planning
[title] Segment.io
[path] Metering/Meter Integration Options/
You can ingest events into Amberflo using **Segment.io**.
Integration details can be found [here.](https://segment.com/catalog/integrations/amberflo/)
**What You Can Do**
With Segment's **Amberflo Destination**, you can:
- **Ingest meter events** using:
- track
- page
- screen
- **Create customers** in Amberflo using:
- identify
This integration provides a seamless way to bring your customer and usage data into Amberflo using Segment’s event tracking.
## Getting Started
1. From the
2. Search for
3. Choose which
4. Go to the
5. Enter the “API Key” in the
## Supported methods
## Page
Create a meter called **page** in Amberflo.
The ***page*** is ingested as meter with value 1.
```javascript
analytics.page({
userId: "some_user_id",
name: "Home",
properties: {
"title": "Welcome | Initech",
"keywords": "paper,comedy",
"search": "schrute farms",
"referrer": "https://google.com",
"path": "/home",
"browser": "Chrome",
"url": "https://segment.com"
}
})
```
**Mappings:**
**Amberflo webhook endpoint:**
```curl
curl --request POST \
--url https: //app.amberflo.io/ingest \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '
{
"uniqueId": "messageId",
"customerId": "some_user_id",
"meterApiName": "page",
"meterValue": 1.0,
"meterTimeInMillis": 1619445706909,
"dimensions": {
"name": "Home",
"title": "Welcome _ Initech",
"keywords": "paper,comedy",
"search": "schrute farms",
"referrer": "https:__google.com",
"path": "_home",
"browser": "Chrome",
"url": "https:__segment.com"
}
}
```
## Screen
Create a meter called **screen** in Amberflo. The *screen* event is ingested as meter with value 1.
```javascript
analytics.screen({
userId: "some_user_id",
name: "Home",
properties: {
"title": "Welcome | Initech"
}
})
```
**Mappings:**
**Amberflo webhook endpoint:**
```curl
curl --request POST \
--url https://app.amberflo.io/ingest \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '
{
"uniqueId": "messageId",
"customerId": "segmentUserId",
"meterApiName": "screen",
"meterValue": 1.0,
"meterTimeInMillis": 1619445706909,
"dimensions": {
"name": "Home",
"title": "Welcome _ Initech"
}
}
'
```
## Identify
Identify creates a customer in Amberflo or updates if customer already exists. Segment's **userId** is required for a customer in Amberflo. If **userId** is not set, then the customer will not be created in Amberflo and the *identify* event will be discarded.
```javascript
analytics.identify({
userId: "some_user_id",
traits: {
"name": "John Doe",
"email": "john.doe@email.com",
"plan": "premium",
"logins": 5,
"phone": "650-769-3240",
"username": "marakasina",
"website": "example.com",
"avatar": "https://s3.amazonaws.com/uifaces/faces/twitter/scottkclark/128.jpg"
}
})
```
**Mappings:**
**Amberflo webhook endpoint:**
```curl
curl --request PUT \
--url https://app.amberflo.io/customers \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '
{
"customerId": "XXXX-ZZZZZ",
"customerName": "myCustomerName",
"customerEmail" "john.doe@email.com",
"traits": {
"plan": "premium",
"logins": 5,
"phone": "650-769-3240",
"username": "marakasina",
"website": "example.com",
"avatar": "https:__s3.amazonaws.com_uifaces_faces_twitter_scottkclark_128.jpg"
}
}
'
```
## Track
Create a meter in Amberflo for the track *event* in Segment. The Segment track event is ingested as a meter with value of properties.value, or 1 if the value is not set.
```javascript
analytics.track({
userId: "some_user_id",
event: "ApiCalls",
properties: {
"value" : 2.0
"region": "us-west-2"
}
})
```
**Mappings:**
**Amberflo webhook endpoint:**
```curl
curl --request POST \
--url https://app.amberflo.io/ingest \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '
{
"uniqueId": "messageId",
"customerId": "some_user_id",
"meterApiName": "ApiCalls",
"meterValue": 2.0,
"meterTimeInMillis": 1619445706909,
"dimensions": {
"region": "us-west-2"
}
}
'
```
## Links
[Segment Catalog -> Amberflo](https://app.segment.com/amberflo-lior/destinations/catalog/amberflo)
[Segment Destination Documentation -> Amberflo](https://segment.com/docs/connections/destinations/catalog/amberflo/)