# Aggregation Levels and the Account Hierarchy

This article describes the implications of tiered services in the context of Exivity's hierarchical account system.

## Tiered Rate Configurations and Owners

{% hint style="warning" %}
**Key point**

The parameters defining how a tiered service is to be charged, including such things as the bucket ranges and rates, are collectively termed a *Tier Configuration*
{% endhint %}

As with non-tiered service rates, Tier Configurations may have revisions such that they change over time (for example the prices for one year may be different to those of the previous year). However in the case of tiered services these revisions can only be changed on the boundary of a calendar month. 

This is because tiering is always applied to a monthly quantity derived from summing the instance quantities seen on each day and this requires consistency of the configuration for all days of the month.

Tier configurations can be *Global* or *Custom*. A tiered service must have one Global configuration and may have any number of Custom configurations.

The Global configuration is the default which will be used for calculating charges for all accounts that don't have a Custom tier configuration of their own. Thus by extension, Custom configurations are explicitly associated with a specific account. 

{% hint style="warning" %}
**Key point**

The account associated with a Custom configuration is termed the *Owner Account* of that configuration
{% endhint %}

A tiering configuration contains the following information:

| Item              | Description                                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Bucket ranges     | One or more ranges which collectively define how a monthly quantity is to be allocated to buckets                                                                        |
| Tiering type      | Whether Standard or Inherited tiering should be performed                                                                                                                |
| Owner ID          | The ID of the account associated with this tier configuration. Global configurations have an owner ID of `0`                                                             |
| Aggregation Level | The level of the account hierarchy (with `1` being the highest level) to which quantities should be summed before tiering is applied to the resulting aggregate quantity |

## The Aggregation Level

The aggregation level is the level of the account hierarchy at which tiering is applied to the quantity. For aggregation levels higher than the lowest level account, the quantity to be tiered will be the sum of all the quantities at lower levels. 

{% hint style="info" %}
When creating a custom tier configuration, the aggregation level must be at or below the level of the owner account.
{% endhint %}

### Aggregation with a simple 2-level account hierarchy

Consider a Standard tier configuration where the following bucket ranges and rates apply:

| Bucket | Range | Rate    |
| ------ | ----- | ------- |
| 1      | 0 +   | `10.00` |
| 2      | > 5   | `5.00`  |
| 3      | > 10  | `3.00`  |

The diagram below illustrates how tiering would be applied to a simple 2-level account hierarchy, where the aggregation level is set to level 1 (the highest level).

![Aggregation at level 1 of a 2-level account hierarchy](https://1141395848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPRZvuYYNyI3vz1mar1l4%2Fuploads%2FCLWW1OOikzj3opKcFviu%2Faggregation_in_2_level_report_01.PNG?alt=media\&token=6dc99c33-dd4d-455d-a347-5b646c62de15)

{% hint style="info" %}
In the above diagram the aggregation level is surrounded with an orange box and the total quantity of the lowest-level (Level 2) accounts is surrounded with a purple box.
{% endhint %}

It can be seen that the quantity consumed by the two child accounts`Level2A` and `Level2B` is summed (aggregated) to determine the quantity at the aggregation level account `Level1A`. 

It is this aggregated quantity that is allocated to the buckets (at the aggregation level) based on the ranges specified in the table above, thus with a total quantity of `40` the first two buckets are allocated `5` each and the rest is placed into Bucket 3.

Once this allocation has been done the bucket quantities for the lower level accounts `Level2A` and `Level2B` are calculated as a proportion of the quantities in the buckets for the `Level1A` parent account.

{% hint style="warning" %}
**Key point**

When the aggregation level is higher than the lowest level of the account hierarchy, the consumed quantities of the lowest level accounts are still the same but the quantities allocated to the buckets at the lowest level are different than if the aggregation level was at the lowest level.
{% endhint %}

The key point above is critical to a proper understanding of how tiered charges work in Exivity so let's review them once more in the context of the diagram above. 

With an aggregation level of 1, the quantities at level 2 are summed, the resulting total quantity is allocated to buckets at the aggregation level and then the buckets at level 2 are set proportionally to the quantities of the buckets at level 1. 

In the example illustrated above this leads to bucket quantities of `2.5`,`2.5` and `15` for each of the level 2 accounts because those level 2 accounts accounted for half the consumed quantity each thus each of the buckets for the level 2 is half the quantity of the same bucket at the level 1 account.

If the tier configuration specified an aggregation level of 2, the quantities of each level 2 account would have been allocated to buckets locally to that account with no consideration of any other account, such that both level 2 accounts would have had bucket quantities of `5`,`5` and `10` as shown below.

![Aggregation at level 2 of a 2-level account hierarchy](https://1141395848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPRZvuYYNyI3vz1mar1l4%2Fuploads%2FiQNLlZJ5W632GcwVK5JB%2Faggregation_in_2_level_report_02.PNG?alt=media\&token=92e4653b-54d2-46af-b03e-ca00bbe04da5)

{% hint style="info" %}
In the above diagram the aggregation level is surrounded with an orange box and the individual quantities of the lowest-level (level 2) accounts are surrounded with purple boxes.

With the aggregation level set to 2, each of the purple boxes would therefore have been tiered independently.
{% endhint %}

Note that when the aggregation is at level 2, no calculations or charges are explicitly performed for level 1. However a report at level 1 in Exivity would still show the charges as the sum of those at the lower levels.

### Aggregation with multiple top-level accounts

Having discussed the 'parent and two child accounts' scenario above we can now extend that example such that we have more than one parent account.

The following diagram illustrates how tiering is performed in a situation where there are two level 1 accounts, each of which has two child accounts. 

![Aggregation at level 1 of a 2-level account hierarchy with multiple level 1 accounts](https://1141395848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPRZvuYYNyI3vz1mar1l4%2Fuploads%2Fc1jyKRcLOmZTlcMIwIKQ%2Faggregation_in_2_level_report_03.PNG?alt=media\&token=fbc282b5-985a-4f08-aa4d-52ddf9fdf430)

As before, the aggregation level is boxed in orange and the quantities to which tiering is applied are boxed in purple. 

The manner in which tiering is applied is no different to that described previously. The main difference in the illustration above is simply that each of the level 1 accounts had tiering applied to them independently.

{% hint style="warning" %}
**Key point**

When there are multiple accounts at the aggregation level, tiering is applied independently to each of them and the resulting bucket allocations for each are further distributed down across their child accounts.
{% endhint %}

Looking at the diagram above it can be seen that there are actually two 'subtrees' of accounts in the scenario. The root of each of these trees is a Level 1 account and the children of that account are evaluated in order to perform the tiering at the top level.

{% hint style="warning" %}
Key point

The bucket allocations (and the resulting charge) for each of the child accounts of `Level1B` are different to one another. This is because the *Total Monthly Quantity* of each child account has been used to determine the percentage of the quantity at the aggregation level that the child represents. 

Thus each bucket of each child gets the same percentage allocated to it based on the tiered quantities at the aggregation level.
{% endhint %}

### Mixed level aggregations

Developing further the scenario previously outlined, let's consider there are two configurations:  the Standard configuration in the beginning of this article and another Standard configuration, which is applied at a level two account.

The first Standard tier configuration:

| Bucket | Range | Rate    |
| ------ | ----- | ------- |
| 1      | 0 +   | `10.00` |
| 2      | > 5   | `5.00`  |
| 3      | > 10  | `3.00`  |

The second Standard tier configuration:

| Bucket | Range | Rate    |
| ------ | ----- | ------- |
| 1      | 0 +   | `20.00` |
| 2      | > 10  | `10.00` |
| 3      | > 15  | `5.00`  |

![Mixed level aggregation](https://1141395848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPRZvuYYNyI3vz1mar1l4%2Fuploads%2FBCPhEa4RCbkwcZvNOoYl%2Fmixed%20level%20aggregations.png?alt=media\&token=473d3b93-9f04-419e-9ed9-0ed8e9b87427)

{% hint style="info" %}
In the diagram above, the orange box uses the first Standard Configuration, while the purple outlined account has been configured to use the second Standard config.
{% endhint %}

As we can observe, it is possible for multiple configurations to co-exist: the `Level1C` account distributes its quantities in buckets by the rules of the second configuration.