Guides

Mapping Pax8 Microsoft Subscriptions to Graph API Identifiers

Suggest Edits

This guide details how to map Pax8 company, product, and subscription identifiers to their Microsoft Tenant and Graph API counterparts. With the recent addition of the vendorSubscriptionId to the Pax8 API, there are now two distinct methods depending on your goal.

  • Method 1 (Recommended for Existing Subscriptions): A direct method for partners who need to map their existing Pax8 subscriptions to Microsoft Graph API subscription IDs for automation and workflows.
  • Method 2 (Advanced/Catalog Integration): A workaround for integrators or partners who need to map product SKUs without an existing subscription, for example, to build a full catalog integration or enable ordering.

Method 1: Direct Mapping for Existing Subscriptions

This is the simplest and most effective way to reconcile a specific, active Pax8 subscription with its counterpart in the Microsoft Graph API.

The Process

The Pax8 Subscription API now exposes the Microsoft subscription ID directly in the vendorSubscriptionId field.

  1. Fetch Pax8 Subscription Details: Call the GET /v1/subscriptions/{subscriptionId} endpoint for the desired subscription.
  2. Identify the Vendor Subscription ID: In the API response, locate the vendorSubscriptionId field. This value is the Microsoft Graph API Subscription ID.
  3. Use in Microsoft Graph API: You can now use this ID directly in Microsoft Graph API calls. For example, to get details on that specific subscription:
    GET https://graph.microsoft.com/v1.0/subscriptions/{vendorSubscriptionId}

Example Pax8 API Response Snippet:

{
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "companyId": "f9e8d7c6-b5a4-3210-a9b8-c7d6e5f4g3h2",
  "productId": "MS-0C-O365-BUSINESS-PREMIUM",
  "quantity": 10,
  "vendorSubscriptionId": "0e9a8b7c-6d5f-4e3d-2c1b-0a9f8e7d6c5b", // <-- This is the Microsoft Graph ID
  // ... other fields
}

Method 2: Mapping Products for Catalog Integration (Advanced)

This method is for mapping Pax8 products to Microsoft skuId values before a subscription is purchased. This is useful for developers building catalog integrations or advanced management tools that need to understand the entire Microsoft product offering.

Step 1: Map Pax8 Company to Microsoft Tenant ID

  1. Fetch Pax8 Company Details: Use GET /v1/companies/{companyId}.
  2. Identify Tenant ID: The externalId field in the response corresponds to the Microsoft Tenant ID.

Step 2: Map Pax8 Product to Microsoft Graph API SKU

  1. Get Pax8 Product Name: From the Pax8 Product API (GET /v1/products/{productId}), note the product name (e.g., "Microsoft 365 Business Standard").
  2. Use Microsoft's Reference CSV:
    • Download the CSV from the Microsoft Product names and service plan identifiers page.
    • Find the Pax8 product name in the CSV's Product_Display_Name column.
    • From that matching row, retrieve the GUID. This GUID is the skuId used by the Graph API.

Step 3: Use the Mapped IDs in Graph API

With the Tenant ID (from Step 1) and the skuId (from Step 2), you can query the Microsoft Graph API. For example, to check the license status for that SKU within a specific tenant:

  1. Query Microsoft Graph API: Call GET https://graph.microsoft.com/v1.0/subscribedSkus. Note: this endpoint uses the Tenant ID contextually from your authentication token. You can also query across all tenants via GET https://graph.microsoft.com/v1.0/organization/{tenantId}/subscribedSkus.
  2. Find Matching SKU: In the Graph API response, find the object where its skuId matches the GUID obtained in Step 2. From here, you can reconcile details like consumedUnits.

References & Key Considerations

Key Considerations:

  • Choosing the Right Method: For any existing subscription, Method 1 is the preferred solution. Use Method 2 only when you need product information without an active subscription.
  • CSV Updates: For Method 2, regularly download the latest Microsoft product reference CSV as product names and GUIDs can change.
  • Product Naming: Be mindful of potential minor differences in product names between the Pax8 catalog and the Microsoft CSV. Fuzzy matching may be required.

Updated 6 days ago