/subscriptions

name: "Pax8 Subscriptions"
description: >
  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.
when_to_use: >-
  When checking license status, seat counts, subscription state, or change history for a
  client's Pax8 subscriptions. Use when: pax8 subscription, pax8 license, pax8 seat,
  pax8 provision, pax8 cancel, subscription management, license management, seat count,
  pax8 activate, license optimization, subscription lifecycle, or subscription status.

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.

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-licensing` or `cipp-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-patterns` for 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 `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