Get Started with Maxio Metering

Set up Maxio Metering in Advanced Billing to create an event stream, configure a meter, and send a test usage event. After setup, you can confirm that Maxio receives usage data and calculates meter results before connecting usage to billing.

Review these concepts before creating your first stream and meter:

• Stream: Defines the event structure Maxio accepts.
• Meter: Calculates usage from stream events.
• Segment: Groups usage by a string property, such as region or customer tier.

For a full explanation, see Streams, Meters, and Segments Explained.

Step 1: Configure Metering

Once Metering is activated, you can configure it for your site.

1. From Advanced Billing, go to Config > Settings > Metering.

   

2. Toggle on Metering.
3. Optional: Enter a Subscription Processing Grace Period to give Maxio extra time to receive usage data before closing a billing period.
4. Click Save Settings.

Step 2: Create an event stream

An event stream defines the structure of the usage events your system sends to Maxio.

1. Go to Metering > Streams.

   

2. Click Create Event Stream.
3. For Name, enter a descriptive name, such as API Usage Stream.

4. Review the API Handle.

   Maxio generates the API handle from the stream name and uses it in the events API endpoint.

5. In Description, enter optional context for your team.

6. Under Subscription Identifier, select one identifier type:

   • Subscription ID: Maxio’s internal numeric subscription ID.
   • Subscription Reference: Your external subscription reference ID.

   Select either Subscription ID or Subscription Reference, not both. All events sent to this stream must use the same identifier type you select.

7. Under Event Properties, click Add Property for each field your events include.
8. For each property, configure the following values:
   • Name: Enter the field name.
   • Used for Billing: Select Meter for values used in billing calculations (Integer or Float only), or Segment for values used to group usage (String, Integer, Float, Boolean, or Date).

   • Data Type: Select Int or String.

     Example setup:

     Property name	Used for	Data type
     api_calls	Meter	Int
     region	Segment	String
     customer_tier	Segment	String

9. Repeat for each property.

   The Event Example panel updates as you add properties.

10. Click Save.

If you already have an event format, click JSON Import, paste a sample event, review the detected fields, and click Add Properties.

For details about identifiers, data types, and JSON import, see Configure Metering.

Step 3: Create your first meter

A meter defines how Maxio calculates usage from stream events.

1. Open the stream you created.
2. Click the Meters tab.

3. Click Create Meter.

   

4. In Meter Name, enter a descriptive name, such as API Calls.
5. Select an Analysis Type:
   • Count — counts the total number of events
   • Count Unique — counts distinct values for a selected property
   • Sum — totals the values of a selected numeric property
   • Average — averages the values of a selected numeric property
   • Minimum — returns the lowest value for a selected numeric property
   • Maximum — returns the highest value for a selected numeric property
6. For Count Unique, Sum, Average, Minimum, and Maximum, select the property to aggregate.
7. If you select Count Unique or Sum, select the property to aggregate.
8. Under Segment, select an existing segment or click New Segment and choose a property to segment by.
9. Optional: Turn on Save Segment to make the segment reusable.
10. Click Save.

For help choosing an aggregation type, see Aggregation Types Explained.

Step 4: Send a test event

After the stream and meter are configured, send a test event that matches the stream schema.

1. Go to Metering > Streams and open the stream.
2. From the Stream details > Token Utilization, click the Copy icon, , to copy the stream URL (also known as the API endpoint URL) to the clipboard.

3. Send a POST request with a JSON payload that matches your stream schema.

   Include:

   • Your subscription identifier (matching the type selected on the stream)
   • The event properties you defined

A successful request returns a 2xx response.

Step 5: Confirm the event and meter result

After sending the event:

1. Go to Metering > Streams and open the stream.
2. Click the Events tab.
3. Confirm that the event appears.
4. Check the success rate stat to confirm no validation errors occurred.

If the event does not appear or displays as invalid, review Troubleshoot Metering Issues.

Step 6: Connect usage to billing

Once your stream and meter are working, connect the meter to a billing component in your Product Catalog.

Next steps: Design Your Catalog - Use Metering with Components