Segmented Aggregations - m3ter Documentation

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. This topic introduces an example usage-based pricing use case and explains how to create and work with Segmented Aggregations:

Example Use Case
Configuration for Example Use Case
Creating Segmented Aggregations
Pricing Plans with Segmented Aggregations
Reviewing Bills for Segmented Aggregation Pricing
Custom Descriptions for Segmented Aggregations
Using Copy or Cut and Paste to Create and Manage Segment Values
Using Wildcards or Defaults in Segmented Aggregations

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:

Data	Field	Category	Example Values
Candidate location	location	Where	China \| USA \| UK
Background check level	type	What	Standard \| Extended \| Complete
Number of checks performed	quantity	Measure	1

Aggregations

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

Tip: Only String Data Fields can be Segmented! That is: Who, What, and Where Data Fields. Numeric Data Fields, such as Measure, Cost, and Income cannot be segmented.

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:

Segments	location	type
Segment value 1	China	Standard
Segment value 2	China	Extended
Segment value 3	USA	Extended
Segment value 4	USA	Complete
Segment value 5	UK	Standard
Segment value 6	UK	Complete

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.

Note: Limit on Segmentation Fields? The maximum number of fields that can be used for segmentation is 5.

To create a Segmented Aggregation:

Select Metering>Aggregations. The Aggregations page opens.
In the Product drop-down, select the Product for which you want to create the new Segmented Aggregation.
Select Create aggregation. The Create page opens.
Under Aggregation details, enter a Name and Code for the new Aggregation:

Accounting product. Use the drop-down to select a Product. For accounting purposes, you can use this to link to a specific Product any usage line items on Bills that result from pricing a Plan using this Aggregation. (Optional)
- If you’ve also defined an Accounting product for a Pricing that uses this Aggregation, then the Pricing Accounting product takes precedence and is used.
- If no Accounting product is defined for a Pricing and you omit an Accounting product for the Aggregation, then the Product the Plan belongs to is used.

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.

Enter the Aggregation settings:

In this example:

We’ve selected to Sum the number of Candidate Hiring Checks.

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:

Tip: Creating Segmented Aggregations using Derived Fields? If you have added a Derived Field on the target Meter which is a string type, then this Derived Field will show as available to set up segment values for when creating an Aggregation. For example, if you’ve set up a Derived Field which concatenates two string Data Fields, this Derived Field will show as available under Segments to set up segment values for the Aggregation.

In the Segments panel, select the Meter fields you want to use to create segments. The panel adjust to add a first blank row for the selected Meter fields:

Enter segment values for the first row and then use the Add segment button to successively 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:

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.

Notes and Tips:

Pricing a Plan using this example Segmented Aggregation? See Pricing Plans Using Segmented Aggregations.
Aggregation metadata? If you scroll down the Aggregation details page, you can review Aggregation metadata. See Reviewing Aggregation Details.

If you want to edit an Aggregation’s details, select the Edit button, make your changes, and click Update.
If you want to remove an Aggregation, return to the Aggregations page and select the Delete button for the Aggregation:

A confirmation popup opens.

Select Yes to confirm the delete action.

Tip: Create Segmented Aggregation using API call? You can also use the Create Aggregation API call - see the Aggregation section of our API Reference documentation.

Pricing Plans with 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 do this, see Pricing Plans Using Segmented Aggregations.

Pricing Plans in conjunction with tiered pricing! Caution is required when using Segmented Aggregations in conjunction with a tiered pricing structure:

Suppose in the current example use case 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 segment and the bill amount will be $0.

Reviewing Bills for Segmented Aggregation Pricing

If you use Segmented Aggregations to price your Product Plans, then at billing one line item will be created per Aggregation segment value you’ve used for pricing and any default pricing you’ve used:

Each Bill line item shows a charge for a priced segment.
If you do not use a segment value for pricing, then no line item for this appears on the Bill.

To illustrate how Bills are generated when a segmented Aggregation is used for pricing, we’ll use the Hire Check segmented Aggregation for the Premium Data Checks Product created in the earlier section, submit some test usage data to an Account, and then generate a Bill. To generate and review Bills for Segmented Aggregation pricing:

Select Products>Premium Data Checks. The Product details page opens.

We’ll first create a Plan for the Product.

Create a Plan Template for the Product configured for monthly billing in US Dollars and then create the Premium Data Check Plan based on the template. See Creating Product Entities for more details.

Next, we’ll open the Hire Check Aggregation then use it to price the Premium Data Check Plan.

Open the Plan details page for the Premium Data Check Plan and then use the Hire Check Segmented Aggregation to configure pricing for each segment.

See Pricing Plans Using Segmented Aggregations.
For the current example, we’ve configured a flat-rate single tier pricing in US Dollars for each of the six segments defined for the Hire Check Aggregation as follows:

Type	Location	Unit Price
Complete	UK	30
Complete	USA	20
Extended	China	15
Extended	USA	12
Standard	China	10
Standard	UK	20

For each segment Pricing, we’ve entered a generic description to appear on Bill line items:

Create a test Account and attach the Premium Data Check Plan to it. We’ve created the Data Check Customer 1 Account and attached the Plan to it:

Next, we can submit some test usage data to the Account

Select Submit usage

On the Submit usage data modal, select Candidate Check for Step 1: Select a meter.
For Step 2: Define measurements and send, submit a single test usage data measurement for each of the six segments we priced for the Premium Data Check Plan, and all within the same month. The correct Meter and Account fields will be preselected. For example:
Type Location Quantity
Complete UK 27
Complete USA 42
Extended China 15
Extended USA 61
Standard China 18
Standard UK 56

Type	Location	Quantity
Complete	UK	27
Complete	USA	42
Extended	China	15
Extended	USA	61
Standard	China	18
Standard	UK	56

We now have a test usage data submission made against the Data Check Customer 1 Account for each of the segment values we priced the attached Product Plan for and we can generate a Bill for the month in which the submissions were made.

Select the Data Check Customer 1 Account Bills tab and Run billing for the month in which you made test usage data submissions. See Running Bills Manually.

When the Bill job has completed the newly generated Bill will appear on the Bills tab. Select Bill Reference text hotlink to open the Bill:

As expected the Bill contains six line items - one for each of the priced segment values defined for the Hire Check Segmented Aggregation which we used to price the Premium Data Check Plan attached to the Account.
However, the generic description we defined for each segment pricing fails to show us which particular segment value each line item applies to. You can reference the segment values in custom descriptions for segment pricing to ensure that when Bills are generated, the segment value the line item applies to can be distinguished.

Custom Descriptions for Segmented Aggregations

If you want to use custom descriptions for the line items on Bills generated when a segmented Aggregations has been used for pricing, you can use handlebar notation to reference segment values within the pricing description definition. For the example Bill we generated in the previous section, we can update each segment pricing description as follows:

If we recalculate the Bill this will resolve for line item Descriptions as:

Alternatively, if we use the following for each segment pricing description:

This will resolve on Bills as:

If you do not define a description on the pricing you configure for a Plan using a Segmented Aggregation, then a default description is used that includes any segment values: <Aggregation name> (<segment value 1>,<segment value 2>, <segment value 3>…) For the current example, the default description format resolves to:

Using Copy or 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 a spreadsheet application into the Segments values grid. Suppose in the above example, you want to set up six additional segment values that you’ve already set out in a spreadsheet:

Instead of adding these row-by-row, highlight and copy the segment value rows in your spreadsheet then select to Add segment in the Segments panel:

You can then paste the additional copied segment value rows directly into the Segments panel:

Using Wildcards or Defaults in Segmented Aggregations

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

Tip: Create Pricings for Wildcard Segments? For example of how to create pricings for segments that use wildcards using the Create Pricing API call, see the Creating Wildcard Pricings for Segments section of the Pricing Plans Using Segmented Aggregations topic.

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:

Segments	location	type
Segment value 1	China	Extended
Segment value 2	USA	Extended
Segment value 3	USA	Complete
Segment value 4	UK	Complete
Segment value 5	Any	Standard

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 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"}, {}]

As another example, suppose you want to create a segmented aggregation that has only a single segmented field and you want to create a single wildcard segment. In this case, you can use the same syntax. Here’s an example request payload to illustrate:

{
  "meterId": "b91e4ac1-bf9f-4e33-a676-63554108dxyz",
  "name": "Test Segmented Agg",
  "aggregation": "SUM",
  "rounding": "NONE",
  "quantityPerUnit": 1,
  "unit": "GB",
  "targetField": "quantity",
  "segmentedFields": ["service_id"],
  "segments": [
    {}
  ]
}

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:

Segments	location	type
Segment 1	Any	Standard
Segment 2	UK	Any
Segment 3	Any	Any

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).

​Example Use Case

​Configuration for Example Use Case

​Meter

​Aggregations

​Creating Segmented Aggregations

​Pricing Plans with Segmented Aggregations

​Reviewing Bills for Segmented Aggregation Pricing

​Custom Descriptions for Segmented Aggregations

​Using Copy or Cut and Paste to Create and Manage Segment Values

​Using Wildcards or Defaults in Segmented Aggregations

​Using Wildcards - An example

​Using Wildcards - API Calls

​Using Wildcards - Order of Evaluation

Example Use Case

Configuration for Example Use Case

Meter

Aggregations

Creating Segmented Aggregations

Pricing Plans with Segmented Aggregations

Reviewing Bills for Segmented Aggregation Pricing

Custom Descriptions for Segmented Aggregations

Using Copy or Cut and Paste to Create and Manage Segment Values

Using Wildcards or Defaults in Segmented Aggregations

Using Wildcards - An example

Using Wildcards - API Calls

Using Wildcards - Order of Evaluation