Overview

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

Endpoints

Save Usage Lines

• Save Usage Lines For a Pax8 Subscription
• POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}
• POST /usage/lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}

Get Usage Lines

• Get Usage Lines for a Pax8 Subscription
• GET /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}&summaryKey={summaryKey}
• GET /usage/lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}&summaryKey={summaryKey}

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.

Note that the above POST and GET API's have an optional parameter called: isSimulation that defaults to false. This parameter is used to facilitate integration testing if you are migrating off of a legacy Pax8 integration.

The Usage Line Object

{
    "summaryKey": "key",
    "summaryDisplayName": "name",
    "quantity": 1,
    "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
• The isSimulation parameter should be set to true when posting usage during integration testing. This allows you to post usage to Pax8 in a way that will not affect real billing. Contact your Pax8 support representative if you want more information on testing your usage migration.

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