Guides

Aggregate Usage Lines

Suggest Edits

Overview

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

Save Usage Lines with an Aggregate Partner Quantity

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

Our API also offers an optional feature that enables Vendors to store a unique identifier on a subscription during provisioning. The externalProvisionerSubscriptionId serves as a reference point for future interactions with the object, making it easy to locate and modify without complex mappings.

The Aggregate Usage Line Object

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

Additional Information

Pax8 Partners may have many usage lines for a subscription, and those lines could be for many different companies, so we offer a grouping mechanism called summaryKey to aggregate usage lines into summaries.
The most common grouping pattern - and the pattern recommended by Pax8 - is to group usage lines by company.

  • Usage Lines are grouped by a summaryKey for a Subscription. Every usage line that shares an identical summaryKey will grouped together for display purposes.
    • The key must be a unique identifier, most often a company id.
  • The summaryDisplayName is used in the Pax8 UI, this is the label that partners will see on their invoices and throughout the month when monitoring their usage. It gives a friendly name to the group defined by a summaryKey.
    • If you are grouping usage by Company ID, then Company name is a good candidate for summaryDisplayName

NOTE: both summaryKey and summaryDisplayName have a 255 character limit.

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.

When reporting usage to Pax8 for the company, Amazing Company, you would send us the following request:

curl --request POST \
     --url 'https://api.pax8.com/v2/usage/aggregate-lines?subscriptionId=ef29b3e0-2474-4c27-9405-9a8520ffc72c&billingPeriod=2025-08' \
     --header 'accept: */*' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "summaryKey": "12345",
    "summaryDisplayName": "Amazing Company",
    "quantity": 40,
    "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
    "unitOfMeasurement": "Unit",
    "partnerAggregateQuantity": 120
  }
]
'
'

And you would receive the following response:

[
    {
        "summaryKey": "12345",
        "summaryDisplayName": "Amazing Company",
        "quantity": 40,
        "partnerAggregateQuantity": 120,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "Unit"
    }
]

Updated 9 days ago