Understand Streams, Meters, and Segments

Learn how Streams, Meters, and Segments work together in Maxio Metering to turn incoming usage events into a billable quantity. Streams define incoming events, Meters calculate usage totals, and Segments group usage by attribute, connecting measured activity to invoice charges. For where Maxio Metering sits relative to the rest of usage-based billing, start with Understand Maxio Metering.

Stream

A Stream defines the structure of the events your system sends to Maxio.

Every Stream includes:

• Name and API Handle: The API Handle is used in the endpoint URL where your system sends events.
• Subscription Identifier: Tells Maxio which subscription each event belongs to.
• Event properties: Defines the fields included in each event.

Define the Stream schema before sending event data. Maxio validates incoming events against the Stream schema.

Example: An API Usage Stream may include api_calls, region, and customer_tier as event properties.

Meter

A Meter reads events from a Stream and calculates usage.

A Meter defines:

• Which Stream to read
• Which aggregation type to use
• Which property to calculate, if applicable
• Whether usage is segmented

A Stream can have multiple Meters. For example, one Stream can support one Meter that counts API calls and another Meter that sums bytes transferred.

Segment

A Segment groups usage by a property value. Use Segments when usage needs separate calculation or pricing by attribute.

A Meter supports up to 10 Segment properties simultaneously, enabling granular usage splits by dimensions such as region, model tier, API key, plan type, and environment.

Common Segment examples include:

• Region
• Customer tier
• Feature type
• Environment
• API key
• Plan type

Example: If events include a region property, a Meter can calculate usage separately for us-east, eu-west, and ap-southeast.

How the objects work together

Metering objects work together in this order:

Stream → Meter (with optional segmentation) → Metered Product → Invoice

1. A Stream receives events from your system and validates them against the Stream schema.
2. A Meter reads those events, optionally grouping usage by Segment properties to calculate usage separately per Segment value. Segment configuration is part of the Meter definition, not a separate step.
3. A metered product connects the calculated usage to pricing in Advanced Billing.
4. Maxio applies the usage charge to the Invoice.

Example setup:

Use the following setup to bill API calls by region:

• Stream: API Usage Stream
• Meter property: api_calls
• Aggregation type: Sum
• Segment: region
• Product pricing: Different price for each region

Key rules:

• Create the Stream before sending events.
• Events must match the Stream schema.
• Numeric properties can be used for calculations.
• Properties of any supported data type can be used for segments.
• A Meter must be connected to a metered product before it creates billing charges.

Related information

To create these objects for the first time, see Get Started with Maxio Metering.

To review configuration fields, see Configure Maxio Metering.

For guidance on aggregation types, see Choose the Right Aggregation Type.

For product pricing by Segment, see Design Your Catalog: Use Metering with Products.