• Home
/
• Explore m3ter Documentation
/
• Pricing Metrics: Aggregations

Segmented Aggregations

Segmented Aggregations allow you to segment the usage data collected by a single Meter. This capability is very useful for implementing some pricing and billing use cases.

Example Use Case

Suppose you offer a service to companies to perform background checks on employee candidates to support their hiring process. Pricing for this service will vary by candidate location and the level of check done. The service is offered for candidate locations across three countries and you can perform three levels of background check for each location: Standard, Extended, or Complete. If you want to price differently for each possible combination of check for Country/Level, this would mean having to set up multiple Meters/Aggregations to support usage-pricing for all possible combinations. This then places the burden of deciding which Meter to use for pricing on you when sending customer usage data into the m3ter platform. For such cases, you can use Segmented Aggregations on the same Meter usage data, which means you can always send us data for the same Meter and allows a different pricing to be created for each segment.

Configuration for Example Use Case

Here's the configuration for the example.

Meter

Create and configure a single Meter with three Data Fields:

Aggregations

First, you can define which Meter Data Fields are part of the segmented Aggregation - for the current example, these are location and type.

Second, you can then define different segmented values for the Aggregation, where for each value you want to assign a specific pricing. For the current example, let's suppose we want to set up six segment values:

Pricing Using Segmented Aggregations

When pricing Plans you can define a pricing for each segmented value set up for an Aggregation. For more details on how to, see Pricing Plans Using Segmented Aggregations.

Using in Conjunction with Tiered Pricing

Some caution is required when using Segmented Aggregations in conjunction with a tiered pricing structure.

Suppose in the current example you want to offer 50 free background checks to your customers per billing period and then charge $50 per 100 checks made after the first 50 free per billing period. If you had priced using a non-segmented Aggregation and a customer consumes 150 checks in total during a billing period, then the bill would amount to $50. If however you use a Segmented Aggregation and your customer again consumes a total of 150 checks but across 3 segmented values and at 50 checks for each value, then the 50 free tier is applied separately to each and the bill amount will be $0.

Billing for Segmented Aggregations

If you use Segmented Aggregations to price your Product Plans, then at billing one line item would be created per Aggregation segment value you've used for pricing and any default pricing you've used. Each of these Bill line items would contain usage data matching the defined segment. If you've not used a particular Aggregation segment value for pricing, then a line item for this does not appear in the Bill.

Creating Segmented Aggregations

This section explains how to create a Segmented Aggregation for the example use case described in the earlier section of this topic. It's assumed that a Meter with the required three Data Fields has been set up.

To create a Segmented Aggregation:

1. Select Usage>Aggregations. The Aggregations page opens.

2. In the Product drop-down, select the Product for which you want to create the new Segmented Aggregation.

3. Select Create Aggregation. The Create page opens.

4. Under Aggregation Details, enter a Name and Code for the new Aggregation:

5. Under Meter Settings, select the Meter previously created for the example and with the required Data Fields: Location, Type, and Quantity:

In this example:

• Our Meter set up earlier is called Candidate Check.

• We've selected quantity as the Target Field.

6. Enter the Aggregation Settings:

In this example:

• We've selected to Count the number of Candidate Hiring Checks.

7. Open the Segments panel:

• Because the Candidate Check Meter has two Data Fields of the category that can be segmented - a Location>Where and a Type>What field - the Segments panel is loaded with these:

8. In the Segments panel, select the Meter fields you want to use to create segments, and then add the required segments you want to price by. For the current example, we've added six segment values using the Location/Type Meter fields:

9. Select Create Aggregation. The Aggregation Details page opens:

When you come to price up your Product Plans in the Pricing Editor, the new Segmented Aggregation will be available for selection. See Pricing Plans and Plan Templates where an example of how to price a Plan using this example Segmented Aggregation is given at Pricing Plans Using Segmented Aggregations.

10. If you want to edit an Aggregation's details, select the Edit button, make your changes, and click Update.

11. If you want to remove an Aggregation, return to the Aggregations page and select the Delete button for the Aggregation:

A confirmation popup opens.

12. Select Yes to confirm the delete action.

Tip: Using Copy/Cut and Paste to Create and Manage Segment Values

If you have a longer list of segment values to set up and manage for an Aggregation, you can copy/cut and paste values from and into the Segments values grid. Suppose in the above example, you want to set up additional segment values. Instead of adding these row-by-row, you can highlight and copy the existing six rows:

Then paste these copied values below:

And edit as required:

Using Wildcards or Defaults in Segmented Aggregations

You can use wildcards or defaults when setting up a Segmented Aggregation:

• Using Wildcards - An example

• Using Wildcards - API Calls

• Using Wildcards - Order of Evaluation

Using Wildcards - An example

To illustrate, we can adapt the current example use case. Suppose, instead of wanting to charge a different rate for a Standard checks by Country, you want to charge the same amount as a default for a Standard level of candidate background check regardless of country of location. The schema for the segment values will now look like this:

Using this schema, we can set up a second Aggregation - called Hire Check 2 (and see above) - that is segmented using the location and type fields in the following way for the required Extended or Complete level:

To set up the default for any Standard check level, first select Add default segment. A new row is added with (Any) shown for both the Location and Type. You can now edit the Type for Standard and leave Location as (Any):

We can now use Hiring Check 2 in the Pricing Editor to price up Plans and define a charge - see Pricing Plans Using Segmented Aggregations - for Standard checks for candidates in any location:

Using Wildcards - API Calls

If you use a Create Aggregation API call to set up a Segmented Aggregation, you can use wildcards when defining segments using the "segments" request schema parameter. For instance, if we take the example from the previous section, we can use this line in the request body of the call to define the five segment values:

"segments": [{"location" : "China", "type" : "Extended"}, {"location" : "USA", "type" : "Extended"},{"location" : "USA", "type" : "Complete"},{"location" : "UK", "type" : "Complete"}, {"type" : "Standard"}]

Note that for the last segment defined, where we want a wildcard for "location" value, we simply omit this field and only define a value for the "type".

Similarly, if we had wanted to define a double-wildcard segment for the Location/Type segmented fields, we can omit a specific value for both:

"segments": [{"location" : "China", "type" : "Extended"}, {"location" : "USA", "type" : "Extended"},{"location" : "USA", "type" : "Complete"},{"location" : "UK", "type" : "Complete"}, {}]

Using Wildcards - Order of Evaluation

If you are using wildcards in your Segmented Aggregations, you should be clear about the order of evaluation. To understand this, we can develop the example use case for a third - Hiring Check 3 - that uses the same Candidate Check Meter for source usage data and we use the following schema for segmented values on this Aggregation using the location and type Data Fields with wildcards:

Again, we can configure the segment values when we create Hiring Check 3 to follow this schema using wildcards:

Now, suppose we have an item of usage data collected by the Candidate Check Meter as follows:

• location = UK

• type = Standard

If we've used Hiring Check 3 to price a Plan for a Product, how will the end customer Account with that Plan attached be charged for this usage data; under which segment value pricing will the Account be charged? This depends on the order in which you've defined the segmented fields:

• In this example, where the order of defined segmented fields is location then type, the data would be matched preferentially to the location value, and would be charged according to the pricing configured for the UK/(Any) segment value.

• If, however, we'd defined the segmented fields for the Aggregation in the order of type then location, the data would be matched preferentially to the type value, and would be charged according to the pricing configured for the Standard/(Any) segment value.

You can change the order of segmented fields in the configuration table for an Aggregation by deselecting the Segmented fields checkboxes and then reselecting them in order for the evaluation order you want. The columns in the table will be ordered accordingly:

Lastly, there might be usage data items collected that do not have a match for either location or type fields with segment values configured, such as in this case:

• location = USA

• type = Complete

These would be evaluated for charging against the Account on the basis of our third, "double wildcard", segment value: (Any)/(Any).

Next: Calculation Syntax and Supported Functions/Operators

Additional Support