/orders

name: "Pax8 Orders"
description: >
  Pax8 orders: order retrieval, order line items, provisioning status and timelines,
  billing terms, and the order-to-subscription workflow.
when_to_use: >-
  When viewing orders, tracking provisioning status, or following an order through to an
  active subscription. Use when: pax8 order, pax8 purchase, pax8 provision, pax8 buy,
  place order pax8, order status, order tracking, new subscription order, or pax8
  ordering.

Pax8 Order Management

Overview

Orders in Pax8 are the mechanism for provisioning new cloud subscriptions for client companies. When an MSP needs to set up a new product for a client -- whether it is Microsoft 365 licenses, a security tool, or backup solution -- they create an order. The order contains one or more line items, each specifying a product, quantity, and billing term. Once submitted, the order is processed and, upon successful provisioning, creates one or more subscriptions.

Anti-triggers

• **What the client currently has** — an order is a historical purchase

event; the live licence state is `pax8-subscriptions`. An order that provisioned twelve months ago tells you nothing about today's seat count.

• **What the MSP owes for it** — orders do not carry the charge; use

`pax8-invoices`.

• **A quote to the client** — a Pax8 order is the MSP buying from the

distributor, not the client buying from the MSP. Client-facing quoting lives in `connectwise-cpq-quotes` or `autotask-quotes`.

• **A purchase order in the accounting system** — use

`qbo-expenses` or `xero-invoices`; a Pax8 order is not a PO on the books.

MCP Tools

Available Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | `pax8-list-orders` | List orders with optional filters | `page`, `size`, `companyId` | | `pax8-get-order-by-uuid` | Get a single order's details | `uuid` (required) |

List Orders

Call `pax8-list-orders` with optional parameters:

• **Filter by company:** Set `companyId` to a company UUID
• **Paginate:** Set `page` (0-based) and `size` (up to 200)

**Example: List all orders for a company:**

• `pax8-list-orders` with `companyId=a1b2c3d4-...`, `size=200`

**Example: List recent orders (first page):**

• `pax8-list-orders` with `page=0`, `size=50`

Get a Single Order

Call `pax8-get-order-by-uuid` with the `uuid` parameter.

**Example:**

• `pax8-get-order-by-uuid` with `uuid=o1r2d3e4-r5s6-7890-abcd-ef1234567890`

Key Concepts

Order Lifecycle

Create Order --> Processing --> Provisioning --> Completed --> Subscription Created
                                    |
                               PendingManual
                               (vendor action needed)

Order States

| State | Description | |-------|-------------| | `Submitted` | Order received and being processed | | `Processing` | Order is being provisioned | | `Completed` | Order fulfilled; subscriptions created | | `Failed` | Order could not be provisioned | | `PendingApproval` | Awaiting MSP approval (self-service orders) | | `Cancelled` | Order was cancelled before completion |

Line Items

Each order contains one or more line items. Each line item corresponds to a single product:

| Concept | Description | |---------|-------------| | Product | The cloud software being ordered | | Quantity | Number of seats/licenses | | Billing Term | Monthly, Annual, or Triennial | | Provision Start Date | When the subscription should begin |

Order-to-Subscription Flow

1. **MSP creates an order** with line items for one or more products 2. **Pax8 processes the order** and initiates provisioning with the vendor 3. **Provisioning completes** (automated: seconds/minutes; manual: hours/days) 4. **Subscription is created** and becomes Active 5. **Billing begins** on the provision start date

Field Reference

Order Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | UUID | System | Order unique identifier | | `companyId` | UUID | Yes | Company the order is for | | `lineItems` | array | Yes | Products being ordered | | `status` | string | System | Current order status | | `createdDate` | datetime | System | When the order was placed | | `orderedBy` | string | System | Who placed the order |

Line Item Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | UUID | System | Line item unique identifier | | `productId` | UUID | Yes | Product being ordered | | `quantity` | integer | Yes | Number of licenses | | `billingTerm` | string | Yes | Billing term (Monthly, Annual) | | `provisionStartDate` | date | No | When subscription starts | | `lineItemNumber` | integer | System | Position in the order |

Common Workflows

Track Order Provisioning Status

1. Call `pax8-get-order-by-uuid` with the order's `uuid` 2. Check the `status` field for the current state 3. Review each line item for product details and quantities 4. If status is not `Completed`, check back periodically

View Order History for a Client

1. Find the company UUID using `pax8-list-companies` with `company_name` 2. Call `pax8-list-orders` with `companyId` and `size=200` 3. Paginate if needed to get all orders 4. Review order dates, statuses, and line items

Verify Order Created Subscriptions

1. After an order shows `Completed` status, call `pax8-list-subscriptions` with `companyId` 2. Look for subscriptions matching the ordered product IDs 3. Verify quantities and billing terms match the original order

Standard MSP Onboarding Order Verification

When onboarding a new client, verify the typical stack was ordered:

1. Call `pax8-list-orders` with the `companyId` 2. Check that orders exist for the expected products (M365, security, backup) 3. Verify each order reached `Completed` status 4. Cross-reference with `pax8-list-subscriptions` to confirm active subscriptions

Response Examples

**Order:**

{
  "id":