Usage Line Grouping Examples

Suggest Edits

Below are some examples of methodologies for grouping usage lines together into usage summaries

Group by Company

This is the grouping pattern recommended by Pax8 for the vast majority of our Vendors.

Below is an example grouping scenario for a Pax8 Partner that has 2 Companies under their account.

  • Company A uses 10 units of product 123
  • Company B uses 15 units of product 123

When submitting usage lines:

  • summaryKey is set to the unique company id, which is often times a UUID,
  • summaryDisplayName is set to the company name
POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}
[
    {
        "summaryKey": "{company-A-id}",
        "summaryDisplayName": "Company A",
        "quantity": 10,
        "productId": "123",
        "unitOfMeasurement": "unit"
    },
    {
        "summaryKey": "{company-B-id}",
        "summaryDisplayName": "Company B",
        "quantity": 15,
        "productId": "123",
        "unitOfMeasurement": "unit"
    }
]

Group by Company and Product Type

This grouping pattern is an option if your offering includes a very large array of products that make sense to group by product type.
As a reminder, Pax8 recommends simply grouping by Company for the majority of cases.

Below is an example grouping scenario for a Pax8 Partner that has 1 Company under their account with multiple product types.

  • Company A uses 10 units of product 1, which is Type VM
  • Company A uses 20 units of product 2, which is Type VM
  • Company A uses 30 units of product 3, which is Type Storage

When submitting usage lines:

  • summaryKey is set to the concatenation of the unique company id, which is often times a UUID, and the product type
  • summaryDisplayName is set to the company name and product type, separated by a comma
POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}
[
    {
        "summaryKey": "{company-A-id}-group-vm",
        "summaryDisplayName": "Company A, Group VM",
        "quantity": 10,
        "productId": "1",
        "unitOfMeasurement": "unit"
    },
    {
        "summaryKey": "{company-A-id}-group-vm",
        "summaryDisplayName": "Company A, Group VM",
        "quantity": 20,
        "productId": "2",
        "unitOfMeasurement": "unit"
    },
    {
        "summaryKey": "{company-A-id}-group-storage",
        "summaryDisplayName": "Company A, Group Storage",
        "quantity": 30,
        "productId": "3",
        "unitOfMeasurement": "unit"
    }
]

Group all of your requests by summary key

In the above examples, we've shown that you can send lines for multiple different summary keys in the same request, and then Pax8 will sort them into summary buckets based on that key. However, it may be simpler, and in fact highly recommended by Pax8, that you only includes lines that share a single summary key in a single request. This will help to keep everything grouped cleanly for both systems.

Include all usage lines for a single summary key in a single request

It is highly recommended that when posting usage lines for a given summary key, you include all applicable lines for that summary key in the same request. This is because if you split them up across multiple requests on the same day, only the lines from the most recent request would be active.

For example, if you post a couple lines for summary key A, and then minutes later post a few more lines for summary key A, the lines from the first post are actually deleted. Pax8 will only keep a record of the most recent lines posted for a given Subscription and summaryKey combination.

Updated about 2 months ago