Mapping Pax8 Identifiers to Microsoft Graph API

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

---

Method 1: Direct Mapping for Existing Subscriptions (Recommended)

Use this method when you have an active Pax8 subscription and need to identify the corresponding Microsoft commercial subscription in Graph.

Steps:

1. Fetch the Pax8 subscription using GET /v1/subscriptions/{subscriptionId}. Note the vendorSubscriptionId in the response.
2. In the Microsoft 365 Admin Center, you’ll see the vendorSubscriptionId in the URL for the subscription under Billing > Your Products. This confirms it is the Microsoft commerce subscription ID.
3. In Microsoft Graph, use the /directory/subscriptions endpoint. Look for a companySubscription object where commerceSubscriptionId matches the Pax8 vendorSubscriptionId.
   • You can use alternate key addressing: GET https://graph.microsoft.com/v1.0/directory/subscriptions(commerceSubscriptionId='{vendorSubscriptionId}')
   • Or list all subscriptions and filter client-side: GET https://graph.microsoft.com/v1.0/directory/subscriptions
4. The Graph /subscriptions endpoint is for webhook subscriptions (change notifications) and does not return commercial product subscriptions. Always use /directory/subscriptions for licensing.

Example:

• Pax8 API returns vendorSubscriptionId: 56daaf48-497d-42d5-d93e-3e45c8cb33ec
• In Graph, GET /directory/subscriptions(commerceSubscriptionId='56daaf48-497d-42d5-d93e-3e45c8cb33ec') returns the matching companySubscription object.

---

Method 2: Mapping Products for Catalog Integration (Advanced)

Use this method when you need to map Pax8 products to Microsoft skuId values before a subscription is purchased (for catalog integrations or quoting).

Steps:

1. Get the Pax8 product name from GET /v1/products/{productId}.
2. Download Microsoft’s Product names and service plan identifiers CSV. Find the product name in the ProductDisplayName column and note the GUID (skuId). See list of references below.
3. In Graph, use GET /subscribedSkus to see which SKUs are active for a tenant. Match the skuId to confirm presence and review license counts.

---

Key Points:

• The vendorSubscriptionId from Pax8 matches the commerceSubscriptionId in Microsoft Graph’s /directory/subscriptions endpoint.
• The /subscriptions endpoint in Graph is for webhooks, not licensing.
• For product mapping, use Microsoft’s official CSV to match product names to skuId.
• Always use a Graph access token scoped to the customer tenant (Pax8's externalId on the company endpoint can be used to store this value).
• For multiple subscriptions of the same SKU, use the subscriptionIds array in /subscribedSkus to cross-reference companySubscription.id values.

---

Troubleshooting:

• If you cannot find the subscription in Graph, verify you are using the correct tenant and permissions.
• If you see the vendorSubscriptionId in the admin center URL but not in Graph, ensure you are querying /directory/subscriptions, not /subscriptions.
• For product mapping, confirm product names match exactly or use fuzzy matching if needed.

---

References:

• Pax8 API OpenAPI specs to get help form AI: https://devx.pax8.com/openapi/
• Pax8 changelog for vendorSubscriptionId addition: https://devx.pax8.com/changelog/partner-direct-microsoft-subscription-mapping-added-to-subscription-api
• Microsoft Graph companySubscription: https://learn.microsoft.com/en-us/graph/api/companysubscription-get?view=graph-rest-1.0
• Microsoft Graph directory subscriptions: https://learn.microsoft.com/en-us/graph/api/directory-list-subscriptions?view=graph-rest-1.0
• Microsoft Graph subscribedSkus: https://learn.microsoft.com/en-us/graph/api/subscribedsku-list?view=graph-rest-1.0
• Microsoft Product names and service plan identifiers (CSV): https://learn.microsoft.com/en-us/entra/identity/users/licensing-service-plan-reference

---

Summary Table: