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