How to Use Usage Endpoints

Below is a quick introduction to the basics of using the usage endpoints.

Base Url

The base url for all usage requests is https://api.pax8.com/v2

Terminology

The Pax8 Usage API provides a way for Vendors to upload usage data for Pax8 Subscriptions. Here are a few key terms

Partner - A Pax8 Partner, also known as a Managed Service Provider (MSP). Partners
manage cloud software for Companies and are Pax8's primary users.
Company - A Pax8 Company, also known as an End User. Companies buy
cloud software and support from a Partner.
Subscription - A subscription record in Pax8 for a specific Partner/Company/Product combination in the Pax8 system.
Usage Line - A single line of usage data represented by a specific Subscription/Product/Quantity combination in the Pax8 system.
Billing Period - A window in time for which Pax8 will gather usage and create billable charges for Partners, usually monthly.

How Posting Usage Works

A Partner orders from Pax8, and a Subscription is created
Vendors will post Usage Lines to Pax8 throughout an ongoing billing period in order to keep usage totals up to date with Pax8
3 days after the end of a Billing Period, Pax8 will create billable charges for the Partner based on the latest totals posted by Vendor for that billing period.
After billable charges are created for a Partner for a given Billing Period, Vendor can no longer submit usage for that Subscription/Billing Period combination.

Expectations When Posting Usage

When vendors post usage for a Subscription, the latest totals will overwrite all the older totals that were posted that Billing Period. Pax8 will not track usage posted by vendors cumulatively. Our average latency at our current low volumes are about 400 to 500 milliseconds, and the upper limit on post requests is 1000 per minute.
- Example: Vendor posts a Usage Line for some product with quantity 5, and then later posts a Usage Line for the same Subscription and Billing Period for quantity 6. Pax8 calculates the total usage at that time to be 6, not 11.
Pax8 tracks usage totals on a daily basis. Vendors should post the most current usage totals for a subscription once per day.
- Vendors can post usage more than once per day, but Pax8 will only keep a record of the latest usage posted for that day.
- If vendors post usage for the same Subscription and summaryKey more than once on the same day, the older usage from that day is deleted, and Pax8 will store the most recent usage posted for that Subscription and summaryKey . For more info on how to use the summaryKey see the Usage Line Grouping Examples page.
When a Billing Period ends, vendors have 2 days to post usage for that period until Pax8 creates billable charges, after which, usage can no longer be posted for that period.
- Example: A billing period ends on October 31. Vendors can still post usage for the October billing period on November 1 and November 2, but on November 3rd, attempts to post usage for the October billing period will be rejected.

Expectations when Pax8 creates billable charges

Billable charges are line items that are on the actual invoice that goes to Partners. They cannot be changed once created.
On the 3rd of each month, Pax8 will look for the latest usage totals posted for a subscription for the previous Billing Period, and convert them into billable charges. After the 3rd, usage data for the previous month cannot be corrected via the API. At this stage, partner bills are finalized and invoices are prepared.
- This comes with some caveats. Check out the billing examples page for some detailed examples.

OpenAPI Spec

You can find the complete OpenAPI Spec for the usage API here: https://devx.pax8.com/openapi/661469e054fdd00030608528