Pax8 Subscriptions
Pax8 subscriptions: license and seat counts, the full subscription lifecycle and its states, change history, filtering by company or product, and quantity management for license optimization.
SKILL.mdmsp-claude-plugins/pax8/pax8/skills/subscriptions/SKILL.md
GitHubPax8 Subscription Lifecycle Management
Overview
Subscriptions in Pax8 represent active cloud product licenses assigned to a client company. When an order is placed and provisioned, it creates a subscription. Subscriptions are the core ongoing entity that MSPs manage -- adjusting seat counts as clients hire or leave, upgrading plans, or cancelling when a product is no longer needed. Every subscription is tied to a company and a product, with a quantity (seat count), billing term, and status.
Anti-triggers
- Licences bought through Sherweb — the other CSP marketplace in this
marketplace. Same concepts, different account, no shared IDs; use
sherweb-subscriptions. A client's licences may sit in either, or split across both, so establish which distributor holds the product before reasoning about seat counts. - A licence assigned to a named user — Pax8 tracks what the MSP
purchased; who it is assigned to lives in the tenant. Use
m365-licensingorcipp-licenses. Purchased seats and assigned seats legitimately differ, and reconciling them is a cross-tool comparison. - Changing a seat count — no tool here does it. This surface is
read-only; quantity changes and cancellations happen in the Pax8 portal.
See
pax8-api-patternsfor the full read-only scope. - The purchase event rather than the resulting licence — use
pax8-orders; an order is the transaction, a subscription is what it created.
MCP Tools
Available Tools
| Tool | Description | Key Parameters |
|---|---|---|
pax8-list-subscriptions |
List and filter subscriptions | page, size, sort, status, billingTerm, companyId, productId |
pax8-get-subscription-by-uuid |
Get a single subscription | uuid (required) |
List Subscriptions
Call pax8-list-subscriptions with optional parameters:
- Filter by company: Set
companyIdto a company UUID - Filter by status: Set
statusto one of the allowed values (see below) - Filter by billing term: Set
billingTermtomonthly,annual,two-year,three-year,one-time,trial, oractivation - Filter by product: Set
productIdto a product UUID - Paginate: Set
page(0-based) andsize(up to 200)
Example: List all active subscriptions for a company:
pax8-list-subscriptionswithcompanyId=a1b2c3d4-...,status=Active,size=200
Example: List all trial subscriptions:
pax8-list-subscriptionswithstatus=Trial,size=200
Example: List all annual subscriptions:
pax8-list-subscriptionswithbillingTerm=annual,status=Active,size=200
Get a Single Subscription
Call pax8-get-subscription-by-uuid with the uuid parameter.
Example:
pax8-get-subscription-by-uuidwithuuid=s1u2b3s4-c5r6-7890-abcd-ef1234567890
Key Concepts
Subscription Lifecycle
Order Placed --> Provisioning --> Active --> [Modify/Cancel] --> Cancelled
| |
PendingManual ActivePendingChange
PendingAutomated PendingCancel
WaitingForDetails
Subscription States
| State | Description |
|---|---|
Active |
Subscription is live and billing |
Cancelled |
Subscription has been terminated |
PendingManual |
Awaiting manual provisioning by vendor |
PendingAutomated |
Automated provisioning in progress |
PendingCancel |
Cancellation request submitted, not yet complete |
WaitingForDetails |
Additional information needed for provisioning |
Trial |
Free trial period active |
Converted |
Trial converted to paid subscription |
PendingActivation |
Activation pending |
Activated |
Recently activated |
Billing Terms
| Term | Description | Commitment |
|---|---|---|
| Monthly | Month-to-month | Cancel anytime |
| Annual | 12-month commitment | Locked for 12 months |
| Two-Year | 24-month commitment | Locked for 24 months |
| Three-Year | 36-month commitment | Locked for 36 months |
| One-Time | Single purchase | No recurring billing |
| Trial | Free trial | No commitment |
Quantity Management
The quantity field represents the number of licenses (seats, devices, or units depending on the product). Changing quantity triggers a billing adjustment:
- Increase: Additional seats are prorated for the current billing period
- Decrease: Seat reduction may be restricted by vendor commitment terms
- Annual plans: Seat decreases may only be allowed at renewal
Field Reference
Subscription Fields
| Field | Type | Description |
|---|---|---|
id |
UUID | Subscription unique identifier |
companyId |
UUID | Associated company ID |
productId |
UUID | Associated product ID |
quantity |
integer | Number of licenses/seats |
startDate |
date | Subscription start date |
endDate |
date | Subscription end date (for commitments) |
createdDate |
datetime | When the subscription was created |
billingStart |
date | When billing begins |
status |
string | Current subscription state |
billingTerm |
string | Billing term (Monthly, Annual) |
price |
decimal | Current unit price |
commitmentTermId |
UUID | Commitment term identifier |
Usage Summary Fields
| Field | Type | Description |
|---|---|---|
subscriptionId |
UUID | Associated subscription |
resourceGroup |
string | Usage resource group |
quantity |
decimal | Usage quantity |
unitOfMeasure |
string | Usage unit |
currentCharges |
decimal | Charges for this period |
date |
date | Usage date |
Common Workflows
Check Subscriptions for a Company
- Find the company UUID using
pax8-list-companieswithcompany_name - Call
pax8-list-subscriptionswithcompanyIdandstatus=Active - For each subscription, optionally call
pax8-get-product-by-uuidwith theproductIdto get product names
License Optimization Across All Clients
This is one of the most valuable MSP workflows -- finding unused or underutilized licenses:
- Call
pax8-list-companieswithsize=200to get all companies - For each company, call
pax8-list-subscriptionswithcompanyIdandstatus=Active - Build a list of all subscriptions with company name, product, quantity, billing term, and monthly cost (
quantity * price) - Sort by monthly cost descending to surface the biggest savings opportunities
- Flag subscriptions with very low seat counts or monthly billing that could switch to annual
Subscription Status Report by Company
- Find the company with
pax8-list-companiesorpax8-get-company-by-uuid - Call
pax8-list-subscriptionswithcompanyIdandsize=200(no status filter to get all) - Group results by status and calculate total monthly cost for active subscriptions
Renewal Management
- Call
pax8-list-subscriptionswithstatus=ActiveandbillingTerm=annual - Review each subscription's
endDateto find upcoming renewals - For renewals within the next 30 days, prepare a review list with company name, product, seat count, and pricing
Get Usage Data for a Subscription
For usage-based products (e.g., Azure):
- Call
pax8-get-usage-summarywithsubscriptionId(required) - Optionally filter by
resourceGrouporcompanyId - For detailed line-item usage, call
pax8-get-detailed-usage-summarywith theusageSummaryId
Response Examples
Subscription:
{
"id": "s1u2b3s4-c5r6-7890-abcd-ef1234567890",
"companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"productId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
"quantity": 25,
"startDate": "2025-06-01",
"endDate": "2026-05-31",
"createdDate": "2025-05-28T14:30:00.000Z",
"billingStart": "2025-06-01",
"status": "Active",
"billingTerm": "Annual",
"price": 17.10
}
Error Handling
Common Errors
| Error | Cause | Resolution |
|---|---|---|
| Subscription not found | Invalid UUID | Verify the UUID with pax8-list-subscriptions |
| Invalid status filter | Wrong status value | Use one of: Active, Cancelled, PendingManual, PendingAutomated, PendingCancel, WaitingForDetails, Trial, Converted, PendingActivation, Activated |
| Invalid billingTerm | Wrong billing term value | Use one of: monthly, annual, two-year, three-year, one-time, trial, activation |
State Transition Errors
| Current State | Attempted Action | Notes |
|---|---|---|
| Cancelled | Modify quantity | Cannot modify cancelled subscription |
| PendingCancel | Modify quantity | Cannot modify during cancellation |
| PendingManual | Cancel | Cannot cancel during provisioning |
| ActivePendingChange | Modify quantity | Wait for current change to complete |
Best Practices
- Check state before modifying - Always verify the subscription is in
Activestate before making changes - Understand commitment terms - Annual subscriptions restrict quantity decreases
- Optimize regularly - Review subscriptions monthly to find unused licenses
- Use company filter - Always filter by
companyIdwhen checking a specific client's subscriptions - Monitor pending states - Subscriptions in pending states need attention
- Plan renewals - Track end dates and plan renewal conversations with clients
- Batch operations carefully - When checking multiple companies, respect rate limits (1000/min)
- Document changes - Note why quantities were changed in your PSA or documentation
- Use billing term filter - Filter by
billingTerm=monthlyto quickly find candidates for annual commitment savings
Related Skills
- Pax8 API Patterns - MCP tools reference and connection info
- Pax8 Companies - Company management
- Pax8 Products - Product catalog and pricing
- Pax8 Orders - Creating new subscriptions via orders
- Pax8 Invoices - Billing for subscriptions