Pax8 Orders

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.

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": "o1r2d3e4-r5s6-7890-abcd-ef1234567890",
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Completed",
  "createdDate": "2026-02-20T09:15:00.000Z",
  "orderedBy": "partner@msp.com",
  "lineItems": [
    {
      "id": "l1i2n3e4-i5t6-7890-abcd-ef1234567890",
      "productId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "quantity": 25,
      "billingTerm": "Annual",
      "provisionStartDate": "2026-03-01",
      "lineItemNumber": 1
    }
  ]
}

Error Handling

Common Errors

| Error | Cause | Resolution | |-------|-------|------------| | Order not found | Invalid UUID | Verify the order UUID with pax8-list-orders | | No orders found | Company has no orders | Verify the company UUID is correct |

Order State Issues

| State | Meaning | Action | |-------|---------|--------| | Failed | Provisioning failed | Check the Pax8 portal for details; may need to resubmit | | PendingApproval | Awaiting approval | Approve in the Pax8 portal if orderApprovalRequired is set | | Cancelled | Order was cancelled | Create a new order if still needed |

Billing Term Reference

| Term | Commitment | Seat Changes | Discount | |------|-----------|--------------|----------| | Monthly | None | Increase/decrease anytime | Standard price | | Annual | 12 months | Increase anytime, decrease restricted | ~10% discount | | Triennial | 36 months | Increase anytime, decrease restricted | ~15% discount |

Best Practices

1. Validate before ordering - Check company, product, and quantity before submitting orders in the Pax8 portal
2. Use annual billing - Annual commitments save money; recommend to clients
3. Bundle line items - Include all products in a single order when possible
4. Track provisioning - Monitor order status until completion using pax8-get-order-by-uuid
5. Check product availability - Use pax8-get-product-by-uuid to verify products are active before ordering
6. Handle failures gracefully - Failed orders may need to be resubmitted
7. Respect quantity limits - Stay within product min/max quantity bounds
8. Document orders - Record order IDs in your PSA for cross-reference
9. Test with small quantities - For new products, test with minimal seats before scaling up
10. Verify subscriptions - After order completion, confirm subscriptions are active with pax8-list-subscriptions

Related Skills

• [Pax8 API Patterns](../api-patterns/SKILL.md) - MCP tools reference and connection info
• [Pax8 Products](../products/SKILL.md) - Product catalog and pricing
• [Pax8 Subscriptions](../subscriptions/SKILL.md) - Managing resulting subscriptions
• [Pax8 Companies](../companies/SKILL.md) - Company management
• [Pax8 Invoices](../invoices/SKILL.md) - Billing for orders