Pax8 Subscriptions

Pax8 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.

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 companyId to a company UUID
• Filter by status: Set status to one of the allowed values (see below)
• Filter by billing term: Set billingTerm to monthly, annual, two-year, three-year, one-time, trial, or activation
• Filter by product: Set productId to a product UUID
• Paginate: Set page (0-based) and size (up to 200)

Example: List all active subscriptions for a company:

• pax8-list-subscriptions with companyId=a1b2c3d4-..., status=Active, size=200

Example: List all trial subscriptions:

• pax8-list-subscriptions with status=Trial, size=200

Example: List all annual subscriptions:

• pax8-list-subscriptions with billingTerm=annual, status=Active, size=200

Get a Single Subscription

Call pax8-get-subscription-by-uuid with the uuid parameter.

Example:

• pax8-get-subscription-by-uuid with uuid=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

1. Find the company UUID using pax8-list-companies with company_name
2. Call pax8-list-subscriptions with companyId and status=Active
3. For each subscription, optionally call pax8-get-product-by-uuid with the productId to get product names

License Optimization Across All Clients

This is one of the most valuable MSP workflows -- finding unused or underutilized licenses:

1. Call pax8-list-companies with size=200 to get all companies
2. For each company, call pax8-list-subscriptions with companyId and status=Active
3. Build a list of all subscriptions with company name, product, quantity, billing term, and monthly cost (quantity * price)
4. Sort by monthly cost descending to surface the biggest savings opportunities
5. Flag subscriptions with very low seat counts or monthly billing that could switch to annual

Subscription Status Report by Company

1. Find the company with pax8-list-companies or pax8-get-company-by-uuid
2. Call pax8-list-subscriptions with companyId and size=200 (no status filter to get all)
3. Group results by status and calculate total monthly cost for active subscriptions

Renewal Management

1. Call pax8-list-subscriptions with status=Active and billingTerm=annual
2. Review each subscription's endDate to find upcoming renewals
3. 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):

1. Call pax8-get-usage-summary with subscriptionId (required)
2. Optionally filter by resourceGroup or companyId
3. For detailed line-item usage, call pax8-get-detailed-usage-summary with the usageSummaryId

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

1. Check state before modifying - Always verify the subscription is in Active state before making changes
2. Understand commitment terms - Annual subscriptions restrict quantity decreases
3. Optimize regularly - Review subscriptions monthly to find unused licenses
4. Use company filter - Always filter by companyId when checking a specific client's subscriptions
5. Monitor pending states - Subscriptions in pending states need attention
6. Plan renewals - Track end dates and plan renewal conversations with clients
7. Batch operations carefully - When checking multiple companies, respect rate limits (1000/min)
8. Document changes - Note why quantities were changed in your PSA or documentation
9. Verify after modification - Re-fetch the subscription after changes to confirm they took effect
10. Use billing term filter - Filter by billingTerm=monthly to 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