Usage Overview

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

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).
Manages cloud software for a Company and are Pax8's primary users.
Company - A Pax8 Company, also known as an End User. A Company buys
cloud software from a Partner
Subscription - A 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 monthly timeframe, measured from from the first day to the last day of a month, for which Pax8 will create billable charges for Partners

A Partner orders from Pax8, and a Subscription is created using the Provisioning Endpoints.
Vendors will post usage to Pax8 throughout an ongoing Billing Period in order to keep usage totals up to date within Pax8.
Three 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.
Vendors will be unable to submit usage for a previous Billing Period for any Subscription after midnight UTC on the 2nd after the following month.

Pax8 tracks usage totals on a daily basis. Best practices:

Vendors should post the most current usage totals once per day.
Pax8 does not track usage cumulatively. The latest usage posted will represent the total for a Billing Period.
When multiple posts occur for the same Subscription and summaryKey on the same day. The default behavior is that older usage from that day is deleted. However overwriting same-day usage is configurable. See documentation for detailed examples

When a Billing Period ends, Vendors have a limited window to post usage:

Grace Period: 2 days after the Billing Period ends
Deadline: Based on UTC time standard
After the grace period, Pax8 creates billable charges and no further usage can be posted for that period

Example:

Billable charges are line items that appear on the actual invoice sent to Partners
Once created, billable charges cannot be changed
On the 3rd of each month, Pax8 will:
- Look for the latest usage totals posted for subscriptions from the previous Billing Period
- Convert these totals into billable charges
- Finalize partner bills and prepare invoices
After the 2nd, usage data for the previous month cannot be corrected via the API

Note: There are some caveats to this process. For detailed examples, please refer to the billing examples page.

Usage line posting is currently synchronous, meaning:
- The client waits for the request to complete with an HTTP 200 status code.
- The client remains connected until success or failure is confirmed.
Asynchronous processing (where Pax8 would accept payloads with a 201 status and provide polling capabilities) is not supported at this time

There is an upper limit to payload size before timeouts occur.
Recommendation: Send no more than fifty (50) usage lines in a single request payload.
This ensures the Pax8 system can process each request before client timeout.

When creating summaries with more than 50 usage lines sharing the same summaryKey:

Problem: Default behavior causes the second batch of 50 lines to overwrite the first batch when sent on the same day.
Solution: Include the overwriteSameDayUsage=false parameter when posting usage.
- This configures the API to append to existing lines rather than overwrite them.

For detailed examples of this configuration, see the overwrite same-day usage documentation.

You can find the complete OpenAPI Spec for the usage API here