• Home
/
• Working in m3ter - User Guides
/
• Pricing Metrics: Aggregations

Compound Aggregations

Compound Aggregations allow you to derive numerical measures from usage data by applying a calculation to one or more simple Aggregations. The calculation can also reference Custom Fields. You can then use these calculated measures as pricing metrics to set up usage-based pricing Plans for your Products. In this way, Compound Aggregations can help you to implement a wide range of pricing use cases for your Products.

This topic starts off by explaining the difference between Product-specific and Global Compound Aggregations:

• Product vs. Global Compound Aggregations

The topic then illustrates the value of using Compound Aggregations with a usage-based pricing example, and explains how to create a Compound Aggregation to apply a calculation to simple Aggregations to satisfy the example pricing use case:

• Example Use Case

• Creating a Compound Aggregation

The final section provides helpful guidance on rules that apply to Compound Aggregations for referencing simple Aggregation values and the corresponding syntax you must use:

• Compound Aggregations - Referencing Values and Fields and Supported Syntax

Product vs. Global Compound Aggregations

You can create Product Compound Aggregations, which belong to a specific Product, or Global Compound Aggregations, which are not tied to a specific Product:

• You can use a Product Compound Aggregation to price only those Plans that belong to the same Product.

• You can use a Global Compound Aggregation to price Plans belonging to any Product.

Example Use Case

Suppose you provide a service which allows your customers to develop and run software applications and host these applications on your service. You intend to charge customers for this application build-and-host service by total number of requests made to all of their applications being hosted in any given billing period. However, you want to offer customers a sign-up bonus for their first year of using your service, where the first 100 requests made to an application they host with you are free for each billing period - for example, if a customer has 3 applications hosted with you during the first billing period, they are due 300 free requests for the first Bill.

To set things up in m3ter to implement usage-based pricing for this type of case, you can use a Compound Aggregation:

• First, create and configure a Meter which will record the number of applications hosted. You can send an event into m3ter each time one of your customers creates and loads an application into your service. Use this Meter field to create a simple Aggregation to give a Maximum value measure for hosted applications. Give this simple Aggregation a code of: unique_apps. (Note that for the example, we suppose that under the terms of the sign-up bonus if a customer reaches 5 applications in any given billing period, they are granted 500 free requests even if 2 of those applications are disabled before the end of the billing period.)

• Second, create and configure a Meter to record the number of requests made by applications. You can then create a second simple Aggregation to Sum this data. Give this simple Aggregation a Code of: num_requests.

• Third, create a Compound Aggregation that applies a calculation to the two simple Aggregations to give a number for chargeable requests:

Math.max(0, aggregation.num_requests - (aggregation.unique_apps * 100))

When you come to price up your Product Plans, you can now use this Compound Aggregation.

Creating a Compound Aggregation

This section explains how to create a new Product Compound Aggregation for the example use case outlined above, and assumes the two simple Aggregations used have already been created for the same Product.

To create a Compound Aggregation:

1. Select Metering>Compound Aggregations. The Compound Aggregations page opens.

2. In the Product drop-down, select the Product for which you want to create the new Compound Aggregation. The Compound Aggregations page adjusts and lists:

• Any existing Compound Aggregations created for the selected Product.

• Any Global Compound Aggregations, which are clearly labeled.

3. Select Create Compound Aggregation. The Compound Aggregations>Create page opens.

4. Enter the Compound Aggregation Details:

• Name. For this example, enter a descriptive name, such as Requests minus free.

• Code. Unique identifier. For this example, we've used requests_minus_free:

5. Enter the Compound Aggregation Settings:

• Calculation. First select Advanced if you want to enter a specific calculation. The form adjusts to show a text entry box. Enter the expression for the required calculation referencing simple Aggregations:

Math.max(0, aggregation.num_requests - (aggregation.unique_apps * 100))

• Unit. For this example, enter Requests. This will be used as a label for billing to indicate to your customers what they are being charged for.

• Quantity per Unit. Enter the quantity by which you want to charge for the measured value. For example, if you want to charge your customers on a per-500 units used basis, enter 500. For the current example, enter 1.

• Rounding. Specifies how you want m3ter to deal with non-integer, that is fractional number, Aggregation values. See Reviewing Aggregation Options for example. Four options:

  • None. Default

  • Down

  • Up

  • Nearest. Rounds up to the nearest half: 5.1 is rounded to 5; 5.5 is rounded to 6.

    • Note: Also used in conjunction with Quantity per unit setting. Rounds the number of units after the Quantity per unit has been applied. See Reviewing Aggregation Options for example.

• Evaluate Null Aggregations. Optional setting - enable this if you want to allow null values from the simple Aggregations referenced in the Compound Aggregation to be passed in. Simple Aggregations based on Meter Target Fields where no usage data is available will have null values. Default is to have this disabled:

6. Add any required Custom Fields to the Compound Aggregation. For more on Custom Fields, see Adding and Editing Custom Fields. We strongly recommend reviewing Working with Custom Fields before you create and use Custom Fields.

7. Select Create Compound Aggregation. The Compound Aggregation Details page opens:

Any new Compound Aggregations you've created become immediately available for pricing up your Product Plans. See Pricing Plans and Plan Templates.

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

9. If you want to remove a Compound Aggregation, return to the Compound Aggregations page and select the Delete button for the Compound Aggregation:

A confirmation popup opens.

10. Select Yes to confirm the delete action.

Compound Aggregations - Referencing Values and Fields and Supported Syntax

This section explains the syntax for referencing simple Aggregation values and Custom Fields in your Compound Aggregation calculations.

Referencing Simple Aggregation Values

You can reference the resultant values of simple Aggregations in a Compound Aggregation calculation using a simple Aggregation's Code. The general format is:

aggregation.<aggregationCode>

The simple Aggregations you can reference when you create a Product-specific Compound Aggregation or a Global Compound Aggregation are the same:

• The calculation can reference all simple Aggregations – any Product-specific and any Global simple Aggregations.

Referencing Segmented Aggregation Values

You can also reference Segmented Aggregations in a Compound Aggregation. The segments defined for the referenced Segmented Aggregations that are made available for the Compound Aggregation depends on whether it references one or multiple Segmented Aggregations. For details with an example, see Compound Aggregations - Segments Available.

Compound Aggregations - Referencing Custom Fields

You can reference the default values for Custom Fields - those defined at Organization level - in your Compound Aggregation calculations:

• organization.<fieldName>

• meter.<fieldName>

• product.<fieldName>

• account.<fieldName>

• accountPlan.<fieldName>

• plan.<fieldName>

• planTemplate.<fieldName>

Next: Compound Aggregations - Examples and Syntax

Additional Support