Usage Lines

Usage Lines represent usage for a subscription and usage product for a single billing period.

Endpoints

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

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

Usage Line Object

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. 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.
It gives a friendly name to the group defined by a summaryKey. Most often, this will be the company name.
NOTE: both summaryKey and summaryDisplayName have a 255 character limit.

Check out some grouping examples on the line grouping examples page

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

Post Usage Lines for a Subscription

Vendors should post current totals for the entire billing period. Pax8 will not sum up incremental charges that are posted throughout a billing period.
Vendors should post usage to the subscription Pax8 provides upon the provisioning request. If the subscription is provisioned at the customer level (by company), Vendor should expect to post usage to the customer level.
Posting usage lines for a billing period will overwrite any previously posted lines for that period.
Pax8 will always bill on the most recent lines posted for a billing period.

POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}
[
    {
        "summaryKey": "key1",
        "summaryDisplayName": "name1",
        "quantity": 1,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    },
    {
        "summaryKey": "key2",
        "summaryDisplayName": "name2",
        "quantity": 1,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]

[
    {
        "summaryKey": "key1",
        "summaryDisplayName": "name1",
        "quantity": 1,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    },
    {
        "summaryKey": "key2",
        "summaryDisplayName": "name2",
        "quantity": 1,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]

Post Usage Lines with an External ID

Alternatively, our API 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.

POST /usage/lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}

Get All Usage Lines for a Subscription and Summary Key

GET  /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}&summaryKey={summaryKey}

{
    "page": {
        "size": 1,
        "totalElements": 1,
        "totalPages": 1,
        "number": 1
    },
    "content": [
        {
            "summaryKey": "test",
            "summaryDisplayName": "name",
            "quantity": 1,
            "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
            "unitOfMeasurement": "unit"
        }
    ]
}