Pricing Plans Using Segmented Aggregations

If you want to use a Segmented Aggregation to price up one of your Product Plans, the Pricing Editor is designed to help you quickly price the segments you’ve defined for the Aggregation. This topic explains how to use the Segmented Aggregation described in the Segmented Aggregations topic to price a Plan:

If you’ve set up a Compound Aggregation that references Segmented Aggregations, you can also use this to Price Plans:

Pricing with Compound Aggregations Based on Segmented Aggregations

Notes & Warnings:

Preparing to price Plans and Plan Templates using Segmented Aggregations! We strongly recommend that before you attempt to price up Product Plans or Plan Templates using a Segmented Aggregation, you first review the Pricing Plans and Plan Templates topic.
Pricing Plans in conjunction with tiered pricing! Caution is required when using Segmented Aggregations in conjunction with a tiered pricing structure:
- Suppose you offer a service to perform background checks for companies on job application candidates. 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.

Creating Segmented Pricings for Plans in the Console

When you use a Segmented Aggregation to price one of your Product Plans, you must create a separate pricing for each segment value you’ve defined. You can do this using the Console’s Pricing Editor. To price a Plan using a Segmented Aggregation:

Select Pricing>Pricing editor. The Pricing editor opens.
In the Product drop-down, select the Product for which you want to add a Plan to price up.
Select Add Plans. A Select Plans popup appears and lists the Plans created for the Product.
Select the Plan or Plans you want to price and select Confirm. You are returned to the Pricing page where the selected Plan is shown. A warning states that no pricing has yet been configured for the Plan.
Select Add aggregations. A Select Aggregations popup appears listing the Aggregations created for the Product.

Notes: Selecting Aggregations for Pricing.

Available Aggregations: Only those Aggregations belonging to the same Product as the Plan and any Global Aggregations in your Organization are shown for selection in the popup.
Duplicating Aggregations: You cannot add the same Aggregation more than once for pricing a Plan and any Aggregations you’ve already added will no longer be available for selection in the popup.

Select the Segmented Aggregation you want to use to price the Plan and select Confirm. The popup closes, you are returned to the Pricing Editor where the Segmented Aggregation is shown ready for pricing. A warning states that no active pricing is yet configured.
Select Edit segmented pricing. The Pricing>Segments page opens:

An Aggregation details and Plan Details panel are shown.
A Segmented pricing grid allows you to create the pricing for each segment value you have configured for the Segmented Aggregation.

Tip: Filter Grid? You can use the filter fields at the head of each segment field column to filter the grid.

To configure a price for a segment value, select Create plan pricing. A Pricing page opens for the segment value, which mimics the Pricing page for a simple Aggregation that is not segmented - you can use either a Pricing Wizard workflow or choose to use the Advanced Pricing configuration options. See Creating a Pricing for a Plan for more guidance.
Use the Pricing page to configure the precise pricing you want to apply to the segment value and select Create Pricing:

Above shows the first two for China location under Segmented pricing.
Repeat Steps 8 and 9 to create the pricing for all segment values:

When you return to the Pricing Editor, you’ll see the pricing you’ve configured using the Segmented Aggregation has been saved - in this example 6/6 (6 of 6) segments are now priced:

Reviewing Segmented Priced Plan Details

If you open the Plan details page of a Plan you’ve priced using a Segmented Aggregation, under Pricing you can review and manage the each segment’s pricing. For the current example:

For the current example, we’ll select the type and location for the segment pricing to review:

Note that you can Edit segmented pricing from this panel.
When you’ve selected a specific segment pricing, you can then view any historic or future pricing for that segment applied to the Plan using the paging arrows at the bottom of the Pricing card:

Lastly, you can select the View pricing schedule hotlink to open the Pricing schedule for the selected segment pricing applied to the Plan:

See Viewing Pricing Schedule for more details.

Using API Call to Create a Segmented Pricing

Instead of using the Console Pricing Editor, you can use the Create Pricing API call to create a pricing on a Plan using a Segmented Aggregation. When you do this, you can create a separate pricing for each of the segment values defined for the Segmented Aggregation. You can also create a pricing using wildcards to satisfy cases where you only want a specific pricing to apply to some of the segment values and apply a common pricing to any of the other segment values. This section uses the example of a Segmented Aggregation defined in the main Segmented Aggregations topic to show how to:

Create a pricing for a specific segment value.
Create wildcard pricings to apply to segment values for which no specific pricing has been created

API Call - Creating a Pricing for a Segment

We’ll adapt the previous example to imagine we want to price a Plan using a Segmented Aggregation called Hiring Check 4:

The Hiring Check 4 Segmented Aggregation defines three segment values using Location and Type fields:

If we select to Edit segmented pricing, Pricing>Segments page opens. Under Segmented pricing, the Pricing Grid shows that no active pricings have been configured for any of the three segment values:

To create a segment value pricing:

Make a POST Create Pricing call to create a pricing for the Location = China/Type = Standard segment value:

Here’s the request body JSON:

{

  "planId": "12f2e595-d758-4d68-a492-d923bbxxxxxx",
  "aggregationId": "2a6db6df-26de-481e-8974-e1a43fxxxxxx",
  "segment": {
    "location": "China",
    "type": "Standard"
  },
  "cumulative": true,
  "tiersSpanPlan": false,
  "pricingBands": [
    {
      "lowerLimit": 0,
      "fixedPrice": 0,
      "unitPrice": 0.25

    }
  ],

  "startDate": "2023-11-01T14:15:22Z",
  "endDate": "2024-11-01T14:15:22Z",
  "minimumSpend": 0,
  "minimumSpendDescription": ""

}

Note that:

The planId parameter is required.
The aggregationId of the Segmented Aggregation is a required request parameter for each segment pricing you create.
Use the segment request parameter to specify which segment defined for the Segmented Aggregation you want the pricing to apply to.
Use the pricingBands request parameter to define the pricing - in this example, a single tier pricing has been defined.

If the segment pricing has been created successfully, you’ll receive a 200 response and a response body similar to this:

Note that:

The pricing id is given.
Each pricing band id is given.

If we return to Pricing>Segments and refresh the page, we can check that the Segmented pricing grid is now showing for the specified segment value:

API Call - Creating Wildcard Pricings for Segments

If you’ve created a Segmented Aggregation and defined multiple segment values, you might have a pricing use case that requires only some of those segment values to have their own specific pricing defined and for the remainder of the segments to be priced together using a common or default pricing. You can do this by using wildcard values for some or all of the fields used to define segments. This section illustrates with two example how to create such wildcard pricings for your Segmented Aggregations using the Create Pricing API call.

Creating Double-Wildcard Default Segment Pricing

Suppose the pricing requirements for the current example of a three-value Segmented Aggregation is that for one segment value - Location = China/Type = Standard - a specific pricing will apply but for the remaining two segment values - Location = USA/Type = Complete and Location = UK/Type = Extended - a common pricing will apply. To implement this, you’ll first have to define a wildcard segment value for the Segmented Aggregation:

In the Console, open the Edit page for the Hiring Check 4 Aggregation and select Add default segment:

Select Update Aggregation.
Return to the Segmented pricing grid for the Segmented Aggregation - we can see that this double-wildcard default segment value has no pricing yet created for it:

We can now create a pricing for this double-wildcard default segment. This pricing will then be applied to any usage data submitted for any undefined segment values. To create a double-wildcard segment value pricing:

Make a POST Create Pricing call:

Here’s the request body JSON:

{

  "planId": "12f2e595-d758-4d68-a492-d923bb1xxxxx",
  "aggregationId": "2a6db6df-26de-481e-8974-e1a43f12xxxx",
  "segment": {},
  "cumulative": true,
  "tiersSpanPlan": false,
  "pricingBands": [
    {
      "lowerLimit": 0,
      "fixedPrice": 0,
      "unitPrice": 0.50

    }
  ],

  "startDate": "2023-11-01T14:15:22Z",
  "endDate": "2024-11-01T14:15:22Z",
  "minimumSpend": 0,
  "minimumSpendDescription": ""

}

Note that for the segment request parameter we leave this empty and omit any use of a "location" value or "type" value to create a double-wildcard pricing.

If we return to Pricing>Segments and refresh the page, we can check that the Segmented pricing grid is now showing for the wildcard segment value:

With this double-wildcard default pricing created, any usage submitted for Location/Type Data Fields on our usage Meter and which do not have a corresponding segment defined for the Hire Check 4 Segmented Aggregation will have this pricing applied for billing purposes.

Important! Segments added to the Aggregation and which do not have Pricing created for them yet, DO NOT have the default segment pricing applied. In the current example, if we now want the default segment pricing to be applied to usage data submitted for either Location = USA/Type = Complete or Location = UK/Type = Extended, we first have to update the Hire Check 4 Segmented Aggregation and delete them from the Aggregation.

Creating Single-Wildcard Segment Pricing

Lastly, you might want to create a pricing for a Segmented Aggregation that uses a single wildcard. In the current Example, suppose we define a segment value on Hiring Check 4 for Location = Germany/Type = Any, since we want to apply the same pricing to any checks made for candidates located in Germany and regardless of the Type of check performed:

Select Update Aggregation.
Return to the Segmented Pricing grid for the Segmented Aggregation - we can see that this single-wildcard segment value has no pricing yet created for it:

We can now create a pricing for this single-wildcard pricing. To create a single-wildcard segment value pricing:

Make a POST Create Pricing call:

Here’s the request body JSON:

{

  "planId": "12f2e595-d758-4d68-a492-d923bb174981",
  "aggregationId": "2a6db6df-26de-481e-8974-e1a43f121719",
  "segment": {
    "location": "Germany"
  },
  "cumulative": true,
  "tiersSpanPlan": false,
  "pricingBands": [
    {
      "lowerLimit": 0,
      "fixedPrice": 0,
      "unitPrice": 0.75

    }
  ],

  "startDate": "2023-11-01T14:15:22Z",
  "endDate": "2024-11-01T14:15:22Z",
  "minimumSpend": 0,
  "minimumSpendDescription": ""

}

Note that for the segment request parameter, we use a “location” value and omit any "type" to create a single-wildcard pricing.

If we return to Pricing>Segments and refresh the page, we can check that the Segmented pricing grid is now showing for the wildcard segment value:

With this single-wildcard pricing created, any usage for Location = Germany, whether of Type = Standard, Type = Complete, or Type = Extended, will be charged according to this pricing.

Tip: Using Wildcards for Segment Values - Evaluation Order? If you use a mix of specific segment values and wildcard segment values, you might be wondering in what order evaluation occurs when usage data is ingested for different segment values. For details, see Using Wildcards - Order of Evaluation.

Pricing with Compound Aggregations Based on Segmented Aggregations

You cannot define segments directly for a Compound Aggregation. However, if you’ve created a Compound Aggregation that references one or more Segmented Aggregations, you can also use the Compound Aggregation to price a Plan by segments defined for the Segmented Aggregations:

The Compound Aggregation does not inherit any of the pricings for segments you might have configured when using the referenced Segmented Aggregations to price Plans.
The segments set up on the referenced Segmented Aggregations are available to the Compound Aggregation to price a Plan by:
- If only one Segmented Aggregation is referenced, then all of the segments are available for pricing using the Compound Aggregation.
- If two or more Segmented Aggregations are referenced, then the segments available for pricing are restricted to those segments that are defined in common or intersect across any of the referenced Segmented Aggregations - see below Compound Aggregations - Segments Available.

To price with Compound Aggregation based on Segmented Aggregations:

Select Pricing>Pricing Editor. The Pricing page opens.
In the Product drop-down, select the Product for which you want to add a Plan to price up.
Select Add Plans. A Select Plans popup appears and lists the Plans created for the Product.
Select the Plan or Plans you want to price and select Confirm. You are returned to the Pricing page where the selected Plan is shown. A warning states that no pricing has yet been configured for the Plan.
Select Add compound aggregations. A Select Compound Aggregations popup appears listing the Aggregations created for the Product.
Select the Compound Aggregation based on Segmented Aggregations you want to use to price the Plan and select Confirm. The popup closes, you are returned to the Pricing Editor, and the Segmented Aggregation is shown ready for pricing. A warning states that no active pricing is yet configured for any of the available segments:

Select Edit segmented pricing. The Pricing>Segments page opens:

An Aggregation details and Plan Details panel are shown.
Under Segmented pricing, a grid allows you to create the pricing for each available segment configured for the referenced Segmented Aggregations:

In this example, Hiring Check Compound1 references a single Segmented Aggregation - Hiring Check - which has six segments defined and therefore there are 6 segments available to price, but we’ve chosen to price only 4/6 (4 of 6) segments:

Compound Aggregations - Segments Available

The Segments available for pricing using a Compound Aggregation depends on how many Segmented Aggregations are referenced:

If a single Segmented Aggregation is referenced, then all segments defined are available.
If two or more are referenced, then only those segments defined in common or which intersect across the referenced Segmented Aggregations are available.

For example, suppose we’ve set up Hiring Check 1 Aggregation and defined the following segments on it for "location" and "type" fields:

{"location" : "China", "type" : "Extended"}

{"location" : "China", "type" : "Complete"}

{"location" : "USA", "type" : "Extended"}

{"location" : "USA", "type" : "Standard"}

{"location" : "UK", "type" : "Standard"}

{"location" : "UK", "type" : "Complete"}

We’ve then set up a second Hiring Check 2 Aggregation and defined the following segments on it for "location" and "type" fields:

{"location" : "China", "type" : "Standard"}

{"location" : "China", "type" : "Complete"}

{"location" : "USA", "type" : "Complete"}

{"location" : "USA", "type" : "Standard"}

{"location" : "UK", "type" : "Extended"}

{"location" : "UK", "type" : "Complete"}

If we now create a Compound Aggregation - Hiring Check Compound - that references both Hiring Check 1 and Hiring Check 2, then only the following three segments will be available to Hiring Check Compound:

{"location" : "China", "type" : "Complete"}

{"location" : "USA", "type" : "Standard"}

{"location" : "UK", "type" : "Complete"}

​Creating Segmented Pricings for Plans in the Console

​Reviewing Segmented Priced Plan Details

​Using API Call to Create a Segmented Pricing

​API Call - Creating a Pricing for a Segment

​API Call - Creating Wildcard Pricings for Segments

​Creating Double-Wildcard Default Segment Pricing

​Creating Single-Wildcard Segment Pricing

​Pricing with Compound Aggregations Based on Segmented Aggregations

​Compound Aggregations - Segments Available

Creating Segmented Pricings for Plans in the Console

Reviewing Segmented Priced Plan Details

Using API Call to Create a Segmented Pricing

API Call - Creating a Pricing for a Segment

API Call - Creating Wildcard Pricings for Segments

Creating Double-Wildcard Default Segment Pricing

Creating Single-Wildcard Segment Pricing

Pricing with Compound Aggregations Based on Segmented Aggregations

Compound Aggregations - Segments Available