Mapping Pax8 Microsoft Subscriptions to Graph API Identifiers
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.
- Fetch Pax8 Subscription Details: Call the
GET /v1/subscriptions/{subscriptionId}
endpoint for the desired subscription. - Identify the Vendor Subscription ID: In the API response, locate the
vendorSubscriptionId
field. This value is the Microsoft Graph API Subscription ID. - 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
- Fetch Pax8 Company Details: Use
GET /v1/companies/{companyId}
. - 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
- Get Pax8 Product Name: From the Pax8 Product API (
GET /v1/products/{productId}
), note the productname
(e.g., "Microsoft 365 Business Standard"). - 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'sProduct_Display_Name
column. - From that matching row, retrieve the
GUID
. ThisGUID
is theskuId
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:
- 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 viaGET https://graph.microsoft.com/v1.0/organization/{tenantId}/subscribedSkus
. - Find Matching SKU: In the Graph API response, find the object where its
skuId
matches theGUID
obtained in Step 2. From here, you can reconcile details likeconsumedUnits
.
References & Key Considerations
- Pax8 API: OpenAPI Spec
- Microsoft SKU Info: Product Names & Service Plan Identifiers (download CSV from this page)
- Graph API SKUs: List subscribedSkus
- Graph API Subscriptions: Get subscription
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 13 days ago