Aggregate Usage Lines

Aggregate Usage Lines are identical to regular Usage Lines except for one key difference. Aggregate Usage Lines have an additional required field called partnerAggregateQuantity that is absent from regular Usage Lines.

Use Aggregate Usage Lines when you want to give Partners a price based on the aggregate usage of all of their Companies. Typically, this would be used alongside a volume based rate plan, where there are price breaks at certain volume amounts.

Endpoints

Note that billingPeriod is a year-month, taking the format yyyy-MM.

POST /usage/aggregate-lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}
POST /usage/aggregate-lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}
GET  /usage/aggregate-lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}&summaryKey={summaryKey}

Aggregate Usage Line Object

{
    "summaryKey": "key",
    "summaryDisplayName": "name",
    "quantity": 1,
    "partnerAggregateQuantity": 100,
    "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
    "unitOfMeasurement": "unit"
}

Example

Let's assume usage pricing has been set up in the Pax8 system such that if users consume 0-99 units of usage, the cost is $1.00 per unit. Then, for users who use 100-999 units of usage, the cost is $0.90 per unit.

Next, let's assume some example Partner manages 3 Companies, and each of the Companies consumes 40 units of usage per month. In this case, the partnerAggregateQuantity would be 120, or the sum of the usage from all of their companies. If you send this 120 as the value for partnerAggregateQuantity when posting each individual Company level usage line, the Pax8 system will set the partner price on the usage line to $0.90 per unit, and the end retail price will be $1.00 per unit.

POST /usage/aggregate-lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}
[
    {
        "summaryKey": "companyId1",
        "summaryDisplayName": "companyName1",
        "quantity": 40,
        "partnerAggregateQuantity": 120,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]

[
    {
        "summaryKey": "companyId1",
        "summaryDisplayName": "companyName1",
        "quantity": 40,
        "partnerAggregateQuantity": 120,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]