# Table of Contents - [Developer Platform Overview](#developer-platform-overview) - [Pax8 Glossary](#pax8-glossary) - [Integrated MSP Apps](#integrated-msp-apps) - [Ordering Products](#ordering-products) - [Understanding Usage Products](#understanding-usage-products) - [REST API Fundamentals](#rest-api-fundamentals) - [Integrator Setup Guide](#integrator-setup-guide) - [Using Pax8's APIs](#using-pax8-s-apis) - [Mapping Pax8 Identifiers to Microsoft Graph API](#mapping-pax8-identifiers-to-microsoft-graph-api) - [CORS](#cors) - [Subscription Management](#subscription-management) - [Starter Workflows](#starter-workflows) - [Authentication](#authentication) - [Pax8 Partner Authorization via OAuth2](#pax8-partner-authorization-via-oauth2) - [Allowlisted IP Addresses for Outgoing Traffic](#allowlisted-ip-addresses-for-outgoing-traffic) - [Response Codes](#response-codes) - [Provision Notification](#provision-notification) - [Subscription Events: Completed Line Items](#subscription-events-completed-line-items) - [Using AI to Build Your Pax8 Integration](#using-ai-to-build-your-pax8-integration) - [Building AI Agents for Pax8](#building-ai-agents-for-pax8) - [MCP Server](#mcp-server) - [Provision Detail](#provision-detail) - [Invoice & Billing Integrations](#invoice-billing-integrations) - [Usage Lines](#usage-lines) - [MCP Setup Guide (Cursor)](#mcp-setup-guide-cursor-) - [Provision Result](#provision-result) - [MCP Setup Guide (Copilot)](#mcp-setup-guide-copilot-) - [Provisioning Scenarios](#provisioning-scenarios) - [Billing Scenarios](#billing-scenarios) - [MCP Setup Guide (VSCode)](#mcp-setup-guide-vscode-) - [Webhook Configuration](#webhook-configuration) - [How to use Webhook APIs](#how-to-use-webhook-apis) - [Provisioning Simulation Scenarios](#provisioning-simulation-scenarios) - [Provision Attempt](#provision-attempt) - [Overwriting or Appending Same Day Usage](#overwriting-or-appending-same-day-usage) - [Request and Response Examples](#request-and-response-examples) - [Provisioning Overview](#provisioning-overview) - [Introduction for Marketplace Vendors](#introduction-for-marketplace-vendors) - [Provisioner and Webhooks](#provisioner-and-webhooks) - [How To Use Webhooks As a 3rd Party Integrator](#how-to-use-webhooks-as-a-3rd-party-integrator) - [MCP Setup Guide (Claude)](#mcp-setup-guide-claude-) - [Provisioning Integration Testing](#provisioning-integration-testing) - [Aggregate Usage Lines](#aggregate-usage-lines) - [Usage Line Grouping Examples](#usage-line-grouping-examples) - [Usage Overview](#usage-overview) - [Provision Request](#provision-request) - [Subscribing to Events](#subscribing-to-events) - [Providing 3rd Parties Access](#providing-3rd-parties-access) --- # Developer Platform Overview Welcome to the Pax8 Developer Platform, your gateway to unlocking powerful automation and enhancing your Managed Service Provider (MSP) business. We provide the tools and resources to help you seamlessly integrate with the Pax8 Platform, empowering you to automate tasks such as managing companies, placing orders, updating subscriptions, looking up product information, and reading invoices. Our platform leverages standard HTTP requests and returns JSON-formatted data with standard HTTP response codes, ensuring a familiar and efficient development experience. * * * Discover & Build: Your Integration Journey [](https://devx.pax8.com/docs/introduction#discover--build-your-integration-journey) ----------------------------------------------------------------------------------------------------------------------------------- The Pax8 Developer Platform supports two primary approaches to integration, designed to fit your unique needs: 1. **Discover & Integrate Pre-Built Solutions** For MSPs looking to quickly enhance their operations without custom development, we offer a rich ecosystem of pre-built integrations from trusted vendors. These Integrated MSP Apps are designed to help you grow your business, reduce risk, and increase operational efficiency for common use cases like billing, ordering, quoting, and subscription management. **Learn more:** Explore these solutions in our **[Integrated MSP Apps](https://devx.pax8.com/docs/integrated-msp-apps) ** section under **Discover & Integrate** in the navigation. 2. **Build Your Own Custom Integration** If you have specific requirements not met by existing solutions, or if you prefer to tailor an integration to your exact specifications, you can build it yourself. Our platform provides comprehensive tools and documentation to enable custom development, whether you're starting with workflows, leveraging our robust APIs, or responding to events. **Get Started:** Dive into the **Build Your Own Integration** section in the navigation to find guides on: * **Starting with Workflows:** Our recommended approach for [common automation workflows](https://devx.pax8.com/recipes) . * **Leverage Our APIs:** Detailed documentation for direct API interaction. * **Respond to Events:** Implement event-driven solutions with webhooks. * * * Your Central Hub: The Pax8 Integrations Hub [](https://devx.pax8.com/docs/introduction#your-central-hub-the-pax8-integrations-hub) -------------------------------------------------------------------------------------------------------------------------------------- While all our public API documentation is located here on this site, the actual creation and management of your API credentials and other integration-related functionalities are handled within the **Pax8 Integrations Hub** in the Pax8 application. You can find the Integrations Hub by going to **"Settings > Integrations"** in the left navigation of the Pax8 app. The Integrations Hub is currently only accessible to **Partner Admin** and **Primary Partner Admin** roles. Within the Integrations Hub, you can: * **Create and Manage API Credentials:** Generate your secure API access tokens for custom integrations. * Access credentials here: [https://app.pax8.com/integrations/credentials](https://app.pax8.com/integrations/credentials) * **Explore & Connect Integrated MSP Apps:** Discover and manage connections to existing integrations built by third-party vendors. * Explore Apps here: [https://app.pax8.com/integrations/apps](https://app.pax8.com/integrations/apps) * **Hook Up Webhooks and Get Events:** Subscribe to real-time events to build more efficient, event-driven integrations for your custom solutions. * Manage Events here: [https://app.pax8.com/integrations/events](https://app.pax8.com/integrations/events) * Learn more about subscribing to events on this documentation site: [https://devx.pax8.com/docs/subscribe-to-events](https://devx.pax8.com/docs/subscribe-to-events) * **Try Our MCP Server:** Integrate Pax8 data with your preferred AI tools for natural language interaction, supporting advanced automation and insights. * Access the MCP Server here: [https://app.pax8.com/integrations/mcp](https://app.pax8.com/integrations/mcp) * Find more information about our MCP server on this documentation site: [https://devx.pax8.com/docs/mcp-server](https://devx.pax8.com/docs/mcp-server) We encourage our partners to use a combination of these powerful features to build out robust integrations, improve efficiency, leverage AI, and enhance their business operations. * * * Leverage AI to Accelerate Your Integration [](https://devx.pax8.com/docs/introduction#leverage-ai-to-accelerate-your-integration) ------------------------------------------------------------------------------------------------------------------------------------- Consider utilizing Generative AI tools like GitHub Copilot, ChatGPT, or other AI models to assist with building your custom integrations. By providing these tools with our OpenAPI specification, available [here](https://devx.pax8.com/openapi) , and details about your own systems, you can receive AI-generated mockups of your integration flow. This approach allows for faster prototyping and reduced manual coding efforts. These tools can suggest optimized API request structures, error handling, and even code snippets that match your systems' architecture, greatly accelerating your integration process. More details are available [here](https://devx.pax8.com/docs/using-ai-to-build-your-integration) . * * * Support [](https://devx.pax8.com/docs/introduction#support) --------------------------------------------------------------- **For Pax8 Partners:** If you're a Pax8 partner seeking assistance with existing integrations, using our API credentials, or have general integration-related questions, please: * Submit a [support ticket](https://app.pax8.com/support-ticket/create) for post-walkthrough assistance. * Directly contact your Pax8 Account Manager for personalized guidance. **For 3rd Party App Builders (Integrating with Pax8):** If you are a developer or company building a third-party application using Pax8's public APIs, or are interested in having your integration listed in the Pax8 Integrations Hub for our partners, please: * Review our comprehensive [Integrator Setup Guide](https://devx.pax8.com/docs/integrator-setup-guide) which outlines the process for building and deploying your app. * For questions specific to the integration process, technical assistance during development, or inquiries about listing your app, you can reach our team at [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#d6bfb8a2b3b1a4b7a2bfb9b8a596a6b7aeeef8b5b9bb) . **For Vendors Listed in the Pax8 Marketplace:** If you are an existing vendor whose products are available in the Pax8 Marketplace and have questions regarding your Marketplace API or related technical support, please email [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#7305161d171c0112031a1b161f033303120b4b5d101c1e) . Updated 2 months ago * * * Ask AI --- # Pax8 Glossary The terms listed below carry specific meaning in the Pax8 ecosphere * **_agent_** A Pax8 partner that is a consultant, recommender, or other intermediary but not directly involved in production as an MSP * **_company_** Any of our partner's customers who are served through the Pax8 platform * **_dependency_** Any components that are required to order a given product * **_endpoint_** A URL designated for use by HTTP requests to the API * **_HTTP request_** A standard HTTP verb used with an API endpoint (URL). It's a function call to the API. ex. GET /products/{productId} * **_MSP_** Managed service provider, the Pax8 partner who directly serves their customers via the Pax8 platform * **_partner_** The MSP or agent whose customers are served via the Pax8 platform * **_product_** A single offering from Pax8 identified by a SKU * **_provisioning_** The process of setting up a product for use by a customer, and configuring it to conform to specifications in the order * **_response codes_** Standard HTTP result that describes the result of a given request to the API * **_resource_** In the context of an API, resource typically synonymous with an API endpoint or group of endpoints * **_subscription_** The subscription object defines the customer's commitment to a service * **_self service_** Refers to a company whose end-users are allowed to access the Portal directly. End-users are not currently permitted API access * **_token_** A character string that gives you access to the API * **_vendor_** Third-party provider of products or services * **_invoice_** A summation of amounts due for products or services * **_invoice item_** A break down of an amount due for a product or service * **_usage summary_** A summation of amounts due for usage based products or services * **_usage line_** A break down of an amount due for a usage based product or service. Tied directly to a usage summary Updated almost 2 years ago * * * Ask AI --- # Integrated MSP Apps At Pax8, we understand the unique challenges and opportunities faced by our Managed Service Provider (MSP) partners. We've cultivated a rich ecosystem of trusted vendors who have built powerful integrations designed specifically to help you: * **Grow your business:** Expand service offerings and unlock new revenue streams. * **Reduce risk:** Enhance security, compliance, and operational resilience. * **Increase operational efficiency:** Automate workflows, streamline processes, and save valuable time. These pre-built integrations cover a wide array of common use cases vital to your MSP business, including: * **Billing & Invoicing** * **Ordering & Provisioning** * **Quoting** * **Subscription Management** * ...and many more! How to Discover and Connect Integrated MSP Apps: [](https://devx.pax8.com/docs/integrated-msp-apps#how-to-discover-and-connect-integrated-msp-apps) ------------------------------------------------------------------------------------------------------------------------------------------------------- To explore these valuable applications and see how they can meet your specific business needs, visit the Pax8 Integrations Hub within your Partner Portal: [**Explore Apps in the Pax8 Integrations Hub**](https://app.pax8.com/integrations/apps) In the Integrations Hub, you can: * **Review Applications:** Browse detailed information about each available integrated MSP app. * **Access App Websites:** Click through to the vendor's dedicated site to learn more about their solution and initiate their specific onboarding or purchase process. * **Secure Authorization:** Once you've engaged with the vendor, you'll be guided through a secure OAuth2 authorization flow. This process allows you to grant the application permission to access your Pax8 data without sharing your Pax8 login credentials directly with the third party. Once an app is securely authorized, it will appear as **"Connected"** within your Pax8 Integrations Hub, indicating it's actively pulling your Pax8 data. You have full control and can manage or revoke access at any time directly from the Hub. Can't find what you're looking for, or prefer to build your own? [](https://devx.pax8.com/docs/integrated-msp-apps#cant-find-what-youre-looking-for-or-prefer-to-build-your-own) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you don't find an integrated MSP app that perfectly fits your requirements, or if you prefer a custom solution, you have the power to build it yourself! Head over to the **"Build Your Own Integration"** section to leverage Pax8's robust APIs, events, and workflows. Updated 2 months ago * * * Ask AI --- # Ordering Products Here are key guidelines for creating companies and placing orders via the Pax8 API. Creating an Active Company [](https://devx.pax8.com/docs/ordering-details#creating-an-active-company) --------------------------------------------------------------------------------------------------------- Before creating an order for a Company, the Company must be in an **Active** status. Upon initial creation, a Company is placed into an **Inactive** status. To activate the Company, you must add one or more contacts that fulfill all **primary** contact constraints. A Company is required to have a **primary** Contact for each Contact Type ("Admin", "Billing", "Technical"). One contact designated as **primary** for all three types is sufficient to meet this requirement. Placing Orders [](https://devx.pax8.com/docs/ordering-details#placing-orders) --------------------------------------------------------------------------------- ### Future-Dated Scheduled Orders [](https://devx.pax8.com/docs/ordering-details#future-dated-scheduled-orders) Currently, the Pax8 API **does not support** future-dated scheduled orders (e.g., placing an order today that activates in 10 days). While this ability is supported via the Pax8 platform interface, API users must use a workaround. **Workaround:** To handle this in your system, you can: * Place the order immediately when you receive it (instead of waiting until you need it). * Alternatively, build logic into your system to trigger the order _once the desired date/time has passed_. This may involve running a cron job or background service to check and place the order at the specified time. **Endpoint:** [Create Order](https://devx.pax8.com/reference/createorder) Placing Test Orders [](https://devx.pax8.com/docs/ordering-details#placing-test-orders) ------------------------------------------------------------------------------------------- To test your ordering integration without creating billable data, you can use the `isMock` query parameter. The `create order` endpoint takes an optional **`?isMock=true`** parameter. When used, the API will validate your entire order payload. * If the order is **invalid**, the API will return an error. * If the order is **valid**, the API will return a success response, but the order **will not be placed** and no data will be created in the Pax8 system. Updated 4 days ago * * * Ask AI --- # Understanding Usage Products Pax8 has two types of products when it comes to billing unit of measure: 1) seat or device based products, and 2) usage based products. Seat or device based products are billed per computer or device the software is installed on. They are generally billed in advance and billing can be estimated through software price per seat multiplied by cost per seat. An example would be Microsoft Office. Usage based products are billed based on amount of something used. They are generally billed after usage happens so what we refer to as an arrears based product. An example would be Microsoft Azure. How to Identify Usage Based Products? [](https://devx.pax8.com/docs/understanding-usage-products#how-to-identify-usage-based-products) ------------------------------------------------------------------------------------------------------------------------------------------ The "unit of measure" and "type" fields can be used to identify usage based products. Calling our pricing endpoint: [https://devx.pax8.com/reference/findpricingbyproductid](https://devx.pax8.com/reference/findpricingbyproductid) and looking for unit of measure that is noted as X and type that is noted as Y can identify How Usage is Captured & Billing Complications [](https://devx.pax8.com/docs/understanding-usage-products#how-usage-is-captured--billing-complications) ---------------------------------------------------------------------------------------------------------------------------------------------------------- Pax8 vendors that offer usage products via the Pax8 marketplace, send usage reporting to Pax8 on a periodic basis. This usage is then queryable by Pax8 partners. Most times the breakdown of usage by company from a given Pax8 vendor is not the same as how a Pax8 partner sets up companies on the Pax8 side. Therefore Pax8 partners must go into the Pax8 portal and do a one time linking of Pax8 companies to vendor entity/companies. This should only be a one time process and can be done by partners by going into the Pax8 app, navigating to the usage summaries section, and clicking on the three dots at the end of a given usage summary row. That will create a link between the vendor entity and the Pax8 company. Pax8 partners will need to do this anytime they have a new vendor entity or if new usage vendors are purchased via the Pax8 marketplace. The only product exception to this requirement for manual linking between vendor entities and Pax8 companies is Azure which should already have accurate links in place due to tenant id mappings. If a Pax8 partner has not mapped vendor entities to Pax8 companies in the Pax8 app, all usage data for a given vendor will show up at the partner level making correct billing very difficult. Public Usage Endpoints for Partners [](https://devx.pax8.com/docs/understanding-usage-products#public-usage-endpoints-for-partners) --------------------------------------------------------------------------------------------------------------------------------------- There are two usage endpoints that partners can use to monitor mid month usage for usage based products. The first allows you to pull usage summaries which are high level usage details for Pax8 products: [https://devx.pax8.com/reference/findsubscriptionusagesummaries](https://devx.pax8.com/reference/findsubscriptionusagesummaries) . The second allows you to pull more granular usage details or line items for a given usage summary: [https://devx.pax8.com/reference/findusagelines](https://devx.pax8.com/reference/findusagelines) Although usage summaries are also available in the Pax8 portal, they differ from data available via our endpoints because you can't pull historic usage summaries via the API endpoints (only current calendar month). Further, end of month invoice line items can also be used to monitor end of month usage for usage products: [https://devx.pax8.com/reference/findpartnerinvoiceitems](https://devx.pax8.com/reference/findpartnerinvoiceitems) Updated over 1 year ago * * * Ask AI --- # REST API Fundamentals If you're new to REST (Representative State Transfer), you'll find abundant material across the web explaining the underlying concepts. But **you don't need to understand all the theory and details behind REST just to use the Pax8 API**. REST isn't a technology or even a specification -- it's a design pattern that ensures your client and the API platform remain loosely coupled. The API is language independent; meaning, you can develop your client in a preferred language. Most languages offer libraries specifically aimed at helping to manage and send HTTP requests. What do API requests do? [](https://devx.pax8.com/docs/apisforbeginners#what-do-api-requests-do) ---------------------------------------------------------------------------------------------------- Saying an API is RESTful implies a few simple things: * **API calls perform CRUD functions** Your client interacts with the API as it would a database, with simple CRUD (**C**reate, **R**ead, **U**pdate, **D**elete) operations. * **API calls are made via HTTP requests** Those CRUD operations are implemented in the Pax8 API as simple HTTP requests (GET, POST, PUT, and DELETE) your client makes to a specified, published URL * **Really, REST is just CRUD** Like a database, the API just lets you read, write, update, and delete data. (Using those HTTP requests). Those are the basics. Like a database, the server maintains no state information about your client or user interface. But that doesn't mean there's no logic on the server side, only that your client doesn't need to worry about it. A good example of this is when you create an order (using POST with the orders endpoint). For your client-side code, that's just like creating an order record in the database. The server handles all the logistics of provisioning based on the parameters you sent. How do I format requests? [](https://devx.pax8.com/docs/apisforbeginners#how-do-i-format-requests) ------------------------------------------------------------------------------------------------------ The [API Resource Reference](https://devx.pax8.com/reference) below provides the necessary information to make HTTP requests -- the request verb to use (GET, PUT etc.), the URL (endpoint) to use, and the data parameters you must send to return the data you want back -- orders, product info, subscriptions, and so on. Updated 4 months ago * * * Ask AI --- # Integrator Setup Guide Welcome to the Pax8 Integrator Program! This guide walks you through the steps to get started with building and publishing your integration using Pax8 APIs and events. * * * 1\. Initial Contact [](https://devx.pax8.com/docs/integrator-setup-guide#1-initial-contact) ----------------------------------------------------------------------------------------------- To begin, email **[\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#b0d9dec4d5d7c2d1c4d9dfdec3f0c0d1c8889ed3dfdd) ** with the following information: * **Full Name** of the primary contact * **Email Address** (preferably a distribution list if multiple users need access) * **Company or Integration Name** (as it should appear in the Pax8 Integrations Hub that will be visible to Pax8 partners) Once received, we’ll provision access to the **Pax8 Integrator Portal**. * * * 2\. Access the Integrator Portal [](https://devx.pax8.com/docs/integrator-setup-guide#2-access-the-integrator-portal) ------------------------------------------------------------------------------------------------------------------------- Once your account is created, you’ll receive credentials to log into the Integrator Portal. This portal provides: * **Sandbox Environment**: Includes mock data for testing your integration. * **OAuth Setup Tools**: Configure your [OAuth 2.0 flow](https://devx.pax8.com/docs/developingdelegationapplications) to allow Pax8 partners to authorize your app. * **Vendor Profile Editor**: Fill out your company’s profile, which will be displayed in the Pax8 Integrations Hub to partners. * * * 3\. Build Your Integration [](https://devx.pax8.com/docs/integrator-setup-guide#3-build-your-integration) ------------------------------------------------------------------------------------------------------------- You’ll use Pax8’s public APIs and events to build your integration. Key resources include: * **API Documentation**: [https://devx.pax8.com/docs/introduction](https://devx.pax8.com/docs/introduction) * **Common Workflows**: [https://devx.pax8.com/recipes](https://devx.pax8.com/recipes) * **Authentication Guide**: [https://devx.pax8.com/docs/developingdelegationapplications](https://devx.pax8.com/docs/developingdelegationapplications) Use the sandbox credentials to test your integration before going live. * * * 4\. Test and Validate [](https://devx.pax8.com/docs/integrator-setup-guide#4-test-and-validate) --------------------------------------------------------------------------------------------------- Once your OAuth flow and API calls are working in the sandbox, you can: * Validate your integration with real-world scenarios * Confirm that your app can authenticate Pax8 partners and access their data securely * Ensure your vendor profile is complete and accurate * * * 5\. Go Live and Get Discovered [](https://devx.pax8.com/docs/integrator-setup-guide#5-go-live-and-get-discovered) --------------------------------------------------------------------------------------------------------------------- After successful testing, please email us at [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#b1d8dfc5d4d6c3d0c5d8dedfc2f1c1d0c9899fd2dedc) and let us know that your vendor profile is complete, OAuth is configured for partner authorization in your app and you've successfully onboarded a few test users. We'll then make your integration live so that: * Your integration will be listed in the **Pax8 Integrations Hub**, visible to over 40,000 Pax8 partners * Partners can discover and link to your integration page directly from within the Pax8 platform * * * 6\. Support and Troubleshooting [](https://devx.pax8.com/docs/integrator-setup-guide#6-support-and-troubleshooting) ----------------------------------------------------------------------------------------------------------------------- If you encounter issues: * Check the [https://devx.pax8.com/changelog](https://devx.pax8.com/changelog) * Reach out to [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#5d343329383a2f3c293432332e1d2d3c2565733e3230) for help with sandbox access, API behavior, or portal issues Updated 3 months ago * * * Ask AI --- # Using Pax8's APIs Here are some guidelines for getting started with Pax8's APIs: 1. Start by getting your API credentials from the **Pax8 Integrations Hub** in the Pax8 app. Follow these steps: 1. Navigate to [Pax8](https://app.pax8.com/) and **Login**. 2. In the left navigation menu, go to **Settings > Integrations**. 3. Click on the **API Keys** box at the top, or navigate to [https://app.pax8.com/integrations/credentials](https://app.pax8.com/integrations/credentials) . 4. Click the button labeled **\+ Create API credential**. 5. Give your application a descriptive name (e.g., "Internal Automation," or the name of a specific system) and click **Save**. * **Important Note:** These API credentials are intended for your internal use only and should **never** be shared with third-party systems. If a third-party application requires access to your Pax8 data, they should integrate using our secure [OAuth 2.0 delegation flow](https://devx.pax8.com/docs/developingdelegationapplications) . 6. Once created, you will see a **cURL example**. Click the **Copy to clipboard** icon to copy this example. 2. Then use our documentation site or your own API client to generate requests. * Use the copied cURL command with a tool like [Postman](https://www.postman.com/) or your terminal to make a request to our [Access Token endpoint](https://devx.pax8.com/reference/createaccesstoken) and retrieve your API **Access Token**. This token will be used to authenticate your subsequent API calls. * Try logging in to this documentation site with your Pax8 credentials, and you can make calls directly from the API reference and see a history of API calls. Formatting Requests [](https://devx.pax8.com/docs/public-api-details#formatting-requests) --------------------------------------------------------------------------------------------- Starting with a simple `GET` request is the easiest way to confirm connectivity to the API, verify authentication, and receive data. You can try this directly by logging into this documentation site with your Pax8 credentials and making calls from the API reference. ### Example Headers for Requests [](https://devx.pax8.com/docs/public-api-details#example-headers-for-requests) When making API requests, you'll commonly use the following headers: * `Content-Type`: `application/json` * `Authorization`: `Bearer ${accessToken}` The `${accessToken}` value is the JWT you obtain from the createAccessToken request within the Pax8 Integrations Hub. Dynamic Data [](https://devx.pax8.com/docs/public-api-details#dynamic-data) ------------------------------------------------------------------------------- Be aware that some endpoints, such as Product Dependencies, Provisioning Details, and Pricing, return dynamic data that changes periodically. It is recommended to fetch this data each time you need it rather than storing it. Pagination [](https://devx.pax8.com/docs/public-api-details#pagination) --------------------------------------------------------------------------- All Pax8 API endpoints that return lists support pagination, allowing you to retrieve results in smaller, manageable sections. Refer to the specific endpoint documentation for field names and conventions. **Counting Nuances:** * Page numbers typically start at `0`. * Totals like `size`, `totalElements`, and `totalPages` usually start at `1`. For example, to retrieve the first 10 orders: Bash `curl https://sample.pax8.com/order?limit=10&page=0` You can expect a response similar to: JSON `{ "content": [ { ... }, ... ], "page": { "size": 10, "totalElements": 100, "totalPages": 10, "number": 0 } }` API Rate Limits [](https://devx.pax8.com/docs/public-api-details#api-rate-limits) ------------------------------------------------------------------------------------- To ensure fair usage and maintain stability, Pax8 APIs are subject to rate limiting. The current limit is **1000 successful calls per minute**. Exceeding this will result in an HTTP `429` error until the rate limit window resets. To request a rate limit increase, please email [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#b3daddc7d6d4c1d2c7dadcddc0f3c3d2cb8b9dd0dcde) . API Status [](https://devx.pax8.com/docs/public-api-details#api-status) --------------------------------------------------------------------------- You can monitor the real-time status of the Pax8 Partner API and subscribe for updates at [status.pax8.com](https://status.pax8.com/) . The relevant component will be labeled as "Partner API". Updated 2 months ago * * * Ask AI --- # 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)** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#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:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#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:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#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)** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#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:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#steps-1) 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:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#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:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#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:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#references) --------------------------------------------------------------------------------------------------- * **Pax8 API OpenAPI specs to get help form AI:** [https://devx.pax8.com/openapi/](https://devx.pax8.com/openapi/) * **Pax8 changelog for vendorSubscriptionId addition:** [https://devx.pax8.com/changelog/partner-direct-microsoft-subscription-mapping-added-to-subscription-api](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](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](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](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](https://learn.microsoft.com/en-us/entra/identity/users/licensing-service-plan-reference) * * * **Summary Table:** [](https://devx.pax8.com/docs/microsoft-subscription-reconciliation#summary-table) --------------------------------------------------------------------------------------------------------- | Pax8 Field | Microsoft Graph Field | Endpoint | Notes | | --- | --- | --- | --- | | `vendorSubscriptionId` | `commerceSubscriptionId` | `/directory/subscriptions` | Use for mapping subscriptions | | `productId` (Pax8) | `skuId` (Graph) | `/subscribedSkus` | Use for mapping products/SKUs | | `externalId` (Pax8) | _Tenant ID_ | `/organization/{tenantId}` etc. | Use for tenant-level queries | Updated about 2 months ago * * * Ask AI --- # CORS Pax8 does not AllowList any Cross Domain requests at this time. If you experience CORS issues, we recommend creating a CORS proxy or other industry standard approach. CORS [](https://devx.pax8.com/docs/cors#cors) ------------------------------------------------- CORS (Cross-Origin Resource Sharing) is a security feature implemented by web browsers to control how web pages in one domain can request and interact with resources from another domain. It is designed to prevent malicious websites from making unauthorized requests to other domains on behalf of the user. CORS involves both server-side configuration and client-side handling. * [Client Side](https://devx.pax8.com/docs/cors#client-side) * [Server Side](https://devx.pax8.com/docs/cors#server-side) Client-side: [](https://devx.pax8.com/docs/cors#client-side) ---------------------------------------------------------------- When making a cross-origin request (i.e., a request from a different domain), the client (usually a web browser) must include certain headers in the HTTP request to enable CORS. Here are some common headers that API clients must send for CORS to work: 1. `Origin`: The client includes an "Origin" header in the HTTP request, indicating the origin (protocol, domain, and port) of the web page making the request. For example: `Origin: https://example.com` 2. `Preflight Request Headers`: For certain types of requests (e.g., those with specific HTTP methods like PUT or DELETE, or custom headers), a preflight request is sent by the browser before the actual request. The client must send headers like "Access-Control-Request-Method" and "Access-Control-Request-Headers" to specify the intended method and headers for the main request. For example:`Access-Control-Request-Method: PUT Access-Control-Request-Headers: Authorization, Content-Type` 3. `Credentials (with appropriate credentials header)`: If the request includes credentials (e.g., cookies, HTTP authentication), the client needs to set the "withCredentials" property to "true" and include the "Credentials" header. For example:`withCredentials: true` Server-Side: [](https://devx.pax8.com/docs/cors#server-side) ---------------------------------------------------------------- On the server, CORS is configured to allow or deny cross-origin requests. It checks the "Origin" header from the client and responds with appropriate headers to grant or deny access. Some of the server-side response headers include: 1. `Access-Control-Allow-Origin`: This header indicates which origin is allowed to access the resource. It can be set to a specific origin or "\*" to allow any origin. For example:`Access-Control-Allow-Origin: https://example.com` 2. `Access-Control-Allow-Methods`: This header indicates which HTTP methods are allowed for the resource. For example:`Access-Control-Allow-Methods: GET, POST, PUT, DELETE` 3. `Access-Control-Allow-Headers`: This header indicates which HTTP headers are allowed for the resource. For example:`Access-Control-Allow-Headers: Authorization, Content-Type` 4. `Access-Control-Allow-Credentials`: This header indicates whether the resource supports credentials (e.g., cookies, HTTP authentication). For example:`Access-Control-Allow-Credentials: true` In summary, CORS is a mechanism that allows controlled access to resources on a different domain. API clients must send specific headers like "Origin" and, in some cases, preflight request headers, while servers must respond with appropriate "Access-Control-Allow-\*" headers to enable cross-origin requests. This ensures secure communication between web applications from different origins. Example of valid CORS request with headers:\` [](https://devx.pax8.com/docs/cors#example-of-valid-cors-request-with-headers) -------------------------------------------------------------------------------------------------------------------------------- `const express = require('express'); const app = express(); // Middleware to enable CORS app.use((req, res, next) => { res.header('Access-Control-Allow-Origin', '*'); // Allow requests from any origin res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept'); next(); }); app.get('/api/data', (req, res) => { res.json({ message: 'This is a public resource' }); }); app.listen(3000, () => { console.log('Server listening on port 3000'); });` The above example is a valid CORS request because, we've added a middleware that sets the Access-Control-Allow-Origin header to allow requests from any origin (\*). This allows frontend applications hosted on different domains to make requests to http://localhost:3000/api/data without encountering CORS errors. Example of invalid CORS request with headers:\` [](https://devx.pax8.com/docs/cors#example-of-invalid-cors-request-with-headers) ------------------------------------------------------------------------------------------------------------------------------------ `const express = require('express'); const app = express(); app.get('/api/data', (req, res) => { res.json({ message: 'This is a public resource' }); }); app.listen(3000, () => { console.log('Server listening on port 3000'); });` The above example is an invalid CORS request because By default, Express.js does not enable CORS, so any frontend application hosted on a different domain trying to access http://localhost:3000/api/data will encounter CORS errors in the browser. More info about CORS can be found here: [https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) Updated almost 2 years ago * * * Ask AI --- # Subscription Management This guide covers how to manage existing subscriptions, including understanding their status and making changes to quantity or term. Understanding Subscription Status [](https://devx.pax8.com/docs/subscription-management#understanding-subscription-status) ------------------------------------------------------------------------------------------------------------------------------ The `status` field on subscription endpoints provides insight into the provisioning state. Here is a breakdown of common statuses: ### Actively Used: [](https://devx.pax8.com/docs/subscription-management#actively-used) * **Active** - An active subscription * **Cancelled** - A cancelled subscription * **Converted** - When a trial is converted to a paid subscription. * **PendingManual / PendingAutomated** * Both of these display as "Provisioning" in the UI. This means the subscription record has been created, but the provisioning task is not yet closed. * The distinction is whether the provisioning task is fully automated or if a manual action is required by our service delivery team. * **NOTE:** This status can sometimes get "stuck" if service delivery manually provisioned the service but the task was not closed (or was skipped). It does not _always_ mean the service wasn't provisioned in the vendor's system. * **PendingCancel** * This means the subscription has been cancelled (and has an `endDate`), but deprovisioning has not yet occurred. * This status was used more frequently in the past when we scheduled future end dates. Now, an `endDate` is typically added to a subscription at the time a cancel order is received. * **Trial** - A trial subscription. Trials are created with an end date so looking at the end date will help determine if it is active. ### Rarely Used: [](https://devx.pax8.com/docs/subscription-management#rarely-used) * **PendingActivation** * This status is no longer used. It was for older vendor models where hardware shipment confirmation was required before activating the subscription. * **Activated** - This is related to the PendingActivation status that is also no longer used * **WaitingForDetails** * This should not appear for most partners. It means provisioning details were missing when the subscription attempted to provision. We have validation to prevent this, so it would likely only occur due. to internal manual actions bypassing validation. > **IMPORTANT: Billing and Subscription Status** > > Subscription `status` currently has **no impact on billing**. We bill subscriptions based on the subscription's **start and end dates**. This means that if there are provisioning delays, it is possible for billing to occur for a service that has not yet been fully provisioned in the vendor's system. Future-Dated Subscription Changes [](https://devx.pax8.com/docs/subscription-management#future-dated-subscription-changes) ------------------------------------------------------------------------------------------------------------------------------ ### Future-Dated Cancellations [](https://devx.pax8.com/docs/subscription-management#future-dated-cancellations) Cancelling subscriptions at a future date **is supported** via the Pax8 API. You can schedule a future cancellation via the following endpoint: * **Endpoint:** [Cancel Subscription](https://devx.pax8.com/reference/delete_subscriptions-subscriptionid) ### Future-Dated Increases in Subscription Quantities [](https://devx.pax8.com/docs/subscription-management#future-dated-increases-in-subscription-quantities) Increasing subscription quantities for a future date is supported in the Pax8 platform interface, but **not directly through the Pax8 API**. **Workaround:** To handle future-dated increases: * You can place the increase in subscription quantity immediately. * Or, your system can be configured to place the subscription quantity increase once the specified date/time has passed. * **Endpoint:** [Update Subscription - Increase Quantity](https://devx.pax8.com/reference/updatesubscription) ### Future-Dated Decreases in Subscription Quantities [](https://devx.pax8.com/docs/subscription-management#future-dated-decreases-in-subscription-quantities) Support for future-dated subscription quantity decreases varies by product type and has specific limitations. * **For Non-Microsoft NCE licenses:** Decreases are possible via the Pax8 platform interface, but **not via the API**. * **For Microsoft NCE licenses:** Decreases are not supported via the Pax8 app or API _except during the renewal window_. **Workaround for Non-Microsoft NCE Licenses:** * You can place the decrease in subscription quantity immediately (if allowed by the product). * Or, configure your system to place the subscription decrease after the scheduled date/time. **Workaround for Microsoft NCE Licenses:** For Microsoft NCE licenses, subscription quantity decreases can **only be processed after the subscription has renewed**. 1. Store the subscription’s `commitmentTermEndDate` in your system. 2. Wait for the renewal to process (e.g., 24 hours after the renewal date). 3. Pass the API call to decrease subscription quantity _after_ the renewal is complete. * **Endpoint:** [Update Subscription - Decrease Quantity](https://devx.pax8.com/reference/updatesubscription) **Notes for API Users:** * **NCE Products:** The decrease will only be accepted post-renewal. You must store and manage subscription end dates to track when a quantity decrease can be processed via the Pax8 API. * **Non-NCE Products:** Future-dated decreases are possible via the Pax8 platform interface but not the API. Make sure to handle these decreases with a similar time-check mechanism as suggested for orders and increases. Automating Workflows with Subscription Events [](https://devx.pax8.com/docs/subscription-management#automating-workflows-with-subscription-events) ------------------------------------------------------------------------------------------------------------------------------------------------------ To build a more robust and responsive integration, we highly recommend using **Subscription Events**. Instead of polling for changes, you can subscribe to events to automate workflows in real-time as changes occur. Each event corresponds to a **Completed Line Item**—the atomic transaction that drives billing and provisioning—and includes a `type` field that identifies the nature of the change. By filtering on these types, you can build powerful, automated responses. **Common Use Cases:** * **Trigger Onboarding:** Use the **`New`** or **`TrialConvert`** types to automatically kick off your customer onboarding or welcome-email workflow. * **Automate Billing:** Use **`Change`** (for seat increases/decreases) or **`Renewal`** to automatically update records in your internal billing system, ensuring quantities and term dates are always accurate. * **Handle Upgrades:** Filter for **`ChangeProduct`** or **`ChangePartial`** to log and manage subscription upgrades or downgrades. * **Manage Churn:** Use the **`Cancel`** type to trigger a de-provisioning process, notify an account manager, or start a customer-feedback workflow. These are just a few examples. For a complete list of all event types and detailed integration guides, please see the [Subscription Events page](https://devx.pax8.com/docs/subscription-events-completed-line-items) . Updated 5 days ago * * * Ask AI --- # Starter Workflows Jumpstart your Pax8 integrations with our collection of starter [workflows](https://devx.pax8.com/recipes) . These pre-built templates offer practical examples of common partner scenarios, empowering you to quickly review, adapt, and customize solutions for your unique business needs. Updated 4 months ago * * * Ask AI --- # Authentication The Pax8 API authenticate requests using [OAuth 2.0](https://oauth.net/2/) . You'll be given a **client\_id** and a **client\_secret** to authenticate with the API. Once you have these, you'll need to request a token that can be used when making API requests. Access Tokens retrieved will have a time to live of one day. You should not need to request a new access token before every request. NOTE: Although we keep referring to HTTP standards, the literal syntax of all requests to the API _must_ use HTTPS. API requests NOT made through HTTPS will fail. For Partners [](https://devx.pax8.com/docs/authentication#for-partners) --------------------------------------------------------------------------- Once you request your initial API keys via the Pax8 app, your API keys provide full access to all public APIs which includes ordering, invoice management, creating companies, etc. Please use caution in sharing these keys with others. Don't paste them in cleartext to source code, customer code, or shared spaces. Also these should not be provided to any 3rd party platforms. 3rd party platforms are required to use our [Delegated oauth flow](https://devx.pax8.com/docs/usingdelegationapplications) to get partner authorization. **Make sure to use an`audience` of `https://api.pax8.com` when getting a token.** For Integrators [](https://devx.pax8.com/docs/authentication#for-integrators) --------------------------------------------------------------------------------- If you manage a 3rd party application and would like to pull Pax8 partner data via our public apis, you will need to use our [Delegated oauth flow](https://devx.pax8.com/docs/usingdelegationapplications) to get partner authorization. Please reach out to [\[email protected\].](https://devx.pax8.com/cdn-cgi/l/email-protection#f79e998392908596839e989984b787968fcfd994989ad9) Let us know the app you’d like to integrate, your use cases and any known Pax8 partners that are using your app and would be interested in your intended integration. We’ll reach out with API keys and access to a sandbox environment you can use. For Marketplace Vendors [](https://devx.pax8.com/docs/authentication#for-marketplace-vendors) ------------------------------------------------------------------------------------------------- If Pax8 sells your product in our marketplace, obtain your `Client Id` and `Client Secret` from your Pax8 Contact. Generate a token. Replace `` and `` in the example below with your credentials. **Make sure to use an `audience` of `api://provisioning` when getting a token to use with provisioning endpoints. Conversely, make sure to use an `audience` of `api://usage` when requesting a token to use with usage endpoints** ### Example [](https://devx.pax8.com/docs/authentication#example) Make sure to substitute in your client\_id, client\_secret and appropriate audience when creating access tokens: cURL `curl --request POST \ --url https://api.pax8.com/v1/token \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "audience": "api://provisioning", "grant_type": "client_credentials", "client_id": "", "client_secret": "" } '` Token endpoint response example: JSON `{ "access_token": "", "scope": "vendorSimulation:provisioning", "expires_in": 86400, "token_type": "Bearer", "expires_at": "2024-12-20T17:53:50.460+00:00" }` 3. Use the token to call the API. Replace `` in the example below with your token cURL `curl --request GET --url https://api.pax8.com/v2/provision-requests \ --header 'content-type: application/json' \ --header 'Authorization: Bearer '` Updated 6 months ago * * * Ask AI --- # Pax8 Partner Authorization via OAuth2 This guide is intended for third-party application developers who want to integrate with Pax8's public APIs on behalf of Pax8 partners. If you're a Pax8 partner looking to use third-party applications, please review [this guide](https://devx.pax8.com/docs/usingdelegationapplications) . ### What is Delegated Authorization? [](https://devx.pax8.com/docs/developingdelegationapplications#what-is-delegated-authorization) Delegated Authorization is the process of obtaining a Pax8 Partner's consent to call Pax8's Public APIs on their behalf. Before you can access any partner data, the partner must explicitly provide consent through the [OAuth2 Authorization Code Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) flow. When a partner authorizes your application, they will see a consent screen similar to this: ![](https://files.readme.io/9303383-Screenshot_2023-12-19_at_10.09.29_AM.png) Getting Started [](https://devx.pax8.com/docs/developingdelegationapplications#getting-started) --------------------------------------------------------------------------------------------------- ### 1\. Initial Setup [](https://devx.pax8.com/docs/developingdelegationapplications#1-initial-setup) 1. **Contact Pax8**: Send an email to `[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ` to discuss your integration use case. 2. **Receive Credentials**: Pax8 will review your use case and provide: * Sandbox credentials * Vendor Portal access * API keys * Client ID and Client Secret for OAuth ### 2\. Implementation Overview [](https://devx.pax8.com/docs/developingdelegationapplications#2-implementation-overview) Pax8 follows the standard OAuth2 Authorization Code flow with a few specific requirements. If you're familiar with OAuth2, you can likely adapt your existing implementation with minimal changes. The main Pax8-specific requirement is the mandatory `audience` parameter. OAuth2 Flow Implementation [](https://devx.pax8.com/docs/developingdelegationapplications#oauth2-flow-implementation) ------------------------------------------------------------------------------------------------------------------------- ### Step 1: Create an Integration Page [](https://devx.pax8.com/docs/developingdelegationapplications#step-1-create-an-integration-page) Build a page in your application where Pax8 partners can: * Learn about your Pax8 integration * Initiate the authorization process via an "Integrate with Pax8" button ### Step 2: Request Authorization [](https://devx.pax8.com/docs/developingdelegationapplications#step-2-request-authorization) We recommend using Auth0 libraries for your preferred programming language: [API docs](https://developer.auth0.com/resources) The following is a simplified example showing how to go about this: When a partner clicks your integration button, redirect them to the Pax8 authorization endpoint: #### Authorization Endpoint [](https://devx.pax8.com/docs/developingdelegationapplications#authorization-endpoint) `https://login.pax8.com/authorize` #### Required Parameters [](https://devx.pax8.com/docs/developingdelegationapplications#required-parameters) | Parameter | Value | Description | | --- | --- | --- | | `response_type` | `code` | Specifies that you're using the authorization code flow | | `client_id` | `` | The client ID provided by Pax8 | | `scope` | `Manage:Pax8Data` | The permissions you're requesting (see Supported Scopes section) | | `redirect_uri` | `` | The URL where Pax8 will send the authorization code (must be pre-registered with Pax8) | | `audience` | `https://api.pax8.com` | **Required** - Specifies that you're requesting access to the Pax8 API | #### Security Parameters [](https://devx.pax8.com/docs/developingdelegationapplications#security-parameters) | Parameter | Description | | --- | --- | | `state` | A random value you generate to prevent CSRF attacks. Store this value in your session and verify it when Pax8 redirects back to your application. | | `nonce` | A random value used to prevent replay attacks. This value will be included in the ID token if you request the `openid` scope. | #### Example Authorization URL [](https://devx.pax8.com/docs/developingdelegationapplications#example-authorization-url) `https://login.pax8.com/authorize? response_type=code& client_id=& scope=Manage:Pax8Data& state=& redirect_uri=& nonce=& audience=https://api.pax8.com` ### Step 3: Handle the Authorization Response [](https://devx.pax8.com/docs/developingdelegationapplications#step-3-handle-the-authorization-response) After authorization, Pax8 redirects to your `redirect_uri` with an authorization code: `https://?code=` 1. Verify that the `state` parameter matches the value you sent 2. Extract the `code` parameter from the URL ### Step 4: Exchange the Code for Tokens [](https://devx.pax8.com/docs/developingdelegationapplications#step-4-exchange-the-code-for-tokens) Make a POST request to exchange the authorization code for tokens: **Endpoint:** `POST https://login.pax8.com/oauth/token` **Headers:** Text `Content-Type: application/json` **Request Body:** JSON `{ "grant_type": "authorization_code", "code": "", "client_id": "", "client_secret": "", "redirect_uri": "" }` **Response:** JSON `{ "access_token": "", "id_token": "", // Only included if you requested the 'openid' scope "refresh_token": "", // Only included if you requested the 'offline_access' scope "scope": "", "expires_in": 86400, // Token validity in seconds (24 hours) "token_type": "Bearer" }` Token Management [](https://devx.pax8.com/docs/developingdelegationapplications#token-management) ----------------------------------------------------------------------------------------------------- ### Token Lifetimes [](https://devx.pax8.com/docs/developingdelegationapplications#token-lifetimes) * **Access Token**: Valid for 24 hours (86400 seconds) * **Refresh Token**: * Absolute lifetime: 1 year (31,557,600 seconds) * Even with refreshing a token once this time has passed you will be required to have your user re-authenticate. Be sure to have your app configured to alert your user or have them re-submit the authorization page you created in the [Oauth Flow](https://devx.pax8.com/docs/developingdelegationapplications#oauth2-flow-implementation) * Inactivity lifetime: 15 days (1,296,000 seconds) * Each use of the refresh token: * Issues a new refresh token * Invalidates the previous refresh token * Resets the inactivity timer * For security purposes, refresh tokens are rotated - only the most recently issued refresh token is valid. So for every access request a new refresh token will be provided. Save this for future use. ### Refreshing Access Tokens [](https://devx.pax8.com/docs/developingdelegationapplications#refreshing-access-tokens) When an access token expires and if you requested the `offline_access` scope and received a refresh token, you can use it to obtain a new access token when the current one expires: **Endpoint:** `POST https://login.pax8.com/oauth/token` **Request Body:** JSON `{ "grant_type": "refresh_token", "refresh_token": "", "client_id": "", "client_secret": "" }` **Important Notes:** * The refresh token you receive in the response replaces your previous refresh token * Your previous refresh token becomes invalid immediately * Always update your stored refresh token with the new one received in the response * If you attempt to use an old refresh token, the request will fail and you'll need to re-authorize Step 5 API Usage [](https://devx.pax8.com/docs/developingdelegationapplications#step-5-api-usage) ----------------------------------------------------------------------------------------------------- Include the access token in the Authorization header when calling Pax8 APIs: `Authorization: Bearer ` For detailed API documentation, see the [Pax8 API Reference](https://devx.pax8.com/reference/createaccesstoken) . Supported Scopes [](https://devx.pax8.com/docs/developingdelegationapplications#supported-scopes) ----------------------------------------------------------------------------------------------------- | Scope | Description | | --- | --- | | `Manage:Pax8Data` | Access to partner's Pax8 data (orders, subscriptions, contacts, products & invoices). Currently, this is the only data scope available. More granular scopes will be available in the future. | | `email` | Access to the user's email address | | `profile` | Access to basic profile information | | `openid` | When requested, the response will include an ID token with the user's identity | | `offline_access` | When requested, the response will include a refresh token | Sequence Diagram [](https://devx.pax8.com/docs/developingdelegationapplications#sequence-diagram) ----------------------------------------------------------------------------------------------------- ![](https://files.readme.io/05c2d19dc5d5b54fe65caa43b2bc937df417ff9b2f0caa55da8409615dff53c7-AuthorizationCodeFlow.png) Example Implementation [](https://devx.pax8.com/docs/developingdelegationapplications#example-implementation) ----------------------------------------------------------------------------------------------------------------- ### Python Example [](https://devx.pax8.com/docs/developingdelegationapplications#python-example) This example demonstrates how to implement the OAuth2 authorization flow for Pax8 APIs using the Auth0 Python SDK. ### Prerequisites [](https://devx.pax8.com/docs/developingdelegationapplications#prerequisites) Install the required packages: Bash `pip install auth0-python requests` ### Simple OAuth2 Client [](https://devx.pax8.com/docs/developingdelegationapplications#simple-oauth2-client) Python `import time import requests from auth0.authentication import GetToken from urllib.parse import urlencode class Pax8AuthClient: # Pax8 OAuth2 configuration DOMAIN = "login.pax8.com" CLIENT_ID = "YOUR_CLIENT_ID" CLIENT_SECRET = "YOUR_CLIENT_SECRET" REDIRECT_URI = "https://your-app.com/callback" AUDIENCE = "https://api.pax8.com" SCOPE = "Manage:Pax8Data offline_access" def __init__(self): self.access_token = None self.refresh_token = None self.expires_at = 0 self.auth0_client = GetToken(self.DOMAIN) def get_authorization_url(self): """Generate the authorization URL to redirect the user to""" # Build the authorization URL with all required parameters # The Auth0 SDK will handle state parameter automatically params = { 'response_type': 'code', 'client_id': self.CLIENT_ID, 'redirect_uri': self.REDIRECT_URI, 'scope': self.SCOPE, 'audience': self.AUDIENCE } query_string = urlencode(params) authorization_url = f'https://{self.DOMAIN}/authorize?{query_string}' return authorization_url def exchange_code(self, code): """Exchange the authorization code for tokens""" # Exchange the code for tokens using Auth0 SDK token_data = self.auth0_client.authorization_code( client_id=self.CLIENT_ID, client_secret=self.CLIENT_SECRET, code=code, redirect_uri=self.REDIRECT_URI ) self.access_token = token_data.get('access_token') self.refresh_token = token_data.get('refresh_token') self.expires_at = time.time() + token_data.get('expires_in', 86400) return token_data def refresh_token_if_needed(self): """Refresh the access token if it's expired""" if not self.refresh_token: raise ValueError("No refresh token available") if time.time() >= self.expires_at: token_data = self.auth0_client.refresh_token( client_id=self.CLIENT_ID, client_secret=self.CLIENT_SECRET, refresh_token=self.refresh_token ) self.access_token = token_data.get('access_token') self.expires_at = time.time() + token_data.get('expires_in', 86400) # The refresh token might be rotated, so update it if a new one is provided if 'refresh_token' in token_data: self.refresh_token = token_data.get('refresh_token') def call_api(self, endpoint): """Make a request to the Pax8 API (placeholder)""" self.refresh_token_if_needed() # In a real implementation, you would make an actual API call here # This is just a placeholder to show how to use the access token print(f"Calling API endpoint: {endpoint}") print(f"Using access token: {self.access_token[:10]}...") # Example of how you would make the actual API call: # headers = {"Authorization": f"Bearer {self.access_token}"} # response = requests.get(f"https://api.pax8.com{endpoint}", headers=headers) # return response.json() return {"message": "This is a placeholder for the API response"}` ### Minimal Usage Example [](https://devx.pax8.com/docs/developingdelegationapplications#minimal-usage-example) Python `from flask import Flask, request, redirect, jsonify app = Flask(__name__) app.secret_key = "your-secret-key" # Replace with a real secret key ### Create an instance of the Pax8AuthClient auth_client = Pax8AuthClient() @app.route("/login") def login(): """Step 1: Redirect user to Pax8 authorization page""" auth_url = auth_client.get_authorization_url() return redirect(auth_url) @app.route("/callback") def callback(): """Step 2: Handle the callback and exchange code for tokens""" code = request.args.get("code") try: auth_client.exchange_code(code) return "Authorization successful! You can now use the access token to call Pax8 APIs." except Exception as e: return f"Error: {str(e)}", 400 @app.route("/api-example") def api_example(): """Example of calling an API with the access token""" try: # This is just a placeholder - replace with your actual API endpoint result = auth_client.call_api("/your-api-endpoint") return jsonify(result) except Exception as e: return f"Error: {str(e)}", 400 if __name__ == "__main__": app.run(debug=True)` ### Usage Notes [](https://devx.pax8.com/docs/developingdelegationapplications#usage-notes) 1. Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with the credentials provided by Pax8. 2. Update `REDIRECT_URI` to match the callback URL registered with Pax8. 3. This example uses Flask for simplicity, but the `Pax8AuthClient` class can be used with any Python web framework. 4. The `call_api` method is a placeholder - replace it with your actual API calls. 5. The Auth0 Python SDK handles security features like state parameter management automatically. ### Testing Notes [](https://devx.pax8.com/docs/developingdelegationapplications#testing-notes) * **Important**: Your Vendor Portal account cannot be used to test the delegation flow. Only Pax8 Partner accounts will work. * If you are logged into the Vendor Portal ([https://integrations.pax8.com](https://integrations.pax8.com/) ), you must test the login flow in a new browser or incognito window to avoid granting consent with your Integrator account instead of a Partner account. Security Considerations [](https://devx.pax8.com/docs/developingdelegationapplications#security-considerations) ------------------------------------------------------------------------------------------------------------------- 1. Always use HTTPS for all communication. 2. Store client secrets securely and never expose them in client-side code. 3. In production, store tokens securely, not in the session as shown in this example. 4. Use a strong, randomly generated secret key for your Flask application. Support [](https://devx.pax8.com/docs/developingdelegationapplications#support) ----------------------------------------------------------------------------------- If you encounter issues during implementation, please contact `[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ` for assistance. Updated 4 months ago * * * Ask AI --- # Allowlisted IP Addresses for Outgoing Traffic This page serves as the single source of truth for all outgoing IP addresses used by Pax8. The goal is to provide a unified list of IP addresses that can be used by both vendors and partners to allow Pax8 traffic into their networks. Purpose [](https://devx.pax8.com/docs/allowlisted-ip-addresses#purpose) --------------------------------------------------------------------------- The primary purpose of this page is to provide a comprehensive list of outgoing IP addresses that vendors and partners can use to configure their allow-lists. This is particularly important for: * **Vendors** working with Pax8 on provisioning API integrations. * **Partners** using self-hosted ConnectWise as their PSA. Allowlisted IP Addresses [](https://devx.pax8.com/docs/allowlisted-ip-addresses#allowlisted-ip-addresses) ------------------------------------------------------------------------------------------------------------- Add the following IP addresses to your allowlists for outgoing traffic from Pax8 to avoid any disruptions in service. IP Address: 54.166.50.195 34.230.146.81 23.22.220.211 34.196.222.167 44.223.201.101 44.222.10.180 34.224.170.99 44.210.168.210 34.197.194.195 52.45.198.126 54.158.137.11 54.159.159.94 3.215.124.27 3.229.168.253 54.156.115.98 34.236.130.36 Contact Information [](https://devx.pax8.com/docs/allowlisted-ip-addresses#contact-information) --------------------------------------------------------------------------------------------------- If you have any questions or need further assistance, please contact our support team. Updated about 1 year ago * * * Ask AI --- # Response Codes The API uses [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to indicate the success or failure of the API call. All requests return one of these standard HTTP response codes | Id | Meaning | Description | | --- | --- | --- | | `200` | **OK** | Everything worked as expected | | `400` | **Bad Request** | The request was unacceptable and therefore couldn't be processed by API due to bad syntax (wrong data format or missing a required parameter). | | `401` | **Unauthorized** | No valid API key provided | | `403` | **Forbidden** | The API key doesn't have permissions to perform the request | | `404` | **Not Found** | The requested resource doesn't exist | | `422` | **Unprocessable Entity** | The request syntax was correct but an exception was caught in processing | | `429` | **Too Many Requests** | Too many requests hit the API quickly | | `50x` | **Server Errors** | Something went wrong on Pax8 server (These should be rare) | Errors [](https://devx.pax8.com/docs/errors#errors) ------------------------------------------------------- The body of each error response contains JSON in the following format: JSON `{ "type": "Type of error", "message": "Detailed message about the error/possible resolution", "instance": "The path called", "status": 404, "details": [ { "type": "Type of error (optional)", "status": "HTTP Status (optional)", "message": "Detailed message about the error/possible resolution (required)", "instance": "The path called (optional)" } ] }` For example... JSON `{ "type": "NOT_FOUND", "message": "Company Not Found: 3d0617ac-57f6-40e3-951d-e91da47a326b", "instance": "/public/v1/companies/3d0617ac-57f6-40e3-951d-e91da47a326b", "status": 404, "details": [] }` The server will respond with a 400 error in case of incorrect API usage, such as providing data with bad syntax or missing a parameter in the request. This pertains solely to improper API usage and should not be confused with an invalid business entity, etc. Such behavior applies to all APIs in general. **A Bad data format example:** Expected (correct) request data: JSON `{ "companyId": "563beb00-9832-4e1a-9e30-d9e4cd4fc2585" }` Unexpected request data due to bad data format; a wrong syntax JSON: JSON `{ "companyId": 666666 }` **Missing a parameter example:** Expected (correct) request data: JSON `{ "partnerId": "563beb00-9832-4e1a-9e30-d9e4cd4fc2585", "partnerName": "Test Partner", "partnerCity": "Albuquerque" }` Unexpected request data due to missing request parameter (partnerId is missing); a wrong syntax JSON: JSON `{ "partnerName": "Test Partner", "partnerCity": "Albuquerque" }` Both examples of bad syntax will lead to 400 (Bad Request) error response from API like this: 400 API Error - Bad Request - Response example JSON: JSON `{ "type": "BAD_REQUEST", "message": "Api failed to process the request", "instance": "/public/.../", "status": 400, "details": [] }` For Vendor Endpoints [](https://devx.pax8.com/docs/errors#for-vendor-endpoints) ----------------------------------------------------------------------------------- When an error occurs the details map will contain a `supportId`. * This can be provided to Pax8 support when you need to troubleshoot error responses from the API. JSON `{ "type": "invalid-request", "status": 400, "message": "field x must not be blank", "instance": "/example", "details": [ { "supportId": "2f78b0321e2c945293108ded671cba51" } ] }` Updated almost 2 years ago * * * Ask AI --- # Provision Notification Pax8 uses Provision Notification webhooks to notify Provisioners of new Provisioning activity. A Provision Notification webhook should contain all the data you need to complete an provisioning request from Pax8. Configuring Your Webhook [](https://devx.pax8.com/docs/provision-notification#configuring-your-webhook) ----------------------------------------------------------------------------------------------------------- Find out how to customize where we send Provision Notifications and how we authenticate to your API on the [Webhook Configuration](https://devx.pax8.com/docs/webhook-configuration) page. Provision Notification Structure [](https://devx.pax8.com/docs/provision-notification#provision-notification-structure) --------------------------------------------------------------------------------------------------------------------------- * A Provision Notification contains a [Provision Request](https://devx.pax8.com/docs/provision-request) , a [Provision Detail](https://devx.pax8.com/docs/provision-detail) , and a [Provision Attempt](https://devx.pax8.com/docs/provision-attempt) . * Shared Secrets from a Webhook Configuration are sent in HTTP headers. More [here](https://devx.pax8.com/docs/webhook-configuration) * For more information on `isSimulation`, see the testing section of our docs [here](https://devx.pax8.com/docs/provision-simulation-example) JSON `{ "isSimulation": false, "provisionRequest": { "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "NetNew", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }, "provisionDetail": { "id": "5c425efa-60be-4bac-98b4-d3dff9099143", "provisionRequestId": "50f31e66-9a01-43a8-b0f8-14c288bac5da", "details": { "firstName": "John", "lastName": "Doe", "email": "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "changeOfChannel": "Yes" }, "createdDate": "2022-10-03T10:15:30Z" }, "provisionAttempt": { "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9", "provisionDetailId": "8fcf68db-c30e-4f34-b773-bc1631cd1fef", "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41", "status": "Acknowledged", "createdDate": "2022-10-03T10:15:30Z" } }` Null Values [](https://devx.pax8.com/docs/provision-notification#null-values) --------------------------------------------------------------------------------- It's important to note that if any of the values above would be null, the API will omit them from the notification body completely. This rule applies to all requests and responses coming out of the Pax8 API. Where We Send Provision Notifications [](https://devx.pax8.com/docs/provision-notification#where-we-send-provision-notifications) ------------------------------------------------------------------------------------------------------------------------------------- * Pax8 sends each Provision Notification to the URL on the most recent Webhook Configuration configured by a Provisioner. * Each Provision Notification, by way of the `provisionAttempt`, contains a reference to the associated webhook configuration in the `webhookId` field. * For more information about how to configure webhooks see the [Webhook Configuration](https://devx.pax8.com/docs/webhook-configuration) page. Acceptable Status codes [](https://devx.pax8.com/docs/provision-notification#acceptable-status-codes) --------------------------------------------------------------------------------------------------------- * Pax8 **_only_** accepts the following HTTP status codes to acknowledge a Provision Notification: * 200 * 201 * 202 If your url redirects with a 301, you need to adjust your configuration to one that doesn't redirect. Redirects will cause webhook delivery to fail. > 📘 > > Validation and processing of the Provision Notification **should not** be done before the webhook is acknowledged with one of the acceptable status codes. > > > ---------------------------------------------------------------------------------------------------------------------------------------------------------------- All processing and validation should be happening in an asynchronous manner after the lightweight acknowledgement is sent, and the vendor system confirms that they have captured the request into their system. If anything fails during your asynchronous validation process you should respond with a `ProvisionResult` with the status `Fail` and an error message. For example, if the `ProvisionRequest` is missing a required detail for provisioning, the webhook should still be acknowledged with a 200, 201 or 202 code. And then in the subsequent `ProvisionResult`that is sent to Pax8 the the "missing required detail" error would be sent as a failed result. Retries [](https://devx.pax8.com/docs/provision-notification#retries) ------------------------------------------------------------------------- * Status codes not listed above will cause Pax8 to fail the current `ProvisionAttempt` and retry the webhook. * Pax8 will attempt to retry a Webhook delivery 3 times. * We record each webhook delivery as a `ProvisionAttempt` * Pax8 does not accept a `ProvisionResult` for a failed `ProvisionAttempt`. * The Pax8 system waits approximately 15 seconds before retrying Updated 3 months ago * * * Check Out Provisioning Scenarios * [Provisioning Scenarios](https://devx.pax8.com/docs/provisioning-scenarios) Ask AI --- # Subscription Events: Completed Line Items When Pax8 emits **subscription events**, each event corresponds to a **Completed Line Item**—the atomic transaction that drives billing and provisioning. These events allow partners to **automate workflows** such as onboarding, billing updates, renewals, and cancellations. Completed Line Items represent every transaction from subscriptions, arrears billing, and one-time charges. Each event includes a `type` field that identifies the nature of the change. Line Item Types & What They Mean [](https://devx.pax8.com/docs/subscription-events-completed-line-items#line-item-types--what-they-mean) -------------------------------------------------------------------------------------------------------------------------------------------- Use these types to decide which events to subscribe to for automation: * **New** – A new subscription was created (initial entitlement). * **Change** – Mid-term modification (e.g., seat increase/decrease, price updates). * **ChangePartial** – A partial product swap. Related to upgrades/downgrades. * **ChangeProduct** – A full product swap. Related to upgrades/downgrades. * **UpdateRatePlan** – Rateplan change without altering the product. * **SpiffPriceAdjustment** – A promotion or spiff adjustment applied to the line item. * **Renewal** – A subscription commitment term was renewed. * **Cancel** – A subscription was fully canceled. * **Resurrect** – Reactivation of a previously canceled subscription. * **Migration** – Migration of a subscription (e.g., between partners or companies). * **ParentReassignment** – Ownership reassignment to a new parent subscription. * **TrialCreate** – A trial subscription was created. * **TrialConvert** – A trial converted to a paid subscription. * **TrialCancel** – A trial was canceled. * **ArrearsUpload** – Manual arrears line item (manual usage posting). * **RevertToCurrent** – Reverts a pending change back to current state. Important Note on Advanced Topic Filtering [](https://devx.pax8.com/docs/subscription-events-completed-line-items#important-note-on-advanced-topic-filtering) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Please be aware that advanced filtering for event subscriptions (e.g., filtering on specific event properties) is currently **only possible via the API**. This level of granular filtering is **not available** through the standard "Subscribe to Events" UX in the Integrations Hub. To configure advanced filters, developers must use the API endpoints directly: 1. **Discover Topics & Filters:** Use [GET /webhooks/topic-definitions](https://devx.pax8.com/reference/gettopicdefinitions) to retrieve all available topic definitions and the specific filterable conditions for each. 2. **Create or Update Subscriptions with Filters**: 1. Create: Use [POST /webhooks](https://devx.pax8.com/reference/webhooks_create) and include the desired filter configuration within the webhookTopics array when creating a new webhook subscription. 2. Update: To add or replace topics with filters, or to update the filter configuration on an existing topic, use the dedicated topic endpoints (like [POST /webhooks/{id}/topics](https://devx.pax8.com/reference/addwebhooktopic) or [POST /webhooks/{id}/topics/{topicId}/configuration](https://devx.pax8.com/reference/updatewebhooktopicconfiguration) ). Updated 2 days ago * * * Ask AI --- # Using AI to Build Your Pax8 Integration With the rise of Generative AI (GenAI), partners can now streamline their Pax8 API integration process by utilizing tools like GitHub Copilot, OpenAI's ChatGPT, and other GenAI platforms. These AI tools can rapidly mock up integrations, assist with API call construction, and even generate code that fits your specific environment. How to Use AI for Your Integration: [](https://devx.pax8.com/docs/using-ai-to-build-your-integration#how-to-use-ai-for-your-integration) -------------------------------------------------------------------------------------------------------------------------------------------- **1 - Provide the Pax8 OpenAPI Specification** Access our detailed OpenAPI specification [here](https://devx.pax8.com/openapi) . Upload it to the GenAI platform of your choice, such as ChatGPT or Copilot. **2 - Feed Details About Your System** To ensure accurate and optimized code, share details about your environment, including programming languages, database structures, and specific requirements. **3 - Ask for Integration Mockups** Once you've provided the necessary information, prompt the AI to generate an integration flow. Example queries include: * "Generate a sample API call to create an order using the Pax8 API." * "Suggest error handling code for failed subscription updates." * "Write a function that interacts with the Pax8 API to look up invoices." **4 - Review and Customize** Use the AI's mockups as a starting point. Review the generated code and customize it to match your organization's unique needs. Advantages of AI-Assisted Integration: [](https://devx.pax8.com/docs/using-ai-to-build-your-integration#advantages-of-ai-assisted-integration) -------------------------------------------------------------------------------------------------------------------------------------------------- * **Speed**: AI can quickly mock up and generate code, accelerating the development cycle. * **Optimization**: Leverage AI to suggest efficient API request structures, validation logic, and error handling. * **Customization**: With personalized inputs, AI can adjust code recommendations to suit specific technical environments. By incorporating Generative AI tools into your workflow, you can significantly reduce the manual effort involved in building integrations and accelerate your time to market. Learn More [](https://devx.pax8.com/docs/using-ai-to-build-your-integration#learn-more) ------------------------------------------------------------------------------------------- For more details on how to effectively use AI with our API, please visit our [documentation](https://devx.pax8.com/openapi) or contact your Pax8 Account Manager for further assistance. Updated about 1 year ago * * * Ask AI --- # Building AI Agents for Pax8 Are you developing an AI agent and want to enable it to interact seamlessly with the Pax8 platform on behalf of our partners? This guide is for developers and companies, whether you're an existing Pax8 partner or a third-party app builder, looking to offer AI-powered solutions to our extensive partner base. Integrating your AI agent with Pax8 allows partners to automate complex tasks, gain deeper insights, and streamline their operations through natural language interaction. * * * How to Get Started [](https://devx.pax8.com/docs/ai-agents-for-pax8#how-to-get-started) ------------------------------------------------------------------------------------------- To begin building your AI agent integration and make it accessible to Pax8 partners, follow these key steps: 1. **Initial Contact & Account Setup:** Reach out to our integrations team at [\[email protected\].](https://devx.pax8.com/cdn-cgi/l/email-protection#a0c9ced4c5c7d2c1d4c9cfced3e0d0c1d8988ec3cfcd8e) Please include: * The name of your AI application. * The specific tasks or functionalities your AI agent will perform. * Any Pax8 partners currently using your AI who would be interested in this integration. Upon review, we will provide you with an integration account, sandbox credentials, API keys, and access to an OAuth configuration for delegated authorization. 2. **Obtain OAuth Authorization (Delegated Access):** Each Pax8 partner must authorize your AI agent to act on their behalf. Once your integration account is set up, you will configure an OAuth URL to obtain this consent from each partner. This secure process ensures your agent can access Pax8 data without partners sharing their direct login credentials. * For detailed information on implementing delegated OAuth, please review our [comprehensive guide](https://devx.pax8.com/docs/developingdelegationapplications) . 3. **Leverage Our OpenAPI Specification:** Our detailed OpenAPI specification is your agent's blueprint for understanding and interacting with Pax8 APIs. Utilize this specification to help your AI agent understand what API calls to make and when. * Access the OpenAPI specifications [here](https://devx.pax8.com/openapi) . **Using Generative AI Tools for Development:** Accelerate your development by feeding our OpenAPI specification into Generative AI tools like GitHub Copilot, OpenAI's ChatGPT, or other GenAI platforms. * **Upload the Specification:** Provide the OpenAPI document to your chosen GenAI platform. * **Contextualize Your Agent:** Share details about your agent's use cases, conversation flow, environment (e.g., programming languages, database structures), and specific requirements. * **Request Guidance:** Prompt the AI to generate guidance on how your agent should use various Pax8 endpoints. For example: * "How should my agent use the Pax8 API to create an order?" * "What are the best practices for handling subscription updates with the Pax8 API?" * "How can my agent retrieve invoice data using the Pax8 API?" * **Review & Customize:** Use the AI's suggestions as a starting point, then review and customize the generated code or logic to fit your specific needs. * * * Making Your AI Agent Accessible to Pax8 Partners [](https://devx.pax8.com/docs/ai-agents-for-pax8#making-your-ai-agent-accessible-to-pax8-partners) ------------------------------------------------------------------------------------------------------------------------------------------------------- Once your AI agent is developed and thoroughly tested in our sandbox environment: 1. **Create Your Profile Page:** Your integration account includes a profile page. Populate this page with comprehensive details about your AI agent, its capabilities, and benefits. This profile will be visible to all Pax8 partners within the Pax8 Partner App, facilitating discovery and adoption. 2. **Scale Your Solution:** By completing your profile and ensuring your agent is ready, you make it easy for Pax8 partners to discover, understand, and integrate your AI solution, enabling you to scale your agent's reach across the entire Pax8 partner base. Updated 4 months ago * * * Ask AI --- # MCP Server Unlock the power of integrating your Pax8 data with your favorite Large Language Models (LLMs) using the Pax8 MCP Server. This integration allows you to seamlessly access and interact with your Pax8 information through natural language within AI assistants. What is the MCP Server? [](https://devx.pax8.com/docs/mcp-server#what-is-the-mcp-server) -------------------------------------------------------------------------------------------- The Model Context Protocol (MCP) server acts as a secure bridge, enabling AI assistants like Claude, Copilot, and Cursor to access your Pax8 data and perform actions on your behalf. You can learn more about Model Context Protocol, written by Anthropic the makers of Claude, widely adopted across the industry. [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/) Getting Started [](https://devx.pax8.com/docs/mcp-server#getting-started) ----------------------------------------------------------------------------- 1. **Generate a secure MCP token:** Obtain a unique token from your Pax8 Marketplace Intergrations Hub → [https://app.pax8.com/integrations/mcp)](https://app.pax8.com/integrations/mcp)) 2. **Configure your AI Client:** Follow the detailed instructions for your client of choice. 3. **Interact with your Pax8 data using natural language:** Ask questions and initiate actions using simple, intuitive prompts. Supported AI Clients [](https://devx.pax8.com/docs/mcp-server#supported-ai-clients) --------------------------------------------------------------------------------------- Currently, the MCP Server is compatible with: * Cursor * Claude * Copilot * VSCode Available Tools [](https://devx.pax8.com/docs/mcp-server#available-tools) ----------------------------------------------------------------------------- The MCP Server provides access to a variety of tools, allowing you to retrieve specific information and lists from your Pax8 account. Examples include: * Company & Contact Management * Invoices * Order Management * Products * Quoting * Subscriptions (See the full documentation on the [MCP server tab](https://app.pax8.com/integrations/mcp) within the Integrations Hub for a complete list of available tools and example prompts.) Security [](https://devx.pax8.com/docs/mcp-server#security) --------------------------------------------------------------- Your **MCP token** is treated with the highest security standards, featuring end-to-end encryption. You maintain control over which API endpoints are accessible and can revoke access at any time. All actions performed through the MCP Server are fully logged and auditable. **Remember to treat your MCP server token like a password and do not share it publicly.** Feedback [](https://devx.pax8.com/docs/mcp-server#feedback) --------------------------------------------------------------- We value your feedback! If you have any suggestions for improvement, please email us at [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#78151b083808190040561b1715) . Updated about 1 month ago * * * Ask AI --- # Provision Detail A `ProvisionDetail` contains information a user entered at checkout. Pax8 can dynamically add extra provisioning detail data points to enhance the ordering experience as needed. Since this data may change if a user or system discovers incorrect information, a `ProvisionRequest` may have multiple `ProvisionDetail` objects. Each `ProvisionDetail` is immutable and represents a snapshot of the user's information at a specific moment in time. Pax8 creates a new `ProvisionDetail` during: * Initial checkout * Any time a user corrects errors in their checkout information Endpoints [](https://devx.pax8.com/docs/provision-detail#endpoints) ----------------------------------------------------------------------- ### List All Provision Details for a Provision Request [](https://devx.pax8.com/docs/provision-detail#list-all-provision-details-for-a-provision-request) * Retrieves a list of all `ProvisionDetail` objects for a `ProvisionRequest` * [GET /provision-requests/{provisionRequestId}/details](https://devx.pax8.com/reference/getallprovisiondetails) ### Get One Detail for a Provision Request [](https://devx.pax8.com/docs/provision-detail#get-one-detail-for-a-provision-request) * Retrieves one `ProvisionDetail` for a `ProvisionRequest` * [GET /provision-requests/{provisionRequestId}/details/{detailId}](https://devx.pax8.com/reference/getoneprovisiondetail) ### Get Latest Detail for an Provision Request [](https://devx.pax8.com/docs/provision-detail#get-latest-detail-for-an-provision-request) * Retrieves the most recent `ProvisionDetail` for a `ProvisionRequest` * [GET /provision-requests/{provisionRequestId}/details/latest](https://devx.pax8.com/reference/getlatestprovisiondetail) The Provision Detail Object [](https://devx.pax8.com/docs/provision-detail#the-provision-detail-object) =========================================================================================================== JSON `{ "id": "5c425efa-60be-4bac-98b4-d3dff9099143", "provisionRequestId": "50f31e66-9a01-43a8-b0f8-14c288bac5da", "details": { "firstName": "John Doe", "lastName": "Doe", "email": "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "changeOfChannel": "Yes" }, "createdDate": "2025-07-03T02:51:59.552059Z" }` In the example above, `ProvisionDetails` were configured in Pax8's system. This is information that the Partner will fill in during checkout. These are custom data points beyond the standard dataset we already provide in `ProvisionRequest`. Work with your Pax8 support person to configure these custom checkout details. Additional Information [](https://devx.pax8.com/docs/provision-detail#additional-information) ------------------------------------------------------------------------------------------------- ### External Identifiers [](https://devx.pax8.com/docs/provision-detail#external-identifiers) * If you've previously saved an External Identifier in Pax8 at the `Partner`, `PartnerEnrollment`, `Company`, or `Subscription` level, these will appear in the `details` map like so: JSON `{ "details": { "externalProvisionerPartnerId": "53b97015-19e0-4fac-aa07-56188c6580c2", "externalProvisionerPartnerEnrollmentId": "50b7c771-fdf7-4eb5-80fb-2aaf1eba640e", "externalProvisionerCompanyId": "29cf7b7d-08e3-4dcb-a4f8-493788d1fb09", "externalProvisionerSubscriptionId": "0148b5ee-dd60-441e-9501-5a7056cb6be7", "key": "value" } }` Updated 3 months ago * * * Ask AI --- # Invoice & Billing Integrations This guide covers the lifecycle of invoices, how to handle corrections, and the details of invoice line items. * * * 1\. Invoice Lifecycle and Availability [](https://devx.pax8.com/docs/invoice-billing-integrations#1-invoice-lifecycle-and-availability) ------------------------------------------------------------------------------------------------------------------------------------------- ### Invoice Generation Timeline [](https://devx.pax8.com/docs/invoice-billing-integrations#invoice-generation-timeline) Understand when invoices are generated and become available via the API. 1. **Generation:** Invoices are generated on the **4th of the month**. 2. **Internal Approval:** Invoices are reviewed and approved by internal teams shortly after generation. 3. **API Availability:** An invoice is made available via the API **as soon as it is approved**. 4. **Email Distribution:** Emailed invoices begin sending to partners on the **5th of the month**. * **Potential Delays:** If errors are detected _before_ an invoice is approved, Pax8 may regenerate the invoice. This will delay the approval and, consequently, its availability via the API. You can subscribe to our "invoice ready" webhook event to be notified when invoices are ready. ### Invoice Immutability and Corrections [](https://devx.pax8.com/docs/invoice-billing-integrations#invoice-immutability-and-corrections) Once an invoice is approved, its contents are final and cannot be changed. * **Pre-Approval:** As of November 2025, invoices that are not yet approved may be voided and regenerated internally. These voided invoices **will not appear** in the API's invoice list. * **Post-Approval:** An approved invoice **cannot be edited or voided** for any reason. **Handling Corrections to Approved Invoices:** If an approved invoice contains significant errors and must be regenerated, the following process is used: 1. The incorrect, approved invoice is **"Credited"** in full. 2. This "Credited" invoice **will still be visible** in your invoice list and accessible via the API. 3. A ledger credit for the full invoice amount is generated, which will be included on the next credit memo. 4. A **new, corrected invoice** is generated with a **new invoice number**. > **Key Takeaway:** You will not see an approved invoice change. Instead, you will see the original invoice marked as "Credited" and a _new_ invoice issued with the corrected details. ### Understanding Key Invoice Fields [](https://devx.pax8.com/docs/invoice-billing-integrations#understanding-key-invoice-fields) The following fields are present on the invoice object: * **`total`**: The total of all charges and applicable sales tax for the _previous billing period_. * **`carriedBalance`**: The unpaid balance from the _previous_ invoice that is carried forward to the current invoice. (Note: This information will soon be moved to the Account Statement and removed from the invoice itself). * **`balance`**: The total account balance due to Pax8. * **`currencyCode`**: The ISO currency code for the partner's default currency. Every invoice is in this currency. * * * 2\. Line Item Details [](https://devx.pax8.com/docs/invoice-billing-integrations#2-line-item-details) --------------------------------------------------------------------------------------------------------- ### Service Charges [](https://devx.pax8.com/docs/invoice-billing-integrations#service-charges) We use different types of service charges. Here is what to expect from those line items: * **Types:** Charges can be "general" or "product related." * **Product-Related Fields:** These charges provide the _option_ to select a `vendor`, `subscription`, `product`, and `customer`. * **Required Fields:** All service charges will have a `transaction date`, `billing start period`, and `billing end period`. * **Optional Fields:** `quantity` is not a required field but is typically included in the description when applicable. Sales tax may be included or excluded depending on the situation. **Important Change to Reconciliation:** Previously, missed subscriptions were sometimes added using a service charge. This practice has been discontinued. When we detect subscriptions that were missed in a billing cycle, we now upload them upstream from invoice generation. They will appear on your invoice as **normal charge line items**, not as service charges. ### Subscription ID (`subscriptionId`) [](https://devx.pax8.com/docs/invoice-billing-integrations#subscription-id-subscriptionid) The `subscriptionId` is a UUID used to link an invoice line item back to a specific subscription. * **Key Behavior:** This `subscriptionId` increments (i.e., a new UUID is generated) every time there is a modification to the subscription, such as a quantity or price change. In the online Pax8 portal, you can see these different incrementing subscriptionIds. * For purposes of our public APIs, the subscriptionId will always return the original subscriptionId. You can still use our [subscription history endpoint](https://devx.pax8.com/reference/findsubscriptionhistorybysubscriptionid) to see the changes in subscription history and ids. * Each invoice line item includes the "subscriptionId" related to that line item charge, that you can use to cross reference the respective subscription. Updated 5 days ago * * * Ask AI --- # Usage Lines Overview [](https://devx.pax8.com/docs/usage-lines#overview) ================================================================ Usage Lines represent usage for a subscription and usage product for a single billing period. Endpoints [](https://devx.pax8.com/docs/usage-lines#endpoints) ------------------------------------------------------------------ ### Save Usage Lines [](https://devx.pax8.com/docs/usage-lines#save-usage-lines) * Save Usage Lines For a Pax8 Subscription * [POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}](https://devx.pax8.com/reference/saveusagelines) * [POST /usage/lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}](https://devx.pax8.com/reference/saveusagelines) ### Get Usage Lines [](https://devx.pax8.com/docs/usage-lines#get-usage-lines) * Get Usage Lines for a Pax8 Subscription * [GET /usage/lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}&summaryKey={summaryKey}](https://devx.pax8.com/reference/getusagelines) * [GET /usage/lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}&summaryKey={summaryKey}](https://devx.pax8.com/reference/getusagelines) > Note that `billingPeriod` is a year-month, taking the format `yyyy-MM`. > > Our API also offers an optional feature that enables Vendors to store a unique identifier on a subscription during provisioning. The externalProvisionerSubscriptionId serves as a reference point for future interactions with the object, making it easy to locate and modify without complex mappings. The Usage Line Object [](https://devx.pax8.com/docs/usage-lines#the-usage-line-object) ========================================================================================== JSON `{ "summaryKey": "key", "summaryDisplayName": "name", "quantity": 1, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "unit" }` Additional Information [](https://devx.pax8.com/docs/usage-lines#additional-information) -------------------------------------------------------------------------------------------- Pax8 Partners may have many usage lines for a subscription, and those lines could be for many different companies, so we offer a grouping mechanism called `summaryKey` to aggregate usage lines into summaries. The most common grouping pattern - and the pattern recommended by Pax8 - is to group usage lines by company. * Usage Lines are grouped by a `summaryKey` for a Subscription. Every usage line that shares an identical `summaryKey` will grouped together for display purposes. * The key must be a unique identifier, most often a company id. * The `summaryDisplayName` is used in the Pax8 UI, this is the label that partners will see on their invoices and throughout the month when monitoring their usage. It gives a friendly name to the group defined by a `summaryKey`. * If you are grouping usage by Company ID, then Company name is a good candidate for `summaryDisplayName` > NOTE: both `summaryKey` and `summaryDisplayName` have a 255 character limit. Updated 3 months ago * * * * [Overwriting or Appending Same Day Usage](https://devx.pax8.com/docs/overwrite-same-day-usage) Ask AI --- # MCP Setup Guide (Cursor) This guide instructs users on setting up the MCP Server and enabling Cursor integration for both Windows and macOS systems. Prerequisites [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#prerequisites) ------------------------------------------------------------------------------------- Before beginning the setup process, you will need to: * Access to a Pax8 account (app.pax8.com) * Node.js version 18 or higher installed on your system * Administrative privileges on your computer * Internet connection for downloading required software Step 1: Access the Pax8 Integrations Page [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#step-1-access-the-pax8-integrations-page) -------------------------------------------------------------------------------------------------------------------------------------------- 1. Sign in to [app.pax8.com](https://app.pax8.com/) 2. On the left pane, select **Settings** > **Integrations** Step 2: Generate Authentication Token [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#step-2-generate-authentication-token) ------------------------------------------------------------------------------------------------------------------------------------ 1. Navigate to the Integrations page 2. On the **Integrations** page, select the **MCP server** box at the top 3. Under **MCP Token and Authentication**, select **Generate Token** * The page will refresh automatically after token generation Step 3: Install Node.js v18 (If Not Already Installed) [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#step-3-install-nodejs-v18-if-not-already-installed) ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Node.js v18 is the minimum requirement to access the MCP Server. Ensure your default Node.js version is set to 18 or higher. ### Initial Steps (All Platforms) [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#initial-steps-all-platforms) 1. On the Integrations page, select the **MCP server** tab 2. On the right **Info** panel, under **Prerequisites**, select **Node.js v18** 3. On [nodejs.org](http://nodejs.org/) , select **Download** 4. On the **Download Node.js** page, locate the dropdown for a prebuilt Node.js ### Platform-Specific Download and Installation [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#platform-specific-download-and-installation) #### Windows [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#windows) 5. Select **Windows** from the dropdown 6. Select **Windows installer (.msi)** 7. Access the `node-v[semver version].msi` file on your device #### macOS [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#macos) 5. Select **macOS** from the dropdown 6. Select **macOS installer (.pkg)** 7. Access the `node-v[semver version].pkg` file on your device ### Installation Process (All Platforms) [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#installation-process-all-platforms) 8. On the **Install Node.js** wizard, select **Continue** 9. Read the **Software License Agreement** and select **Continue** 10. Select **Agree** to the terms of the agreement 11. Select **Install** (you will be prompted to enter your device's username and password) 12. Enter your login details and select **Install Software** 13. When download is complete, select **Close** Step 4: Download and Install Cursor [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#step-4-download-and-install-cursor) -------------------------------------------------------------------------------------------------------------------------------- Prior to configuring the MCP Server, ensure you have completed Steps 1-3 (token generation and Node.js installation). 1. Download and install the Cursor application from [cursor.sh](https://cursor.sh/) 2. Follow the platform-specific installation instructions 3. Open your newly-installed **Cursor** application 4. Complete the initial setup and sign-in process if prompted Step 5: Configure Cursor MCP Settings [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#step-5-configure-cursor-mcp-settings) ------------------------------------------------------------------------------------------------------------------------------------ ### Access Configuration File [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#access-configuration-file) You can access the configuration file through Cursor settings or locate it manually: #### Option 1: Through Cursor Settings [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#option-1-through-cursor-settings) 1. Open Cursor Settings using the keyboard shortcut: * **macOS**: `⌘ + ,` * **Windows**: `Ctrl + ,` 2. Navigate to **Developer** > **Edit Config** 3. This should open a finder window to the cursor desktop config file #### Option 2: Manual File Location [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#option-2-manual-file-location) Locate the configuration file directly on your system: ##### macOS [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#macos-1) * File path: `/Users/your-user-name/Library/Application Support/Cursor/cursor_desktop_config.json` ##### Windows [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#windows-1) * File path: `C:\Users\your-user-name\AppData\Roaming\Cursor\cursor_desktop_config.json` ### Edit Configuration File [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#edit-configuration-file) 1. Open the `cursor_desktop_config.json` file in your device's default text editor 2. Navigate back to the Integrations > **MCP Server** page in your browser 3. Scroll down to the **Connect** section and select **Cursor** 4. Select **Copy Code** (this will copy the configuration with your MCP token already in place to the clipboard) 1. OR you can copy this code and replace with your unique token 1. JSON `{ "mcpServers": { "supergateway-pax8": { "command": "npx", "args": [ "-y", "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "--header", "x-pax8-mcp-token:YOUR-MCP-TOKEN-HERE", "--streamableHttp", "https://mcp.pax8.com/v1/mcp" ] } } }` 5. Replace the existing text in your `cursor_desktop_config.json` file with the copied configuration 6. On the top menu, select **File** > **Save** 7. Exit the text editor once the file is saved ### Apply Configuration Changes [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#apply-configuration-changes) 1. Save the MCP config file 2. Restart the Cursor application to apply the changes: #### Windows [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#windows-2) * Close Cursor completely * Reopen the Cursor application #### macOS [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#macos-2) * Select **Cursor** > **Quit** from the top menu * Reopen the Cursor application Step 6: Test the Integration [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#step-6-test-the-integration) ------------------------------------------------------------------------------------------------------------------ 1. Open a new chat session in Cursor 2. Type the following test prompt: **"Can you get me a list of companies using the pax8 mcp server?"** 3. This should trigger the MCP server tool call 4. You may need to click the **"Run Tool"** button to see the tool call in action 5. Verify that Cursor can successfully communicate with the Pax8 MCP Server Verification Checklist [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#verification-checklist) ------------------------------------------------------------------------------------------------------- Ensure the following to confirm successful integration: * [ ] Node.js v18+ is installed and set as default version * [ ] Pax8 MCP token has been generated * [ ] Configuration file has been updated with your specific MCP token * [ ] Cursor application has been restarted after configuration changes * [ ] Test prompt successfully triggers MCP server tool calls Optional: Getting Started [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#optional-getting-started) ------------------------------------------------------------------------------------------------------------ Use the sample prompts available on the Integrations > **MCP Server** page to begin exploring the integration capabilities with Cursor. Troubleshooting [](https://devx.pax8.com/docs/mcp-setup-guide-cursor#troubleshooting) ----------------------------------------------------------------------------------------- If you encounter issues during setup: * **Node.js Version**: Verify Node.js v18 or higher is installed by running `node --version` in your terminal * **Token Issues**: Ensure your authentication token was generated successfully and copied correctly * **Configuration File**: Check that the `cursor_desktop_config.json` file was saved correctly with proper JSON formatting * **Application Restart**: Always restart Cursor after making configuration changes * **Tool Execution**: If tools don't execute automatically, look for the "Run Tool" button in the chat interface For additional support, refer to the Pax8 documentation or contact your system administrator or see Cursor official documentation: [https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) Updated 2 months ago * * * Ask AI --- # Provision Result Overview [](https://devx.pax8.com/docs/provision-result#overview) ===================================================================== A `ProvisionResult` represents the end result for a given `ProvisionAttempt`. A `ProvisionResult` indicates the status (`Success` or `Fail`) of provisioning, and returns information about the subscription in the Provisioner system. Endpoints [](https://devx.pax8.com/docs/provision-result#endpoints) ----------------------------------------------------------------------- ### Get All Provision Results for a Provision Request [](https://devx.pax8.com/docs/provision-result#get-all-provision-results-for-a-provision-request) * Get All Provision Results for a Provision Request * If `provisionAttemptId` is provided, it returns the Provision Result associated with the specified Provision Attempt * If `provisionAttemptId` is not provided, it returns all Provision Results for a Provision Request * [GET /provision-requests/{provisionRequestId}/results?provisionAttemptId={provisionAttemptId}](https://devx.pax8.com/reference/getallprovisionresults) ### Get One Provision Result [](https://devx.pax8.com/docs/provision-result#get-one-provision-result) * Get One Provision Result * [GET /provision-requests/{provisionRequestId}/results/{provisionResultId}](https://devx.pax8.com/reference/getoneprovisionresult) ### Get Latest Provision Result for an Order [](https://devx.pax8.com/docs/provision-result#get-latest-provision-result-for-an-order) * Get Latest Provision Result for an Order * [GET /provision-requests/{provisionRequestId}/results/latest](https://devx.pax8.com/reference/getlatestprovisionresult) ### Create Provision Result [](https://devx.pax8.com/docs/provision-result#create-provision-result) * Create Provision Result * [POST /provision-requests/{provisionRequestId}/results](https://devx.pax8.com/reference/createprovisionresult) The Provision Result Object [](https://devx.pax8.com/docs/provision-result#the-provision-result-object) =========================================================================================================== JSON `{ "id": "43b4b1f0-381b-473a-b3ca-a5af43e64c9a", "provisionAttemptId": "c9f3a6bd-acf7-4108-8cc6-0994ccb5fdb9", "status": "Success | Fail", "errorMessage": null, "metadata": { "key": "value" }, "externalProvisionerSubscriptionId": "0148b5ee-dd60-441e-9501-5a7056cb6be7", "externalProvisionerPartnerId": "53b97015-19e0-4fac-aa07-56188c6580c2", "externalProvisionerCompanyId": "29cf7b7d-08e3-4dcb-a4f8-493788d1fb09", "createdDate": "2022-10-03T10:15:30Z" }` Additional Information [](https://devx.pax8.com/docs/provision-result#additional-information) ------------------------------------------------------------------------------------------------- ### Nuances [](https://devx.pax8.com/docs/provision-result#nuances) * A `ProvisionResult` cannot be posted for a `ProvisionAttempt` that already has an associated `ProvisionResult`. * Pax8 does not accept `ProvisionResults` for `ProvisionAttempts` that are not acknowledged * When the `status` is `Fail` The `errorMessage` field should contain relevant error information that a non-technical customer can understand. * The `errorMessage` input is truncated to 500 characters. * Once you have posted a result for a `ProvisionAttempt`, any subsequent attempt to post another result will be rejected. ### Metadata [](https://devx.pax8.com/docs/provision-result#metadata) The `metadata` field exists only for informational purposes, and it is optional to use. It's value can be any valid json object. Use this if you would like to send additional information alongside an error message. You can also use it for successful provision results if you would like to provide some identifiers created during provisioning, again for informational purposes only. ### External Identifiers [](https://devx.pax8.com/docs/provision-result#external-identifiers) * Pax8 can store external identifiers for `Partner`, `PartnerEnrollment`, `Company`, and `Subscription` * They are stored in `externalProvisionerPartnerId`, `externalProvisionerPartnerEnrollmentId`, `externalProvisionerCompanyId`, and `externalProvisionerSubscriptionId` respectively. * These identifiers are _optional_. They are available across Pax8 APIs and can be used to correlate data between Pax8 and the Provisioner system. Pax8 does not validate these identifiers. * An example use case for using an external partner id could be: * Pax8 sends your system a Provision Notification for a Partner that has never purchased with you before. * When you create the Partner account in your system, you create your own internal identifier called "ABC" * When you send the Provision Result to Pax8, you can assign that "ABC" id to the Partner record in the Pax8 system by including it as the value for `externalProvisionerPartnerId` * Then, on every subsequent Provision Notification that Pax8 sends your system for that same partner, `externalProvisionerPartnerId` would appear in the Provision Details, and the value would be "ABC" Updated 3 months ago * * * Ask AI --- # MCP Setup Guide (Copilot) This guide instructs users on setting up the MCP Server and enabling Microsoft Copilot integration through Copilot Studio. Prerequisites [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#prerequisites) -------------------------------------------------------------------------------------- Before beginning the setup process, you will need to: * Access to a Pax8 account (app.pax8.com) * Access to Microsoft Copilot Studio * Access to Power Apps (for custom connector creation) * Administrative privileges for your Microsoft environment * Internet connection for accessing required services * Early Access Instructions: * Create and manage environments in the Power Platform admin center - Power Platform [Here](https://learn.microsoft.com/en-us/power-platform/admin/create-environment#create-an-environment-in-the-power-platform-admin-center) * Settings: Create and manage environments in the Power Platform admin center - Power Platform [Here](https://learn.microsoft.com/en-us/power-platform/admin/create-environment#steps) * "Get new features early" must be Yes * Type: Not sure it matters Step 1: Access the Pax8 Integrations Page [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-1-access-the-pax8-integrations-page) --------------------------------------------------------------------------------------------------------------------------------------------- 1. Sign in to [app.pax8.com](https://app.pax8.com/) 2. On the left pane, select **Settings** > **Integrations** Step 2: Generate Authentication Token [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-2-generate-authentication-token) ------------------------------------------------------------------------------------------------------------------------------------- 1. Navigate to the Integrations page 2. On the **Integrations** page, select the **MCP server** box at the top 3. Under **MCP Token and Authentication**, select **Generate Token** * The page will refresh automatically after token generation 4. Copy and save your MCP token for use in Step 6 Step 3: Create New Agent in Copilot Studio [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-3-create-new-agent-in-copilot-studio) ----------------------------------------------------------------------------------------------------------------------------------------------- 1. Open Microsoft Copilot Studio 2. In the left sidebar, click **Agents** 3. Click the **\+ New Agent** button 4. Configure your agent with the following settings: * **Agent Name**: Provide a descriptive name (e.g., "Pax8 Marketplace Assistant") * **Basic Prompt**: Enter a foundational prompt such as: `You will answer questions about Pax8 from a tool you will have available` 5. Click **Continue** in the top right to proceed Step 4: Prepare OpenAPI Configuration File [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-4-prepare-openapi-configuration-file) ----------------------------------------------------------------------------------------------------------------------------------------------- 1. Download this [file](https://www.pax8nebula.com/m/4a0af63405165ae9/original/MCP-server-open-ai-json-1.json) OR follow the steps below. 2. Copy the OpenAPI configuration provided below 3. Save it as a file named `openapi.json` on your local device ### OpenAPI Configuration File [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#openapi-configuration-file) JSON `{ "swagger": "2.0", "info": { "title": "Pax8 Marketplace", "description": "MCP Server for Pax8 Marketplace - interact with companies, invoices, orders, products, quotes, and subscriptions", "version": "1.0.0" }, "host": "mcp.pax8.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/mcp": { "post": { "summary": "Pax8 Marketplace MCP Server", "x-ms-agentic-protocol": "mcp-streamable-1.0", "operationId": "InvokeMCP", "responses": { "200": { "description": "Success" } } } } }, "securityDefinitions": { "api_key": { "type": "apiKey", "in": "header", "name": "x-pax8-mcp-token" } } }` Step 5: Create Custom Connector in Power Apps [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-5-create-custom-connector-in-power-apps) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Access Custom Connector Creation [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#access-custom-connector-creation) 1. In Copilot Studio, click **Tools** in the top navigation bar 2. Click the **\+ Add a tool** button 3. Click the **\+ New tool** button 4. Select **Custom connector** * This will redirect you to the Power Apps environment ### Import OpenAPI Configuration [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#import-openapi-configuration) 5. In Power Apps, click the **\+ New custom connector** button 6. Select **Import an OpenAPI file** 7. Provide a descriptive name for your connector (e.g., "Pax8 MCP Connector") 8. Click **Import** 9. Upload the `openapi.json` file you created in Step 4 10. Click **Continue** ### Finalize Connector Creation [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#finalize-connector-creation) 11. Review the connector configuration settings 12. Click **Create Connector** in the top right 13. Wait for the connector to be saved successfully Step 6: Configure Connection and Add to Agent [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-6-configure-connection-and-add-to-agent) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Return to Copilot Studio [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#return-to-copilot-studio) 1. Return to the Copilot Studio Tools tab 2. Refresh the page to see your newly created connector 3. Your connector should appear in the **Model Context Protocol** tab, or you can search for it by the name you provided ### Create Connection [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#create-connection) 4. Select your custom connector 5. In the **Connection** dropdown, click your connector name 6. Click **Create new connection** 7. In the authentication field, paste the Pax8 MCP token you generated in Step 2 8. Click **Create** ### Add Tool to Agent [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#add-tool-to-agent) 9. Once the connection is established, click **Add to agent** 10. Wait for the integration process to complete Step 7: Test the Integration [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#step-7-test-the-integration) ------------------------------------------------------------------------------------------------------------------- 1. Navigate to your agent's chat interface 2. Test the integration using one of the following example prompts: * "Can you get me a list of companies using the Pax8 MCP server?" * "Show me recent invoices from Pax8" * "What products are available in the Pax8 marketplace?" 3. Verify that the agent successfully retrieves data from the Pax8 MCP Server Verification Checklist [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#verification-checklist) -------------------------------------------------------------------------------------------------------- Ensure the following to confirm successful integration: * [ ] Pax8 MCP token has been generated and saved * [ ] Agent has been created in Copilot Studio with appropriate prompt * [ ] OpenAPI file has been saved and imported correctly * [ ] Custom connector has been created successfully in Power Apps * [ ] Connection has been established with valid MCP token * [ ] Tool has been added to the agent * [ ] Test prompts return expected Pax8 data Optional: Getting Started [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#optional-getting-started) ------------------------------------------------------------------------------------------------------------- Use the sample prompts available on the Integrations > **MCP Server** page to begin exploring the integration capabilities with your Copilot agent. Troubleshooting [](https://devx.pax8.com/docs/mcp-setup-guide-copilot#troubleshooting) ------------------------------------------------------------------------------------------ If you encounter issues during setup: * **Token Issues**: Ensure your Pax8 MCP token was generated successfully and copied correctly * **OpenAPI Import**: Verify the `openapi.json` file is properly formatted and contains all required fields * **Connector Creation**: Check that you have appropriate permissions in Power Apps to create custom connectors * **Connection Authentication**: Confirm the MCP token is pasted correctly without extra spaces or characters * **Agent Integration**: Ensure the tool has been properly added to your agent after connection creation * **Response Issues**: If the agent doesn't respond as expected, verify the connection is active and test with simpler prompts For additional support, refer to the Pax8 documentation, Microsoft Copilot Studio documentation, or contact your system administrator. Updated 2 months ago * * * Ask AI --- # Provisioning Scenarios Provisioning Validation Failure Example [](https://devx.pax8.com/docs/provisioning-scenarios#provisioning-validation-failure-example) ----------------------------------------------------------------------------------------------------------------------------------------- 1. Pax8 Sends Webhook and creates a `ProvisionAttempt` 2. Provisioner API returns HttpStatus `200`, `201`, or `202` 1. No validation should occur during this step. This is simply to let Pax8 know whether the Provision Notification was received. 3. Pax8 marks the `ProvisionAttempt` as `Acknowledged` 4. Provisioner processes the request asynchronously. During processing, it is determined that the request cannot be processed as is. An example of this could be, the email provided by the user is already in use for another account. 5. Provisioner posts a `ProvisionResult` for the `ProvisionAttempt` with a `Fail` status and an `errorMessage` detailing what went wrong such as `vendorAdminEmail in use by another account` Provisioning Success Example [](https://devx.pax8.com/docs/provisioning-scenarios#provisioning-success-example) ------------------------------------------------------------------------------------------------------------------- 1. Pax8 Sends Webhook and creates a `ProvisionAttempt` 2. Provisioner API returns HttpStatus `200`, `201`, or `202` 1. Pax8 expects the Provisioner API to simply acknowledge the Provision Notification. The Provisioner API should not do any synchronous processing or validation at this time. 3. Pax8 marks the `ProvisionAttempt` as acknowledged 4. Provisioner processes the request asynchronously. At this time that would include validating request data, and then provisioning services. 5. Provisioner posts a `ProvisionResult` for the `ProvisionAttempt` with a `Success` status. Transient Error Example [](https://devx.pax8.com/docs/provisioning-scenarios#transient-error-example) --------------------------------------------------------------------------------------------------------- If our initial Provision Notification webhook fails, Pax8 employs a retry mechanism. Pax8 will automatically retry the webhook delivery up to three times. Each retry creates a new ProvisionAttempt, allowing for a total of four attempts: the initial attempt plus three retries. 1. Pax8 Sends Webhook and creates `ProvisionAttempt_1` 2. Provisioner API does _not_ respond with an acceptable status code ( `200`, `201`, or `202`) 3. Pax8 marks `ProvisionAttempt_1` as failed 4. Pax8 Sends Webhook and creates a `ProvisionAttempt_2` 5. Provisioner API returns HTTPStatus `200` 6. Pax8 marks the `ProvisionAttempt_2` as successful 7. Provisioner returns a `ProvisionResult` for `ProvisionAttempt_2` Updated 3 months ago * * * Ask AI --- # Billing Scenarios Pax8 will create billable charges for `Partners` based on the most recent totals for a given `summaryKey` on a given `Subscription` in a given `Billing Period`. Below are some examples of potentially complex billing scenarios that will bring clarity onto the logic Pax8 uses when creating billable charges. Scenario 1 [](https://devx.pax8.com/docs/billing-usage-examples#scenario-1) ------------------------------------------------------------------------------- * Vendor posts usage every day in October for a given subscription * All usage is grouped under the same `summaryKey` On November 2nd, Pax8 grabs the usage posted on October 31st for that one `summaryKey`, and uses that to create a billable charge Scenario 2 [](https://devx.pax8.com/docs/billing-usage-examples#scenario-2) ------------------------------------------------------------------------------- * It's October 15th, and Vendor has been posting usage for a subscription every day with the latest totals. * All usage is grouped under the same `summaryKey` * On October 16th, for whatever reason, Vendor stops posting usage lines for that `summaryKey`. This persists for the rest of the month. On November 2nd, Pax8 would grab the usage that was posted on October 15th, and use that to create a billable charge. Scenario 3 [](https://devx.pax8.com/docs/billing-usage-examples#scenario-3) ------------------------------------------------------------------------------- * Vendor has been posting usage for a subscription every day with the latest totals. * Usage is grouped by two unique `summaryKey` values, call them `summaryKey` A and B. * On October 30th, Vendor posts usage lines for both `summaryKey` A and B. * On October 31st, for whatever reason, Vendor only posts usage lines for `summaryKey` A. No lines are posted for summaryKey B on the 31st. In this case, on November 2nd, Pax8 will create billable charges for summaryKey A using usage lines posted for it on October 31st. Pax8 will create billable charges for summaryKey B using the lines posted for it on October 30th. Updated about 2 months ago * * * Ask AI --- # MCP Setup Guide (VSCode) This guide instructs users on setting up the MCP Server and enabling VS Code integration for both Windows and macOS systems. Prerequisites [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#prerequisites) ------------------------------------------------------------------------------------- Before beginning the setup process, you will need to: * Access to a Pax8 account (app.pax8.com) * VS Code with GitHub Copilot access * Internet connection for accessing required services Step 1: Access the Pax8 Integrations Page [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-1-access-the-pax8-integrations-page) -------------------------------------------------------------------------------------------------------------------------------------------- 1. Sign in to [app.pax8.com](https://app.pax8.com/) 2. On the left pane, select **Settings** > **Integrations** Step 2: Generate Authentication Token [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-2-generate-authentication-token) ------------------------------------------------------------------------------------------------------------------------------------ 1. Navigate to the Integrations page 2. On the **Integrations** page, select the **MCP server** box at the top 3. Under **MCP Token and Authentication**, select **Generate Token** * The page will refresh automatically after token generation 4. Copy and save your MCP token for use in Step 4 Step 3: Configure VS Code Settings [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-3-configure-vs-code-settings) ------------------------------------------------------------------------------------------------------------------------------ ### Enable Agent Mode [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#enable-agent-mode) 1. Open VS Code 2. Access VS Code Settings using the keyboard shortcut: * **macOS**: `⌘ + ,` * **Windows**: `Ctrl + ,` 3. In the Settings search bar, type: `chat.agent.enabled` 4. Check the box to enable **Chat: Agent Enabled** 5. See [vscode docs](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) for more details. ### Enable MCP Support [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#enable-mcp-support) 5. In the Settings search bar, type: `chat.mcp.enabled` 6. Check the box to enable **Chat: MCP Enabled** Step 4: Configure MCP Server Settings [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-4-configure-mcp-server-settings) ------------------------------------------------------------------------------------------------------------------------------------ ### Access Settings Configuration File [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#access-settings-configuration-file) You can configure the MCP server through Workspace settings or User settings by editing your `.vscode/settings.json` file: #### Option 1: Workspace Settings (Recommended) [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#option-1-workspace-settings-recommended) 1. In your project root, create or open the `.vscode/settings.json` file 2. This will apply MCP settings only to the current workspace #### Option 2: User Settings (Global) [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#option-2-user-settings-global) 1. Open VS Code Settings (`⌘ + ,` on macOS or `Ctrl + ,` on Windows) 2. Click the **Open Settings (JSON)** icon in the top right 3. This will apply MCP settings globally across all VS Code instances ### Add MCP Configuration [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#add-mcp-configuration) Add the following configuration to your `settings.json` file: JSON `"mcp": { "inputs": [], "servers": { "supergateway-pax8": { "command": "npx", "args": [ "-y", "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "--header", "x-pax8-mcp-token:YOUR-MCP-TOKEN-HERE", "--streamableHttp", "https://mcp.pax8.com/v1/mcp" ] } } }` **Important**: Replace `YOUR-MCP-TOKEN-HERE` with the MCP token you generated in Step 2. ### Save Configuration [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#save-configuration) 1. Replace `YOUR-MCP-TOKEN-HERE` with your actual Pax8 MCP token 2. Save the settings file (`⌘ + S` on macOS or `Ctrl + S` on Windows) 3. See [vscode docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. Step 5: Apply Configuration Changes [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-5-apply-configuration-changes) -------------------------------------------------------------------------------------------------------------------------------- 1. Save the MCP configuration file 2. Restart VS Code to apply the changes: #### All Platforms [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#all-platforms) * Close VS Code completely * Reopen VS Code Step 6: Enable Pax8 Tools in Agent Mode [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-6-enable-pax8-tools-in-agent-mode) ---------------------------------------------------------------------------------------------------------------------------------------- ### Access Agent Mode [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#access-agent-mode) 1. Open a new AI chat in VS Code using the keyboard shortcut: * **macOS**: `⌃⌘I` * **Windows**: `Ctrl+Alt+I` 2. In the chat interface, look for the toggle at the bottom that displays **Edit**, **Ask**, or **Agent** 3. Click the toggle and select **Agent** mode ### Enable Pax8 Tools [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#enable-pax8-tools) 4. In Agent mode, you should see a **tools icon** in the chat interface 5. Click the **tools icon** 6. You should see a list of available tools with the **Pax8** option 7. Check the box next to **Pax8** to enable the Pax8 tools Step 7: Test the Integration [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#step-7-test-the-integration) ------------------------------------------------------------------------------------------------------------------ 1. Ensure you are in Agent mode in the AI chat 2. Type the following test prompt: **"Can you get me a list of companies using the pax8 mcp server?"** 3. This should trigger the MCP server tool call 4. You may need to click the **"Start Server"** or **"Continue"** button to see the tool call in action 5. Verify that VS Code can successfully communicate with the Pax8 MCP Server Verification Checklist [](https://devx.pax8.com/docs/mcp-setup-guide-vscode#verification-checklist) ------------------------------------------------------------------------------------------------------- Ensure the following to confirm successful integration: * [ ] Pax8 MCP token has been generated and saved * [ ] VS Code Agent mode is enabled (`chat.agent.enabled`) * [ ] MCP support is enabled in VS Code (`chat.mcp.enabled`) * [ ] Configuration file has been updated with your specific MCP token * [ ] VS Code has been restarted after configuration changes * [ ] Pax8 tools are enabled in Agent mode * [ ] Test prompt successfully triggers MCP server tool calls Updated 2 months ago * * * Ask AI --- # Webhook Configuration A `WebhookConfiguration` represents location and credentials that Pax8 will use for webhook notifications. The `url` is the address Pax8 sends webhook payload to. The `sharedSecret` represents credentials that Pax8 will send as a header in the webhook request to authorize to your system. You can assign a name to the authorization header that Pax8 will send, and Pax8 will generate and return a shared `credential` that will be used when sending a webhook. * You cannot change the `ProvisionerWebhook` information for a previous Provision Attempt * `credential` values are only returned during create. In all other responses, they are returned as `*****` Endpoints [](https://devx.pax8.com/docs/webhook-configuration#endpoints) ---------------------------------------------------------------------------- ### Get All Webhook Configurations for a Provisioner [](https://devx.pax8.com/docs/webhook-configuration#get-all-webhook-configurations-for-a-provisioner) * Get All Webhook Configurations for a Provisioner * [GET /provisioners/{provisionerId}/webhooks](https://devx.pax8.com/reference/getallwebhooksforprovisioner) ### Get One Webhook for a Provisioner [](https://devx.pax8.com/docs/webhook-configuration#get-one-webhook-for-a-provisioner) * Get One Webhook for a Provisioner * [GET /provisioners/{provisionerId}/webhooks/{webhookId}](https://devx.pax8.com/reference/getonewebhookforprovisioner) ### Get Latest Webhook for a Provisioner [](https://devx.pax8.com/docs/webhook-configuration#get-latest-webhook-for-a-provisioner) * Get Latest Webhook for a Provisioner * [GET /provisioners/{provisionerId}/webhooks/latest](https://devx.pax8.com/reference/getlatestwebhookforprovisioner) ### Create a Webhook Configuration for a Provisioner [](https://devx.pax8.com/docs/webhook-configuration#create-a-webhook-configuration-for-a-provisioner) * Create a Webhook Configuration for a Provisioner * Webhook Configurations are immutable. Only the latest configuration's data will be used for new Provision Notifications. In order to change where Pax8 sends your webhook, or the credentials we should send, create a new Webhook Configuration. * Values for the `header` field must comply with HTTP header specifications * If you do not specify a value, the default is `pax8ApiTokenV1` * URL's should not contain any query parameters (for example `?vendorParam={value}`) * Pax8 generates the value for `credential` when a new webhook configuration is created. The `credential` is **only** available in the Create response, so make sure to record the value. * [POST /provisioners/{provisionerId}/webhooks](https://devx.pax8.com/reference/createwebhookforprovisioner) The Webhook Object [](https://devx.pax8.com/docs/webhook-configuration#the-webhook-object) ============================================================================================== JSON `{ "id": "ff50b383-0ba6-4fc4-ad30-f19483c1acfb", "url": "https://example.com", "sharedSecret": { "header": "pax8ApiTokenV1", "credential": "credential" }, "createdDate": "2022-10-03T10:15:30Z" }` Webhook Configuration Guide [](https://devx.pax8.com/docs/webhook-configuration#webhook-configuration-guide) ---------------------------------------------------------------------------------------------------------------- You want to setup a new webhook so you first you make the following request to get your provisionerId: GET Provisioners Request `curl --request GET \ --url https://api.pax8.com/v2/provisioners \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN'` This will return a response similar to GET Provisioners Response `{ "content": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "createdDate": "2025-08-05T17:01:58.621Z", "vendorId": "e20b8d09-a53d-4355-97dc-06ce46218a89", "name": "string" } ], "page": { "size": 0, "totalElements": 0, "totalPages": 0, "number": 0 } }` Now you are able to make a new Webhook Configuration via the following request: Request `curl --request POST \ --url https://api.pax8.com/v2/provisioners/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' { "sharedSecret": { "header": "testAuthorization" }, "url": "https://test-server.com" } '` Upon making that request you receive a response such as this one. You would note down this credential as you as that is the only time you will be able to view it: Response `{ "id": "ff50b383-0ba6-4fc4-ad30-f19483c1acfb", "url": "https://test-server.com", "sharedSecret": { "header": "testAuthorization", "credential": "abc123" }, "createdDate": "2025-08-04T16:28:02.850Z" }` This means that whenever Pax8 sends a webhook notification to you, our request would look something like this: cURL `curl --request POST --url https://test-server.com \ --header 'testAuthorization: abc123' \ --data '{}'` Updated 3 months ago * * * Ask AI --- # How to use Webhook APIs New Pax8 events or topics are continuously being added, but if you have a need or request please email: [\[email protected\]](https://devx.pax8.com/cdn-cgi/l/email-protection#b7ded9c3d2d0c5d6c3ded8d9c4f7c7d6cf8f99d4d8da) We send webhook calls as soon as events or actions happen in the Pax8 platform. However, this may take up to 5 minutes for your service to receive the call. Other general notes: > **Base URL:** `https://api.pax8.com/api/v2/webhooks` > > Authentication is required for every Pax8 API request (see _Authentication_ section). > > Webhooks are marked as failed if a response is not received after 10 seconds > > Webhooks are sent as a POST call with a JSON body. > > Only 1 of each webhook topic can be present in a single webhook subscription. Make a new webhook subscription if you want to receive different notifications for the same topic. Table of contents [](https://devx.pax8.com/docs/how-to-use-webhook-apis#table-of-contents) ---------------------------------------------------------------------------------------------- 1. [Authentication](https://devx.pax8.com/docs/how-to-use-webhook-apis#authentication) 2. [Topic-Definitions API](https://devx.pax8.com/docs/how-to-use-webhook-apis#topic-definitions-api) 3. [Creating & Managing Webhooks](https://devx.pax8.com/docs/how-to-use-webhook-apis#creating-&-managing-webhooks) 4. [Testing a Webhook](https://devx.pax8.com/docs/how-to-use-webhook-apis#testing-a-Webhook) 5. [Webhook Delivery Logs](https://devx.pax8.com/docs/how-to-use-webhook-apis#webhook-delivery-logs) 6. [3rd Party Integrators](https://devx.pax8.com/docs/how-to-use-webhook-apis#3rd-party-integrators) 7. [Automatic Retries & Error-Threshold Email Alerts](https://devx.pax8.com/docs/how-to-use-webhook-apis#automatic-retries-&-error-threshold-email-alerts) 8. [Common Validation Errors & How to Avoid Them](https://devx.pax8.com/docs/how-to-use-webhook-apis#common-validation-errors-&-how-to-avoid-them) 9. [Pax8 Event Permissions & Behavior](https://devx.pax8.com/docs/how-to-use-webhook-apis#pax8-event-permissions-&-behavior) 10. [Frequently Asked Questions](https://devx.pax8.com/docs/how-to-use-webhook-apis#frequently-asked-questions) * * * Authentication [](https://devx.pax8.com/docs/how-to-use-webhook-apis#authentication) ---------------------------------------------------------------------------------------- ### Calling Pax8 apis [](https://devx.pax8.com/docs/how-to-use-webhook-apis#calling-pax8-apis) | Header | Example | Notes | | --- | --- | --- | | `Authorization` | `Bearer eyJhbGc…` | Must be a Pax8 OAuth2 JWT | * When making calls to Pax8 APIs the Authorization header needs to be set. To learn more about this see our [Authentication docs](https://devx.pax8.com/docs/authentication) * The token owner **must** also have the permissions for the Pax8 account they are operating on, otherwise no event notifications will be emitted. For example: you can subscribe to PRODUCT events but only the products the account has access to see in the pax8 catalog. ### Pax8 calling your Webhook URL [](https://devx.pax8.com/docs/how-to-use-webhook-apis#pax8-calling-your-webhook-url) | Header | Example | Notes | | --- | --- | --- | | `Authorization` | my\_super\_secret | This value will be stored encrypted in our system but will be sent to your webhook URL under the "Authorization" header as exactly as you inputed | Setting the Authorization field in the webhook object will include the above header in the request to your webhook url. In your application be sure to validate that value for all calls. This is an optional field so the level of security is up to you. * * * Topic-Definitions API [](https://devx.pax8.com/docs/how-to-use-webhook-apis#topic-definitions-api) ------------------------------------------------------------------------------------------------------ `GET /webhooks/topic-definitions` Returns the authoritative catalog of topics, actions and filterable fields that may be used when creating or updating a webhook. The payload is paged; use `page`, `size`, `search`, `sort` and `topic` query parameters as needed. HTTP `GET /webhooks/topic-definitions?page=0&size=25 Authorization: Bearer Accept: application/json` Successful response (truncated): JSON `{ "content": [ { "topic": "SUBSCRIPTION", "name": "Subscription Events", "description": "Triggered when billing subscription related events occur", "availableFilters": [ { "action": "CREATE", "conditions": [ { "field": "vendorId", "operator": ["IN"], "value": "[uuid, uuid]" } ] } ], "samplePayload": { … } } ], "number": 0, "size": 25, "totalElements": 3, "totalPages": 1 }` Why this endpoint matters: * It is forward-compatible – new topics or actions will appear here first. * Building dynamic UI? Drive your drop-downs from `topic`, `action` and `conditions` arrays. * Your **create webhook** calls will be rejected if you reference a topic/action/field that is not present in this catalog. * Use this api as technical documentation on what to provide our apis * * * Creating & Managing Webhooks [](https://devx.pax8.com/docs/how-to-use-webhook-apis#creating--managing-webhooks) ------------------------------------------------------------------------------------------------------------------- ### Create [](https://devx.pax8.com/docs/how-to-use-webhook-apis#create) `POST /webhooks` jsonc `{ "displayName": "Monthly billing listener", "url": "https://example.com/webhooks/pax8", "contactEmail": "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", // optional email to send a failure alert "authorization": "cGFzc3dvcmQ=", // optional, encrypted at rest "active": true, // overridden to false if no topics are supplied "errorThreshold": 10, // consecutive failures before an email alert is sent "webhookTopics": [ { "topic": "SUBSCRIPTION", "filters": [ { "action": "CREATE", "conditions": [ { "field": "vendorId", "operator": "IN", "value": ["d6489ab3-3e13-4fe1-84ac-08d4d8c4b802"] } ] } ] } ] }` If successful the API returns the fully populated `WebhookView` object (including an auto-generated ID). ### Update [](https://devx.pax8.com/docs/how-to-use-webhook-apis#update) * **Configuration** – `POST /webhooks/{id}/configuration` * Use this to change the information besides the topics, such as: `displayName`, `contactEmail`, `url`, and `authorization` * The `authorization` field is optional. However, we encourage users to place a value to validate against in your app. * **Status (activate / deactivate)** – `POST /webhooks/{id}/status` * This will fail if the webhook url is null * **Add a topic** – `POST /webhooks/{id}/topics` * Adds a topic that does not already exist on the webhook, otherwise it will fail. To update an existing topic filters use `POST /webhooks/{id}/topics/{topicId}/configuration` * **Replace all topics** – `PUT /webhooks/{id}/topics` * Any existing topic in the webhook that is not included in this api call will be deleted, existing ones will be updated. * **Remove a single topic** – `DELETE /webhooks/{id}/topics/{topicId}` All payloads accept the same structures as the create call; only the minimal delta is required. ### Delete [](https://devx.pax8.com/docs/how-to-use-webhook-apis#delete) `DELETE /webhooks/{id}` – permanently removes the webhook and all associated logs. * * * Testing a Webhook [](https://devx.pax8.com/docs/how-to-use-webhook-apis#testing-a-webhook) ---------------------------------------------------------------------------------------------- `POST /webhooks/{id}/topics/{topic}/test` Pick a topic value from the Topic-Definitions and use that for '{topic}' value. The webhook does not need to be subscribed to that topic or be active for this to send. The URL does need to be set in order to send a test. On execution this api queues a synthetic event using the `samplePayload` associated with the topic definition. The call returns immediately. Look for the logs view to see the call attempt. Check you implementation to make sure your system received the webhook call. Any delivery errors will appear in the regular webhook logs (see next section). * * * Webhook Delivery Logs [](https://devx.pax8.com/docs/how-to-use-webhook-apis#webhook-delivery-logs) ------------------------------------------------------------------------------------------------------ | Endpoint | Purpose | | --- | --- | | `GET /webhooks/{webhookId}/logs` | List and filter logs (by status, date range, free-text query). | | `GET /webhooks/{webhookId}/logs/{logId}` | Retrieve one specific attempt. | | `POST /webhooks/{webhookId}/logs/{logId}/retry` | Manually enqueue a retry for a webhook event | `WebhookDeliveryStatus` values: `SUCCESS`, `FAILED`. Fields captured per attempt include HTTP status code, error message, timestamp, and attempt number. PLEASE NOTE: We only provide the last 30 days worth of logs. * * * 3rd Party Integrators [](https://devx.pax8.com/docs/how-to-use-webhook-apis#3rd-party-integrators) ------------------------------------------------------------------------------------------------------ This is coming soon. Currently this feature set is available to pax8 partner users only. * * * Automatic Retries & Error-Threshold Email Alerts [](https://devx.pax8.com/docs/how-to-use-webhook-apis#automatic-retries--error-threshold-email-alerts) ----------------------------------------------------------------------------------------------------------------------------------------------------------- 1. The service will attempt to deliver every event **up to 3 times** (initial attempt + **2 automatic retries**). Back-off schedule: 10 s → 30 s → 60 s. 2. Setting the errorThreshold determines how many times in a row your webhook fails before we email you. Our max is currently set to 20 with a default of 10. Setting the threshold lower than 3 will only retry attempt to that number. For example: Threshold set to 2 will only do 1 more retry after a failed attempt. 3. After the final failure the log status is **FAILED**. 4. The `errorThreshold` counter is incremented for each consecutive failure. Even though we will only try a max of 3 calls per event, as other failed event attempts come through, the threshold counter will increment. 5. When the threshold is met **and** the webhook has a `contactEmail`, exactly **one** email alert is sent. 6. A subsequent _successful_ delivery resets the failure counter and allows the next threshold breach to trigger a new email. You can override the threshold (default **10**) per webhook via the configuration endpoint with a max of 20. * * * Common Validation Errors & How to Avoid Them [](https://devx.pax8.com/docs/how-to-use-webhook-apis#common-validation-errors--how-to-avoid-them) --------------------------------------------------------------------------------------------------------------------------------------------------- | Error Message | Likely Cause | Resolution | | --- | --- | --- | | `Invalid URL` | The `url` field is missing scheme or is not https. | Provide a fully-qualified `https://` URL. | | `User does not have access to partner with ID …` | Filters reference `partnerId` that is outside your tenant. | Remove or correct the `partnerId` list. | | `Vendor with ID … not found` | Unknown vendor UUID in filter. | Retrieve valid IDs from Pax8 Catalog API or omit the filter. | | `Action must be one of …` | The `action` string is not present in the topic definition. | Always consult `/webhooks/topic-definitions` before constructing a payload. | | `Filter field vendorId is not allowed for topic PRODUCT` | Field / operator combination not supported. | Double-check `availableFilters` for the topic. | | `AuthorizationDeniedException` | The token lacks the required `webhook_*` scope. | Request a token with the correct scopes. | * * * Pax8 Event Permissions & Behavior [](https://devx.pax8.com/docs/how-to-use-webhook-apis#pax8-event-permissions--behavior) ----------------------------------------------------------------------------------------------------------------------------- _Event emission is permission sensitive._ * If the Pax8 account **does not** have permission to the _Events_ object **no notifications will be produced**, even if webhooks exist. For example: A webhook is subscribed to a specific product, but that product gets removed from that accounts catalog but may still be active. no events will be sent for that removed product until the product is brought back to the catalog.. * * * Frequently Asked Questions [](https://devx.pax8.com/docs/how-to-use-webhook-apis#frequently-asked-questions) ---------------------------------------------------------------------------------------------------------------- **Q – Can I create an inactive webhook first and activate it later?** Yes. Omit `active` or set it to `false`. You can activate later via `POST /webhooks/{id}/status`. **Q – Do you support HMAC signatures?** Not yet. Use the `authorization` field to embed a static secret (e.g. `Bearer `). The service will include the header _exactly as provided_ on every outbound call. Updated 3 months ago * * * Ask AI --- # Provisioning Simulation Scenarios The Simulation feature is a great way for you to do integration testing as close as possible to production, but without affecting real customers and orders. This guide will give useful examples that can help you make the simulator model real scenarios. With that established you can build a testing plan, and expand the scenarios that you are exercising your integration. Simulation Feature Philosophy [](https://devx.pax8.com/docs/provision-simulation-example#simulation-feature-philosophy) --------------------------------------------------------------------------------------------------------------------------- Invoking a simulated order, and then seeing how your system reacts is one of the key ways of seeing if the provisioning integration is working. The endpoint features a “works out of the box” philosophy that should let you invoke a simulated with random values very quickly. This works great for an initial smoke test, but as you want to get into more realistic simulation scenarios, you’ll want to override the default random values with your own data, in order to fit into your testing environment. What follows are some ideas for how you can use this simulation endpoint to work through the life cycle of a few partners turning on a subscription, modifying it, and then deprovisioning. Based on what you learn from this example, you should be able to continue using the simulation endpoint to exercise more events that you want your system to be able to handle such as: * A partner who already has an account, just tried to get a new account * A partner who is from the wrong region tried to order * A particular kind of customer tries to upgrade from trial to paid * And any other combinations of new ordering events + testing state you want. Simulation Walkthrough [](https://devx.pax8.com/docs/provision-simulation-example#simulation-walkthrough) ============================================================================================================= Here is a sample storyline and a walkthrough of how you could use the simulation feature to model it. Here are the situations that we will be simulating 1. Different Partners order new Subscriptions (`NetNew` Request Type) 2. Updating a quantity for a Subscription (`Update` Request Type) 3. Partner orders a Trial Subscription (`TrialConvert` Request Type) 4. Canceling a subscription (`Deprovision` Request Type) These ID’s are randomly generated for illustration purposes. You will make your own test ID’s for use with the simulation endpoint. Let Partner 1 ID = `331684ad-5ad7-431e-9811-476813670a77` Let Partner 1 Enrollment ID = `0f872e4a-51cb-4ceb-b33c-914292958475` Let Company 1M ID = `879812be-de5c-4c52-af49-dfb321f9bffc` Let Partner 2 ID = `2d73eb3c-e96f-497f-b3d1-fb2bcdcca517` Let Partner 2 Enrollment ID = `07ce5c77-9ecf-4e2b-9003-a7c75182c43e` Let Company 2M ID = `f97da0ef-d374-4019-9369-5f8315aa6408` Let Product A ID = `de533202-a97b-46ab-9476-32acb524393e` Let Product B ID = `9ac6ffaa-f58c-466a-a7d1-7d01f1787617` ### Partner 1 buys a new subscription to Product A for Company 1M [](https://devx.pax8.com/docs/provision-simulation-example#partner-1-buys-a-new-subscription-to-product-a-for-company-1m) POST /provision-simulations/order-events JSON `{ "isSimulation": true, "provisionRequest": { "partnerId": "331684ad-5ad7-431e-9811-476813670a77", "partnerName": "Partner 1", "partnerDomain": "partner1.example.com", "partnerEnrollmentId": "0f872e4a-51cb-4ceb-b33c-914292958475", "companyId": "879812be-de5c-4c52-af49-dfb321f9bffc", "companyName": "Company 1M", "productId": "de533202-a97b-46ab-9476-32acb524393e", "productName": "Product A", "quantity": 1, "subscriptionId": "6129b9ef-1fc6-4379-8130-376463e88d71", "type": "NetNew" }, "provisionDetail": { "details": { "exampleCustomerData1": "collectedAtCheckout", "key2": "value" } } }` A new subscription ID is created in Pax8, define S1 id = `6129b9ef-1fc6-4379-8130-376463e88d71` Usually we do not know the value of subscription id until a NetNew subscription is created, but for purposes of simulation, we provide a value to be echo’d back to us. Your system should see this value come in the ProvisionRequest, and record it in the appropriate systems so that you can react to further events for this subscription. ### Partner 2 buys a new subscription to Product A for Company 2M [](https://devx.pax8.com/docs/provision-simulation-example#partner-2-buys-a-new-subscription-to-product-a-for-company-2m) POST /provision-simulations/order-events JSON `{ "isSimulation": true, "provisionRequest": { "partnerId": "2d73eb3c-e96f-497f-b3d1-fb2bcdcca517", "partnerName": "Partner 2", "partnerDomain": "partner2.example.com", "partnerEnrollmentId": "07ce5c77-9ecf-4e2b-9003-a7c75182c43e", "companyId": "f97da0ef-d374-4019-9369-5f8315aa6408", "companyName": "Company 2M", "productId": "de533202-a97b-46ab-9476-32acb524393e", "productName": "Product A", "quantity": 1, "subscriptionId": "d7fd89e7-f90c-4141-9e5a-5d68dbd6f63d", "type": "NetNew" }, "provisionDetail": { "details": { "exampleCustomerData1": "collectedAtCheckout", "key2": "value" } } }` A new subscription ID is created in Pax8, define S2 id = `d7fd89e7-f90c-4141-9e5a-5d68dbd6f63d` You should now be able to observe both S1 and S2 in your system, both for Product A, and there are two different partners and companies. ### Partner 1 updates quantity for subscription 1 [](https://devx.pax8.com/docs/provision-simulation-example#partner-1-updates-quantity-for-subscription-1) POST /provision-simulations/order-events JSON `{ "isSimulation": true, "provisionRequest": { "partnerId": "331684ad-5ad7-431e-9811-476813670a77", "partnerName": "Partner 1", "partnerDomain": "partner1.example.com", "partnerEnrollmentId": "0f872e4a-51cb-4ceb-b33c-914292958475", "companyId": "879812be-de5c-4c52-af49-dfb321f9bffc", "companyName": "Company 1M", "productId": "de533202-a97b-46ab-9476-32acb524393e", "productName": "Product A", "quantity": 5, "subscriptionId": "6129b9ef-1fc6-4379-8130-376463e88d71", "type": "Update" }, "provisionDetail": { "details": { "exampleCustomerData1": "collectedAtCheckout", "key2": "value" } } }` As a result of this order event, you should now see that the quantity in your system for subscription `6129b9ef-1fc6-4379-8130-376463e88d71` went from 1 to 5. ### Partner 2 buys a new subscription to Product B for Company 2M [](https://devx.pax8.com/docs/provision-simulation-example#partner-2-buys-a-new-subscription-to-product-b-for-company-2m) POST /provision-simulations/order-events JSON `{ "isSimulation": true, "provisionRequest": { "partnerId": "2d73eb3c-e96f-497f-b3d1-fb2bcdcca517", "partnerName": "Partner 2", "partnerDomain": "partner2.example.com", "partnerEnrollmentId": "07ce5c77-9ecf-4e2b-9003-a7c75182c43e", "companyId": "f97da0ef-d374-4019-9369-5f8315aa6408", "companyName": "Company 2M", "productId": "9ac6ffaa-f58c-466a-a7d1-7d01f1787617", "productName": "Product B", "quantity": 1, "subscriptionId": "6230822b-fc68-4d0c-a60c-b12f311aded5", "type": "NetNew" }, "provisionDetail": { "details": { "exampleCustomerData1": "collectedAtCheckout", "key2": "value" } } }` A new subscription ID is created in Pax8, define S3 id = `6230822b-fc68-4d0c-a60c-b12f311aded5` We now have 3 subscriptions in the system. Ensure that your records have the correct quantities, products, partners, and companies. ### Partner 1 buys a new trial subscription to Product B for Company 1M [](https://devx.pax8.com/docs/provision-simulation-example#partner-1-buys-a-new-trial-subscription-to-product-b-for-company-1m) If you don’t support trials, you can skip this kind of test, but this demonstrates how the `type` field on a provisionRequest has different semantics. POST /provision-simulations/order-events JSON `{ "isSimulation": true, "provisionRequest": { "partnerId": "331684ad-5ad7-431e-9811-476813670a77", "partnerName": "Partner 1", "partnerDomain": "partner1.example.com", "partnerEnrollmentId": "0f872e4a-51cb-4ceb-b33c-914292958475", "companyId": "879812be-de5c-4c52-af49-dfb321f9bffc", "companyName": "Company 1M", "productId": "9ac6ffaa-f58c-466a-a7d1-7d01f1787617", "productName": "Product B", "quantity": 1, "subscriptionId": "004a4e33-d9c9-48c6-94d3-2f520a081f38", "type": "TrialCreate" }, "provisionDetail": { "details": { "exampleCustomerData1": "collectedAtCheckout", "key2": "value" } } }` A new subscription ID is created in Pax8, define S4 id = `004a4e33-d9c9-48c6-94d3-2f520a081f38` Validate that this new subscription is set to a “Trial” in your system. ### Partner 1 Deprovisions S1 [](https://devx.pax8.com/docs/provision-simulation-example#partner-1-deprovisions-s1) POST /provision-simulations/order-events JSON `{ "isSimulation": true, "provisionRequest": { "partnerId": "331684ad-5ad7-431e-9811-476813670a77", "partnerName": "Partner 1", "partnerDomain": "partner1.example.com", "partnerEnrollmentId": "0f872e4a-51cb-4ceb-b33c-914292958475", "companyId": "879812be-de5c-4c52-af49-dfb321f9bffc", "companyName": "Company 1M", "productId": "de533202-a97b-46ab-9476-32acb524393e", "productName": "Product A", "subscriptionId": "6129b9ef-1fc6-4379-8130-376463e88d71", "type": "Deprovision" }, "provisionDetail": { "details": { "exampleCustomerData1": "collectedAtCheckout", "key2": "value" } } }` As a result of this order event, validate that your records show that Subscription S1 is marked for deprovision and cancellation. ### Querying Simulation Data [](https://devx.pax8.com/docs/provision-simulation-example#querying-simulation-data) For a period of 7 days after simulated data is created, you can query it using your simulation credentials. For example, if a provision request is created as part of a simulated order, you can do a GET with the id of that provision request to get it from the Pax8 API. Or all of them will show up on the list provision requests endpoint. Updated 3 months ago * * * This walkthrough illustrates just a few specific scenarios you might want to test. The simulation endpoint lets you craft your own scenarios, so don't limit your testing to just these ideas. Ask AI --- # Provision Attempt Overview [](https://devx.pax8.com/docs/provision-attempt#overview) ====================================================================== A `ProvisionAttempt` represents a record of an attempt to provision a `ProvisionRequest` using a `ProvisionDetail`. Endpoints [](https://devx.pax8.com/docs/provision-attempt#endpoints) ------------------------------------------------------------------------ ### Get All Provision Attempts for a Provision Request [](https://devx.pax8.com/docs/provision-attempt#get-all-provision-attempts-for-a-provision-request) * Get All `ProvisionAttempt`s for a `ProvisionRequest` * If `provisionDetailId` is provided, it returns the attempts for that specific provision detail * If `provisionDetailId` is not provided, it returns all attempts for the provision request * [GET /provision-requests/{provisionRequestId}/attempts?provisionDetailId={provisionDetailId}](https://devx.pax8.com/reference/getallprovisionattempts) ### Get Provision Attempt by ID [](https://devx.pax8.com/docs/provision-attempt#get-provision-attempt-by-id) * Retrieves a `ProvisionAttempt` for a `ProvisionRequest` * [GET /provision-requests/{provisionRequestId}/attempts/{provisionAttemptId}](https://devx.pax8.com/reference/getoneprovisionattempt) ### Get Latest Provision Attempt for a Provision Request [](https://devx.pax8.com/docs/provision-attempt#get-latest-provision-attempt-for-a-provision-request) * Get Latest ProvisionAttempt for a Provision Request * [GET /provision-requests/{provisionRequestId}/attempts/latest](https://devx.pax8.com/reference/getlatestprovisionattempt) ### Create Provision Attempt for a Provision Request and Provision Detail [](https://devx.pax8.com/docs/provision-attempt#create-provision-attempt-for-a-provision-request-and-provision-detail) * Create Provision Attempt for a Provision Request and Provision Detail * Use this endpoint to create a new Provision Attempt for a given unfulfilled provision request. This can be useful if you want to retry a failed or otherwise unfulfilled provision request. * This action is disallowed if the target provision request is already fulfilled, meaning there is already a successful provision result associated with it * The newly created provision attempt will automatically have an `Acknowledged` status * [POST /provision-requests/{provisionRequestId}/attempts](https://devx.pax8.com/reference/createattemptforrequest) The Provision Attempt Object [](https://devx.pax8.com/docs/provision-attempt#the-provision-attempt-object) ============================================================================================================== Response `{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "provisionDetailId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "string", "errorDetail": "string", "createdDate": "2025-08-01T20:12:54.968Z" }` Additional Information [](https://devx.pax8.com/docs/provision-attempt#additional-information) -------------------------------------------------------------------------------------------------- ### Statuses [](https://devx.pax8.com/docs/provision-attempt#statuses) Possible status of a `ProvisionAttempt` is `Issued`, `Acknowledged`, or `Failed`. `errorDetail` will be null for successful attempts. * `Issued` - After Pax8 sends the Provision Notification we record this attempt as being issued. * `Acknowledged` - If Pax8 receives a `200`, `201`, or `202` status from your webhook endpoint, we record this attempt as `Acknowledged`. * `Failed` - If Pax8 receives an unacceptable status code from your webhook endpoint, we will record this as a `Failed` attempt and you will not be able to provide us with a `ProvisionResult`. ### Nuances [](https://devx.pax8.com/docs/provision-attempt#nuances) * A `ProvisionRequest` and `ProvisionDetail` may have many associated `ProvisionAttempts`. Pax8 creates a `ProvisionAttempt` whenever we notify the Provisioner of an order via webhook. * Each `ProvisionAttempt` contains a `webhookId` which indicates the Webhook Configuration associated with the `ProvisionAttempt`. * Information about how to configure webhooks may be found on the [Webhook Configuration page](https://devx.pax8.com/docs/webhook-configuration) . ### Retries [](https://devx.pax8.com/docs/provision-attempt#retries) If our initial Provision Notification Webhook does not succeed with a `200`, `201`, or `202`, Pax8 employs a retry mechanism. Here's how retries work: * Pax8 will automatically retry the webhook delivery up to three times. * Each retry creates a new `ProvisionAttempt`, allowing for a total of four attempts, the initial attempt plus three retries. Updated 3 months ago * * * Ask AI --- # Overwriting or Appending Same Day Usage Understanding how Pax8 processes usage data, especially when multiple lines are posted for the same subscription on the same day, is key to accurate billing. This page details the default behaviors for same-day usage posting and how you can control them using the`overwriteSameDayUsage` parameter. Please note that the default behavior for the system is to set `overwriteSameDayUsage` to true. Same-Day Posts and `summaryKey` [](https://devx.pax8.com/docs/overwrite-same-day-usage#same-day-posts-and-summarykey) ------------------------------------------------------------------------------------------------------------------------- The `summaryKey` is crucial for differentiating usage items when reported on the same day. * **Different `summaryKey`s on the Same Day:** * If you post multiple usage lines on the same day for the same subscription but with **different** `summaryKey`s, Pax8 will keep and process all of these lines as distinct usage items. For example, if on `2024-08-01` you post: * `summaryKey: "users", quantity: 10` * `summaryKey: "storageGB", quantity: 50` Both lines will be retained as they represent different billable components for `2024-08-01`. * **Same `summaryKey`, Same Day:** * When you post usage multiple times on the same day for the same `Subscription` and the exact same `summaryKey`, the default behavior is to delete and replace any pre-existing usage lines for that identical `usageDate` and `summaryKey`. For example if on `2024-08-01` you post: * `summaryKey: "users", quantity: 50, "productId": "123"` and `summaryKey: "users", quantity: 50, "productId": "678"` together in the morning * `summaryKey: "users", quantity: 50, "productId": "123"` in the evening Product 678 will be deleting and only 123 will be present for the specific summary key > `productId` is of type UUID. It is set as a simple number in the above examples for explanation purposes Controlling Same-Day Overwrites with `overwriteSameDayUsage` [](https://devx.pax8.com/docs/overwrite-same-day-usage#controlling-same-day-overwrites-with-overwritesamedayusage) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `overwriteSameDayUsage` flag is an _optional_ boolean query parameter available on the `/usage/lines` and `/usage/aggregate-lines` endpoints. It allows you to define how the system should handle new usage lines when there are existing ones for the same `summaryKey` that were posted earlier in the same day. ### Default Behavior: Overwriting Usage (`overwriteSameDayUsage=true` or parameter omitted) [](https://devx.pax8.com/docs/overwrite-same-day-usage#default-behavior-overwriting-usage-overwritesamedayusagetrue-or-parameter-omitted) By default, if you do not include the `overwriteSameDayUsage` parameter in your request, or if you explicitly set it to `true`, any new usage lines posted will **delete and replace** any pre-existing usage lines that were posted on the same day for that identical `summaryKey`. * **Scenario:** You need to correct a usage quantity reported earlier on the same day, or you are simply sending the latest snapshot of usage for that day. * **Example:** 1. At 10:00 AM UTC on `2024-08-01`, you post: JSON `POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08 [ { "summaryKey": "company-id", "summaryDisplayName": "Company Name", "quantity": 100, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "unit" } ]` 2. At 03:00 PM UTC on the same day (`2024-08-01`), you realize the correct count is 105 and post again (either omitting `overwriteSameDayUsage` or setting it to `true`): JSON `POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08&overwriteSameDayUsage=true [ { "summaryKey": "company-id", "summaryDisplayName": "Company Name", "quantity": 105, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "unit" } ]` * **Result:** The initial usage line (quantity 100) from 10:00 AM is deleted. The system retains only the second usage line (quantity 105) for `summaryKey: "company-id"` on `usageDate: "2024-08-01"`. ### Appending Usage (`overwriteSameDayUsage=false`) [](https://devx.pax8.com/docs/overwrite-same-day-usage#appending-usage-overwritesamedayusagefalse) If you wish to add new usage lines on the same day without deleting existing ones for the same `summaryKey`, you must set the `overwriteSameDayUsage` parameter to `false`. * **Scenario:** You are reporting usage incrementally throughout the same day, and each post represents an additional amount of usage rather than a total replacement for that day. * **Example:** 1. At 09:00 AM UTC on `2024-08-01`, you post processed data indicating 5 units of usage: Request `POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08 [ { "summaryKey": "company-id", "summaryDisplayName": "Company Name", "quantity": 5, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "unit" } ]` 2. At 02:00 PM UTC on the same day (`2024-08-01`), you post another batch of usage line data, adding 3 more units of usage and `overwriteSameDayUsage` set to false: JSON `POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08&overwriteSameDayUsage=false [ { "summaryKey": "company-id", "summaryDisplayName": "Company Name", "quantity": 3, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "unit" } ]` * **Result:** Both usage lines for `summaryKey: "company-id"` on `usageDate: "2024-08-01"` are kept. The system will have one record for `quantity: 5` (from 09:00 AM) and another for `quantity: 3` (from 02:00 PM) for that day. Both of these lines would then be saved in the p8p system, and, if no other activity happened for the rest of the billing period, Pax8 would bill out 2 lines for `summaryKey: "transactions"`: One line with `quantity: 5` and another with `quantity: 3` By understanding and utilizing the `summaryKey` and the `overwriteSameDayUsage` parameter effectively, vendors can ensure accurate and flexible usage reporting to Pax8 for same-day postings. Updated 3 months ago * * * Ask AI --- # Request and Response Examples Full Net New Example [](https://devx.pax8.com/docs/examples#full-net-new-example) ===================================================================================== Below is an example of specifying a custom simulation event for Provision Notification with a `NetNew` Provision Request type. If you specify every single field in the order events body like the request below, all of the information will be echoed back to you in the Provision Notification that Pax8 sends you. Request `curl --request POST \ --url https://api.pax8.com/v2/provision-simulations/order-events \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' { "provisionRequest": { "partnerAddress": { "street": "123 Fake Street", "city": "Best City", "street2": "Unit 3", "postcode": "11111", "country": "US", "stateOrProvince": "Colorado" }, "companyAddress": { "stateOrProvince": "CO", "country": "US", "postcode": "22222", "city": "Best City", "street2": "Suite 7", "street": "987 Real Street" }, "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 150, "maxAmount": 250, "unitOfMeasure": "Points", "months": 1 } }, "partnerName": "Super Partner", "partnerDomain": "super.partner", "companyName": "Great Company", "companyDomain": "great.company", "productName": "Best Product", "quantity": 7, "type": "NetNew", "commitmentTermMonths": 12, "billingTerm": "Annual", "id": "13451896-985d-49c2-830d-b852aa6b5e40", "partnerId": "1427aef1-3c96-4ee2-ba2c-2802a2e15da1", "partnerEnrollmentId": "42aeb583-e0b5-41bf-a5f9-76fce7e6dff6", "companyId": "d49d261f-b802-41bb-ba73-0dbdd22ddcdd", "productId": "75015627-3163-4972-aaae-3e9930e67f81", "subscriptionId": "9f4a34a9-37ca-439e-a89c-2013f42b49e2", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermEndDate": "2025-04-08T19:54:03Z" }, "provisionDetail": { "details": { "someKey": "someValue" }, "id": "8fd85e8e-27d7-45f3-ac73-a64826c42a95", "provisionRequestId": "de53ef36-afef-4172-90a6-5611ae06e5b6", "createdDate": "2025-04-08T19:54:11Z" }, "provisionAttempt": { "id": "06ac5243-d257-446c-8c80-bf59f18a7aac", "provisionDetailId": "8fd85e8e-27d7-45f3-ac73-a64826c42a95", "webhookId": "dd15fbf3-8004-4423-90c7-4ff35171fe5d", "status": "Issued", "createdDate": "2025-04-08T19:54:11Z" }, "isSimulation": true } '` Response `{ "provisionRequest": { "id": "0b858eb9-13b5-468d-850d-192192d1359b", "partnerId": "1427aef1-3c96-4ee2-ba2c-2802a2e15da1", "partnerName": "Super Partner", "partnerDomain": "super.partner", "partnerAddress": { "street": "123 Fake Street", "street2": "Unit 3", "city": "Best City", "postcode": "11111", "country": "US", "stateOrProvince": "Colorado" }, "partnerEnrollmentId": "42aeb583-e0b5-41bf-a5f9-76fce7e6dff6", "companyId": "d49d261f-b802-41bb-ba73-0dbdd22ddcdd", "companyName": "Great Company", "companyDomain": "great.company", "companyAddress": { "street": "987 Real Street", "street2": "Suite 7", "city": "Best City", "postcode": "22222", "country": "US", "stateOrProvince": "CO" }, "productId": "75015627-3163-4972-aaae-3e9930e67f81", "productName": "Best Product", "quantity": 7, "subscriptionId": "9f4a34a9-37ca-439e-a89c-2013f42b49e2", "type": "NetNew", "createdDate": "2025-08-05T20:01:22.600597346Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 150, "maxAmount": 250, "unitOfMeasure": "Points", "months": 1 } }, "billingTerm": "Monthly" }, "provisionDetail": { "id": "fd0f9e2f-1f7a-4281-8f0b-2102945cc5a8", "provisionRequestId": "0b858eb9-13b5-468d-850d-192192d1359b", "details": { "someKey": "someValue" }, "createdDate": "2025-08-05T20:01:22.600605046Z" }, "provisionAttempt": { "id": "e9577538-733d-4335-9a97-649de1fa45b1", "provisionDetailId": "fd0f9e2f-1f7a-4281-8f0b-2102945cc5a8", "webhookId": "a3ee5fab-a1ee-4035-99b1-210a8c729269", "status": "Acknowledged", "createdDate": "2025-08-05T20:01:22.600612546Z" }, "isSimulation": true }` After POSTing the Order Event, you will receive a Provision Notification from the Pax8 simulation at the URL specified in your latest simulation Webhook Configuration. Empty or Partial Example [](https://devx.pax8.com/docs/examples#empty-or-partial-example) ============================================================================================= Since every field in the payload to the order events page is optional, it is possible to POST to the order events endpoint with an empty request body, and Pax8 will auto generate values for anything that was absent. For example, if you make a request like the one below: Request `POST /provision-simulations/order-events {} curl --request POST \ --url https://api.pax8.com/v2/provision-simulations/order-events \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' '` You would still receive a full response from the order events endpoint, and you would still receive a full webhook, like in the previous example, only all the values will have been generated by the Pax8 system according to the defaults listed above these examples. You can also omit or include any number of the fields from the body. If, for example, you only care to to test that your system can ingest certain provision detail keys called `adminEmail` and `adminPhone`, you could send an order events request that looks like this: Request `curl --request POST \ --url https://api.pax8.com/v2/provision-simulations/order-events \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' { "provisionDetail": { "details": { "adminEmail": "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "adminPhone": "800-555-7777" } } } '` In this case, the webhook you receive from Pax8 will have auto generated default values for everything _except_ these provision details. It might look like this: Response `{ "provisionRequest": { "id": "be407b00-1e6d-4739-ac7c-dd41bd04e6ac", "partnerId": "ad9b2e3c-2e35-4226-8017-0aac3663e0a6", "partnerName": "Example Partner Name", "partnerDomain": "example.com", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit B", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "partnerEnrollmentId": "3d124400-b40a-4cd6-9d3f-0973cf5b7493", "companyId": "5aa65974-255e-462b-a632-73ffbe1fd82e", "companyName": "Example Company Name", "companyDomain": "example.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit C", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "6be72f2f-b4d1-42f8-bd3d-0c595d515ab7", "productName": "Product ABC", "quantity": 1, "subscriptionId": "bd91fa57-5b1a-46c0-9829-73d92b5955a9", "type": "NetNew", "createdDate": "2025-08-05T20:07:40.934630911Z", "commitmentTermMonths": 25, "commitmentTermEndDate": "2027-09-05T20:07:40.934563560Z", "commitment": { "term": { "months": 25, "endDate": "2027-09-05T20:07:40.934563560Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 25 } }, "billingTerm": "Monthly" }, "provisionDetail": { "id": "c1823834-140b-49c9-8011-5973d9c70a3f", "provisionRequestId": "be407b00-1e6d-4739-ac7c-dd41bd04e6ac", "details": { "adminEmail": "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "adminPhone": "800-555-7777" }, "createdDate": "2025-08-05T20:07:40.934637531Z" }, "provisionAttempt": { "id": "3478a020-bc92-4585-a553-10cdc2a7d982", "provisionDetailId": "c1823834-140b-49c9-8011-5973d9c70a3f", "webhookId": "a3ee5fab-a1ee-4035-99b1-210a8c729269", "status": "Acknowledged", "createdDate": "2025-08-05T20:07:40.934643941Z" }, "isSimulation": true }` Notice how all of the fields have their default values except in the `details` map, where the details you specified in the initial request are echoed back just as you entered them. Updated 3 months ago * * * Ask AI --- # Provisioning Overview Below is a quick introduction to the basics of using the provisioning endpoints. Base Url [](https://devx.pax8.com/docs/provisioning-overview#base-url) -------------------------------------------------------------------------- The base url for all provisioning requests is `https://api.pax8.com/v2` Terminology [](https://devx.pax8.com/docs/provisioning-overview#terminology) -------------------------------------------------------------------------------- The Pax8 Provisioning API provides a way for Vendors to easily fulfill Pax8 Orders. Here are a few key terms: * `Provision` - To fulfill a Pax8 Order by creating the necessary cloud resources, communicating results to Pax8, and providing credentials for the cloud resources to the `Partner`. * `Partner` - A Pax8 Partner, also known as a Managed Service Provider (MSP). Manages cloud software for a `Company` and are Pax8's primary users. * `Company` - A Pax8 Company, also known as an End User. A `Company` buys cloud software from a `Partner` * `Subscription` - A record in Pax8 for a specific `Partner`/`Company`/`Product` combination in the Pax8 system. * `Provisioner` - An entity that provisions Pax8 orders, also known as a Pax8 Vendor. More [here](https://devx.pax8.com/docs/provisioner) * `ProvisionRequest` - Contains basic information about a purchase which cannot change. More [here](https://devx.pax8.com/docs/provision-request) * `ProvisionDetail` - Contains information a user entered at checkout. More [here](https://devx.pax8.com/docs/provision-detail) * `ProvisionAttempt` - Represents an attempt by Pax8 to send your system a Provision Notification. More [here](https://devx.pax8.com/docs/provision-attempt) * `Provison Notification` - An outbound message from Pax8 comprising of a `ProvisionRequest`, `ProvisionDetail`, and `ProvisionAttempt`. More [here](https://devx.pax8.com/docs/provision-notification-webhook) * `ProvisionResult` - Represents the end result for a given `ProvisionAttempt` (`Success` or `Fail`). More [here](https://devx.pax8.com/docs/provision-result) How Provisioning Works [](https://devx.pax8.com/docs/provisioning-overview#how-provisioning-works) ------------------------------------------------------------------------------------------------------ 1. `Partner` orders from Pax8 2. Pax8 sends a Provision Notification via Webhook to the vendor 3. `Provisioner` provisions cloud resources 4. `Provisioner` emails `Partner` information and credentials for cloud resources 5. `Provisioner` notifies Pax8 with `ProvisionResults` using the Provisioning API 6. `Partner` has a `Subscription` in Pax8 they can then modify or cancel at any time OpenAPI Spec [](https://devx.pax8.com/docs/provisioning-overview#openapi-spec) ---------------------------------------------------------------------------------- You can find the complete OpenAPI Spec for the provisioning API [here](https://devx.pax8.com/openapi/6614696de22531001ec2895e) Updated 3 months ago * * * * [Provision Notification](https://devx.pax8.com/docs/provision-notification) Ask AI --- # Introduction for Marketplace Vendors This is a quick introduction for new and existing vendors integrating to our API. We'd also highly recommend utilizing the robust search functionality in the top right corner. Guidelines [](https://devx.pax8.com/docs/introduction-for-marketplace-vendors#guidelines) --------------------------------------------------------------------------------------------- To ensure a seamless integration with our API, please design your API with scalability in mind, implementing clear versioning and robust error handling. This flexibility will help maintain compatibility and performance as our systems evolve. Integration Workflow [](https://devx.pax8.com/docs/introduction-for-marketplace-vendors#integration-workflow) ----------------------------------------------------------------------------------------------------------------- 1. Vendor reviews all Pax8 Vendor Marketplace documentation under 'Vendors' section 2. Vendor receives simulation and production credentials from Pax8 3. Vendor configures separate webhooks for both simulation and production credentials 4. Vendor conducts successful simulation testing for all applicable provisioning order types outlined in API documentation and verifies with Pax8 (**note**: simulating usage is not available at this time) 5. Pax8 provides applicable data mapping requirements to vendor 6. Vendor and Pax8 verify all technical requirements are met 7. Vendor and Pax8 conduct and verify successful production testing Testing [](https://devx.pax8.com/docs/introduction-for-marketplace-vendors#testing) --------------------------------------------------------------------------------------- Pax8 does not have a sandbox environment where you can log in and test this integration, nor can you experience the full order-to-cash process from a partner's perspective. Instead, we offer a non-UI simulation environment for testing provisioning orders. For more detailed guidance, please refer to [Provisioning Integration Testing](https://devx.pax8.com/docs/provisioning-integration-testing) and [Provisioning Simulation Scenarios](https://devx.pax8.com/docs/provision-simulation-example) . > 🚧 > > Please note that **simulation testing for usage is not available**. The recommended method for testing usage is to partner with Pax8 for a production test using a test subscription ID. > > > ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Additionally, it's important to differentiate between the webhook configurations using production credentials and simulation credentials: * The Webhook Configuration created with production credentials is separate from the one created with simulation credentials. * When transitioning to production testing, ensure that you've configured a new Webhook Configuration using your production credentials. Understanding Billing Models for API Integration [](https://devx.pax8.com/docs/introduction-for-marketplace-vendors#understanding-billing-models-for-api-integration) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When integrating with our API, it's essential to understand our two primary billing models and their respective requirements: ### Bill Ahead/Entitlement [](https://devx.pax8.com/docs/introduction-for-marketplace-vendors#bill-aheadentitlement) In this model, Pax8 serves as the source of truth. We send your system a Provision Notification that includes the license quantity along with other provision information. Your integration should focus solely on the [Provisioning Endpoints](https://devx.pax8.com/docs/how-to-use-provisioning-endpoints) to manage orders and subscriptions effectively. It's crucial that partners or customers cannot alter the quantity in your system as it must align with our records to prevent discrepancies. This model supports both monthly and annual billing, indicated by "billingTerm" in the Provision Request. ### Billed in Arrears/Usage-Based [](https://devx.pax8.com/docs/introduction-for-marketplace-vendors#billed-in-arrearsusage-based) This model bills based on the previous month's usage. When a partner orders a product under this model, Pax8 sends a Provision Notification with license quantity of 1 - which cannot be changed - and you submit daily usage data to Pax8. Your integration needs to cover both the [Provisioning Endpoints](https://devx.pax8.com/docs/provisioning-overview) and [Usage Endpoints](https://devx.pax8.com/docs/usage-overview) to accurately track and bill for usage. Both models can accommodate [Commitment Terms](https://devx.pax8.com/docs/provision-request#commitment-terms) , such as monthly payments with annual commitments. Updated 3 months ago * * * * [Provisioning Overview](https://devx.pax8.com/docs/provisioning-overview) * [Usage Overview](https://devx.pax8.com/docs/usage-overview) Ask AI --- # Provisioner and Webhooks Provisioner [](https://devx.pax8.com/docs/provisioner#provisioner) ====================================================================== A `Provisioner` is synonymous with a Pax8 Vendor. `Provisioner` systems provision orders sent to them by Pax8. Endpoints [](https://devx.pax8.com/docs/provisioner#endpoints) ------------------------------------------------------------------ ### Get All Provisioners [](https://devx.pax8.com/docs/provisioner#get-all-provisioners) * Gets All `Provisioners` * [GET /provisioners](https://devx.pax8.com/reference/getallprovisioners) ### Get A Provisioner by ID [](https://devx.pax8.com/docs/provisioner#get-a-provisioner-by-id) * Get A `Provisioner` by ID * [GET /provisioners/{provisionerId}](https://devx.pax8.com/reference/getoneprovisioner) The Provisioner Object [](https://devx.pax8.com/docs/provisioner#the-provisioner-object) ============================================================================================ Provisioner `{ "id":"3fa85f64-5717-4562-b3fc-2c963f66afa6", "createdDate":"2025-08-04T21:53:58.808Z", "vendorId":"3fa85f64-5717-4562-b3fc-2c963f66afa6", "name":"string" }` Webhooks [](https://devx.pax8.com/docs/provisioner#webhooks) ================================================================ Webhook Configuration is tied to the Provisioner. In order to configure your webhook please visit the [Webhook Configuration page](https://devx.pax8.com/docs/webhook-configuration) . Updated 3 months ago * * * Visit the Webhook Configuration Page Ask AI --- # How To Use Webhooks As a 3rd Party Integrator The Pax8 Webhook service allows integrators to subscribe to near-real-time data changes across the Pax8 platform. This guide explains how to properly configure and use webhooks as an integrator. The process is largely the same as creating webhooks as a Pax8 Partner, with the main difference being the required "integrationId" and the fact that multiple partner events will trigger your webhooks. See this [webhook guide](https://devx.pax8.com/docs/how-to-use-webhook-apis) for more details. Creating Webhooks with Integration ID [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#creating-webhooks-with-integration-id) ------------------------------------------------------------------------------------------------------------------------------------------------------------ When creating webhooks as an INTEGRATOR user, you must provide an `integrationId` parameter. This parameter is required and links your webhook to your integration. ### Request Format [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#request-format) JSON `POST /webhooks { "displayName": "My Integration Webhook", "url": "https://my-integration.example.com/webhook", "contactEmail": "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "errorThreshold": 5, "authorization": "Bearer my-secret-token", "webhookTopics": [ { "topic": "INVOICE", "filters": [ { "action": "CREATED", "conditions": [] } ] } ], "active": true, "integrationId": "550e8400-e29b-41d4-a716-446655440000" }` Key Points for Integrators [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#key-points-for-integrators) -------------------------------------------------------------------------------------------------------------------------------------- ### Required Integration ID [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#required-integration-id) As an INTEGRATOR, you must provide your `integrationId` when creating webhooks. The system will validate this requirement and reject requests without a valid integration ID. This id can be provided when you create an integration application. See [Integrators guide](https://devx.pax8.com/docs/integrator-setup-guide) for more details. ### Partner Access Control [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#partner-access-control) When you create a webhook, you'll receive events for all partners that have granted you delegated authorization. The webhook system automatically filters events based on your current access permissions and provided filters. ### Revocation Handling [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#revocation-handling) If a partner revokes their permission to your integration, you'll continue to receive webhook events for your remaining authorized partners. The system will automatically stop sending events related to the partner who revoked access. ### Topic Subscription [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#topic-subscription) You can control which event topics your webhooks subscribe to by configuring the `webhookTopics` list in your request. This allows you to receive only the events relevant to your integration. ### Webhook Configuration Options [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#webhook-configuration-options) You can customize your webhook with: * **displayName**: A human-readable name for your webhook * **url**: The destination URL where events will be sent * **contactEmail**: Email for notifications about webhook delivery issues * **errorThreshold**: Number of retry attempts (max 20) and the threshold in which we will email you * **authorization**: Optional authorization header to secure your endpoint * **active**: Whether the webhook is active or paused * **integrationId**: Your integration's unique identifier (required) Webhooks as Notification Triggers, Not Data Sources [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#webhooks-as-notification-triggers-not-data-sources) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Notification System vs. Source of Truth [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#notification-system-vs-source-of-truth) Webhooks in the Pax8 platform are designed as a notification system, not as a comprehensive data source. They provide minimal information about events that have occurred, serving primarily as triggers for your integration to take further action. Key points to understand: * Webhook payloads contain only basic event information (event type, relevant IDs, timestamp) * Webhooks do not provide complete entity data or full context * The payload data is intentionally minimal to ensure fast delivery ### Follow-up API Workflow Pattern [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#follow-up-api-workflow-pattern) The recommended integration pattern is: 1. Receive webhook notification of an event 2. Extract the relevant identifiers from the webhook payload 3. Call the appropriate Pax8 public API endpoints to retrieve complete, current information 4. Process the full data according to your integration's requirements This pattern ensures your integration always works with the most up-to-date and complete information. Best Practices [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#best-practices) -------------------------------------------------------------------------------------------------------------- 1. **Implement Idempotency**: Design your webhook handler to be idempotent, as the same event may be delivered multiple times in rare circumstances. 2. **Respond Quickly**: Your endpoint should respond with a 2xx status code within 5 seconds to avoid timeouts. 3. **Monitor Delivery Status**: Use the webhook management API to check delivery status and troubleshoot issues. 4. **Secure Your Endpoint**: Use the authorization header to validate incoming webhook requests. 5. **Set Up Alerts**: Configure the contactEmail to receive notifications about persistent delivery failures. 6. **Use Webhooks as Triggers**: Treat webhooks as event notifications that should trigger API calls for complete data. 7. **Implement Retry Logic**: Add appropriate retry mechanisms when calling APIs after webhook receipt. Troubleshooting [](https://devx.pax8.com/docs/how-to-use-webhooks-as-a-3rd-party-integrator#troubleshooting) ---------------------------------------------------------------------------------------------------------------- If you're not receiving expected events, check: 1. Your webhook is marked as active 2. You have the correct partner permissions 3. Your endpoint is responding with 2xx status codes 4. Your topic and filter configuration matches the events you want to receive 5. Your follow-up API calls include proper authentication and parameters Updated 2 months ago * * * Ask AI --- # MCP Setup Guide (Claude) This guide instructs users on setting up the MCP Server and enabling Claude Desktop integration for both Windows and macOS systems. Prerequisites [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#prerequisites) ------------------------------------------------------------------------------------------------- Before beginning the setup process, you will need to: * Access to a Pax8 account (app.pax8.com) * Administrative privileges on your computer * Internet connection for downloading required software Step 1: Access the Pax8 Integrations Page [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#step-1-access-the-pax8-integrations-page) -------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Sign in to [app.pax8.com](https://app.pax8.com/) 2. On the left pane, select **Settings** > **Integrations** Step 2: Generate Authentication Token [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#step-2-generate-authentication-token) ------------------------------------------------------------------------------------------------------------------------------------------------ 1. Navigate to the Integrations page 2. On the **Integrations** page, select the **MCP server** box at the top 3. Under **MCP Token and Authentication**, select **Generate Token** * The page will refresh automatically after token generation Step 3: Install Node.js v18 [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#step-3-install-nodejs-v18) --------------------------------------------------------------------------------------------------------------------------- Node.js v18 is the minimum requirement to access the MCP Server. ### Initial Steps (All Platforms) [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#initial-steps-all-platforms) 1. On the Integrations page, select the **MCP server** tab 2. On the right **Info** panel, under **Prerequisites**, select **Node.js v18** 3. On [nodejs.org](http://nodejs.org/) , select **Download** 4. On the **Download Node.js** page, locate the dropdown for a prebuilt Node.js ### Platform-Specific Download and Installation [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#platform-specific-download-and-installation) #### Windows [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#windows) 5. Select **Windows** from the dropdown 6. Select **Windows installer (.msi)** 7. Access the `node-v[semver version].msi` file on your device #### macOS [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#macos) 5. Select **macOS** from the dropdown 6. Select **macOS installer (.pkg)** 7. Access the `node-v[semver version].pkg` file on your device ### Installation Process (All Platforms) [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#installation-process-all-platforms) 8. On the **Install Node.js** wizard, select **Continue** 9. Read the **Software License Agreement** and select **Continue** 10. Select **Agree** to the terms of the agreement 11. Select **Install** (you will be prompted to enter your device's username and password) 12. Enter your login details and select **Install Software** 13. When download is complete, select **Close** Step 4: Install Claude Desktop [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#step-4-install-claude-desktop) ---------------------------------------------------------------------------------------------------------------------------------- Prior to downloading the Claude Desktop app, ensure you have completed Steps 1-3 (token generation and Node.js installation). ### Download Claude Desktop [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#download-claude-desktop) 1. On the Integrations page, select the **MCP server** tab 2. On the right **Info** panel, under **Prerequisites**, select **Claude Desktop** #### Windows [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#windows-1) 3. On the Claude Download page, select **Windows** 4. Access the `Claude.exe` file on your device * Default directory: `C:\Users\your-username\AppData\Roaming\Claude` #### macOS [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#macos-1) 3. On the Claude Download page, select **macOS** 4. Access the `Claude.dmg` file on your device ### Install and Setup Claude Desktop [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#install-and-setup-claude-desktop) 5. Follow the instructions to download and install 6. Open your newly-downloaded **Claude** application #### macOS Additional Step [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#macos-additional-step) 7. On the **Claude for Mac** wizard, select **Get Started** #### Continue for All Platforms [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#continue-for-all-platforms) 8. Choose your sign-in method and create an account 9. You will be prompted with the following before accessing the Claude app: * **"Do you want to allow this website to open 'Claude'?"** * **"Use Quick entry to send messages and screenshots to Claude from any app."** 10. Verify that the Claude Desktop chat window is open Step 5: Configure Claude Desktop [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#step-5-configure-claude-desktop) -------------------------------------------------------------------------------------------------------------------------------------- ### Access Settings [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#access-settings) #### Windows [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#windows-2) 11. Select the menu icon > **Settings…** #### macOS [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#macos-2) 11. On the top menu, select **Claude** > **Settings…** ### Edit Configuration [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#edit-configuration) 12. On the **Settings** module, select **Developer** > **Edit Config** 13. Open `claude_desktop_config.json` (the file will open in your device's default text editor) 14. Navigate back to the Integrations > **MCP Server** page in your browser 15. Scroll down to the **Connect** section and select **Claude** 16. Select **Copy Code** (this will copy the configuration with your MCP token already in place to the clipboard) 1. 1. OR you can copy this code and replace with your unique token 2. JSON `{ "mcpServers": { "supergateway-pax8": { "command": "npx", "args": [ "-y", "[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ", "--header", "x-pax8-mcp-token:YOUR-MCP-TOKEN-HERE", "--streamableHttp", "https://mcp.pax8.com/v1/mcp" ] } } }` 2. 17. Locate your text editor window with `claude_desktop_config.json` and replace the existing text with your copied code 18. On the top menu, select **File** > **Save** 19. Exit the text editor once the file is saved ### Apply Configuration Changes [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#apply-configuration-changes) #### Windows [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#windows-3) 20. Exit the Claude Desktop application 21. Reopen the Claude Desktop app #### macOS [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#macos-3) 20. Exit the Claude Desktop application by selecting **Claude** > **Quit** from the top menu 21. Reopen the Claude Desktop app Step 6: Verify Integration [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#step-6-verify-integration) -------------------------------------------------------------------------------------------------------------------------- 22. Select the **Adjust** icon on the chat window (a modal will appear) 23. Select **supergateway-pax8** (there should be a corresponding number next to it) 24. Verify that there is a list of tools available under **supergateway-pax8** 25. Claude Desktop should now be integrated with the Pax8 MCP Server Optional: Getting Started [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#optional-getting-started) ------------------------------------------------------------------------------------------------------------------------ Use the sample prompts available on the Integrations > **MCP Server** page to begin exploring the integration capabilities. Troubleshooting [](https://devx.pax8.com/docs/pax8-mcp-server-setup-guide-claude#troubleshooting) ----------------------------------------------------------------------------------------------------- If you encounter issues during setup: * Ensure Node.js v18 or higher is properly installed * Verify that your authentication token was generated successfully * Check that the `claude_desktop_config.json` file was saved correctly * Restart Claude Desktop after making configuration changes For additional support, refer to the Pax8 documentation or contact your system administrator or see Clause official documentation: [https://modelcontextprotocol.io/quickstart/user](https://modelcontextprotocol.io/quickstart/user) Updated 2 months ago * * * Ask AI --- # Provisioning Integration Testing Before you go live with Pax8, you can test your integration by creating simulated events and viewing test data. Pax8 provides the ability to simulate an order coming from our system. You can make a POST request to our order events endpoint, and our system will act as though an order was just placed in our marketplace. Our system will create a `ProvisionRequest`, `ProvisionDetail`, and `ProvisionAttempt`with some test data, as well as send a Provision Notification with the newly created objects to the endpoint configured in your Webhook Configuration. Simulating orders using the order events endpoint is only possible with a separate set of credentials. When you first get credentials to use with the provisioning api, you will get two sets: one for live production requests, and another to use for simulating order events. You cannot use live production credentials to hit the order events endpoint; only the simulation credentials will work. When you simulate an order, that persists some test data in the Pax8 system that has a lifespan of 7 days. This test data is siloed away from real production data. You can use the simulation credentials to query the provisioning api for the test data that has been created, as well as post `ProvisionResults` for any test `ProvisionRequests` that have been created. When using simulation credentials to query the api, you will not be able to see any live production data. Similarly, when using live production credentials to query the provisioning api, no simulated data will be returned. Despite the facts that simulated and production data are siloed from each other, and that you need separate credentials to simulate orders, the simulation feature does not represent a true staging or sandbox environment. There is no Pax8 marketplace sandbox UI to view test data created by the simulations feature. Requests to simulate orders are still just made to the Pax8 production api; they just require separate credentials. Outbound Provision Webhook Notifications for simulated orders will still come from the Pax8 production api servers. When using simulation credentials, you will have a different `provisionerId` in the Pax8 system than when you are using the live production credentials. Similarly, webhook configurations for simulated events are a separate entity from the webhook configurations made by live production credentials. This means that you will have to go through the exercise of configuring your webhook using simulation credentials to point at your testing system, and later you will need to do this again using the live production credentials and point the webhook configuration at your production system. Credentials for Generating Simulated Orders [](https://devx.pax8.com/docs/provisioning-integration-testing#credentials-for-generating-simulated-orders) ----------------------------------------------------------------------------------------------------------------------------------------------------------- * Your Pax8 contact will give you simulation credentials, which you can use in place of your production `clientId` and `clientSecret`. * Use these simulation credentials whenever you trigger testing events or to access any data created as part of a simulation. * Live data is not visible when using simulation credentials and test data is not visible to production credentials * You will have a different `provisionerId` when using production credentials compared to simulation credentials * Test data only persists for 7 days. Please see the [Data Expiration section](https://devx.pax8.com/docs/provisioning-integration-testing#data-expiration) for more info. Simulating an Order [](https://devx.pax8.com/docs/provisioning-integration-testing#simulating-an-order) ----------------------------------------------------------------------------------------------------------- You can simulate an incoming order from Pax8 to test your integration to our Provisioning API. Simulating an order event provides you with data in the same form as what you would receive from a production Provision Notification. Steps to simulating an order: 1. Obtain your simulation credentials from your Pax8 Contact. These credentials will be used to gain access to the simulation functionality. 2. Configure your webhook within our simulation environment using an [authorization token](https://devx.pax8.com/docs/authentication#for-marketplace-vendors) generated from the simulation credentials provided. To configure your webhook, refer to our [webhook configuration](https://devx.pax8.com/docs/webhook-configuration) guide. 3. POST to the Order Events endpoint to simulate an order event. 4. Handle the Simulated Data. Once the request is made to the testing endpoint `/provision-simulations/order-events`, your testing webhook endpoint will receive the simulated order data. 5. Your application must be designed to handle incoming Provision Notifications, process the data accordingly, and send a Provision Result to the Pax8 system. > All simulated Provision Notifications have the `isSimulation` flag set to `true`. Endpoints [](https://devx.pax8.com/docs/provisioning-integration-testing#endpoints) --------------------------------------------------------------------------------------- ### Create Order Event [](https://devx.pax8.com/docs/provisioning-integration-testing#create-order-event) * Create a Simulation Order Event * [POST /provision-simulations/order-events](https://devx.pax8.com/reference/createorderevent) The Order Event Object [](https://devx.pax8.com/docs/provisioning-integration-testing#the-order-event-object) ================================================================================================================= A simulated order event will create : * `Provision Request` - Contains placeholder data similar to a real request * `Provision Detail` - You may specify the key/value pairs you'd like to receive * `Provision Attempts` - In simulation mode `Provision Attempts` are not retried when they are not acknowledged Provision Notification `{ "isSimulation": true, "provisionRequest": { "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "example.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3aa9e9e02", "trialEndDate": "2022-12-03T10:15:30Z", "trialAutoConverts": "true", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "compayDomain": "example.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "TrialCreate", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }, "provisionDetail": { "id": "8fcf68db-c30e-4f34-b773-bc1631cd1fef4", "provisionRequestId": "eb77429f-b313-4916-9bed-ccc1c373dff7", "details": { "key": "value", "key2": "value" } }, "provisionAttempt": { "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9", "provisionDetailId": "8fcf68db-c30e-4f34-b773-bc1631cd1fef4", "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41", "status": "Acknowledged", "createdDate": "2022-10-03T10:15:30Z" } }` Create a Provision Order Event [](https://devx.pax8.com/docs/provisioning-integration-testing#create-a-provision-order-event) --------------------------------------------------------------------------------------------------------------------------------- All fields are optional when you create an Order Event. Pax8 will default the value according to the following conventions: | Field Name | Default Value | | --- | --- | | All UUID fields \* | Random UUID | | quantity | 1 | | partnerName | Example Partner Name | | partnerDomain | example.com | | partnerAddress | {
"street": "123 Partner Ave.",
"street2": "Unit b",
"city": "Denver",
"postcode": "80210",
"country": "US",
"stateOrProvince": "CO"
} | | companyDomain | example.com | | companyAddress | {
"street": "123 Company Ave.",
"street2": "Unit c",
"city": "Denver",
"postcode": "80210",
"country": "US",
"stateOrProvince": "CO"
} | | type | NetNew | | productName | Product ABC | | companyName | Example Company Name | | provisionDetail | {} | | commitmentTermMonths | Random integer between 1 and 36 | | commitmentTermEndDate | Now + commitmentTermMonths | | commitment.volume.minAmount | 1 | | commitment.volume.maxAmount | 10 | | commitment.volume.unitOfMeasure | Users | | commitment.volume.months | 1 | | commitment.term.endDate | Now + commitment.term.months | | commitment.term.months | Random integer between 1 and 36 | | billingTerm | Monthly | | trialEndDate\*\* | Now | | trialAutoConverts \*\* | true | \* `oldProductId` only appears for `ChangeProduct` Provision Request types \*\* Only appears for`TrialCreate` Provision Request types Keep in mind that if you want to simulate events that assume a prior action has happened, as is the case for `Deprovision` or `Update` type provision requests, which assume a `NetNew` has happened sometime prior, you will have to persist data in your system from the prior action, and then provide that data in the body of your request for the subsequent simulation request. Any field not included in the request body will be set to their defaults shown above. Data Expiration [](https://devx.pax8.com/docs/provisioning-integration-testing#data-expiration) --------------------------------------------------------------------------------------------------- The following simulation resources will expire after 1 week: * `Provision Requests` * `Provision Detail` * `Provision Attempts` * `Provision Results` * `Webhooks` - Your latest webhook will never expire, but all others expire after 1 week The following simulation resources do not expire: * `Provisioners` Updated 3 months ago * * * Visit the Request and Response Example and Scenarios Pages * [Request and Response Examples](https://devx.pax8.com/docs/examples) * [Provisioning Simulation Scenarios](https://devx.pax8.com/docs/provision-simulation-example) Ask AI --- # Aggregate Usage Lines Overview [](https://devx.pax8.com/docs/aggregate-usage-line#overview) ========================================================================= Aggregate Usage Lines are identical to regular Usage Lines except for one key difference. Aggregate Usage Lines have an additional required field called `partnerAggregateQuantity` that is absent from regular Usage Lines. Use Aggregate Usage Lines when you want to give Partners a price based on the aggregate usage of all of their Companies. Typically, this would be used alongside a volume based rate plan, where there are price breaks at certain volume amounts. Endpoints [](https://devx.pax8.com/docs/aggregate-usage-line#endpoints) --------------------------------------------------------------------------- ### Save Usage Lines with an Aggregate Partner Quantity [](https://devx.pax8.com/docs/aggregate-usage-line#save-usage-lines-with-an-aggregate-partner-quantity) * Save Aggregate Usage Lines For a Pax8 Subscription * [POST /usage/aggregate-lines?subscriptionId={subscriptionId}&billingPeriod={billingPeriod}](https://devx.pax8.com/reference/saveusagelineswithaggregate) * [POST /usage/aggregate-lines?externalSubscriptionId={externalSubscriptionId}&billingPeriod={billingPeriod}](https://devx.pax8.com/reference/saveusagelineswithaggregate) > Note that `billingPeriod` is a year-month, taking the format `yyyy-MM`. > > Our API also offers an optional feature that enables Vendors to store a unique identifier on a subscription during provisioning. The externalProvisionerSubscriptionId serves as a reference point for future interactions with the object, making it easy to locate and modify without complex mappings. The Aggregate Usage Line Object [](https://devx.pax8.com/docs/aggregate-usage-line#the-aggregate-usage-line-object) ======================================================================================================================= JSON `{ "summaryKey": "key", "summaryDisplayName": "name", "quantity": 1, "partnerAggregateQuantity": 100, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "unit" }` Additional Information [](https://devx.pax8.com/docs/aggregate-usage-line#additional-information) ----------------------------------------------------------------------------------------------------- Pax8 Partners may have many usage lines for a subscription, and those lines could be for many different companies, so we offer a grouping mechanism called `summaryKey` to aggregate usage lines into summaries. The most common grouping pattern - and the pattern recommended by Pax8 - is to group usage lines by company. * Usage Lines are grouped by a `summaryKey` for a Subscription. Every usage line that shares an identical `summaryKey` will grouped together for display purposes. * The key must be a unique identifier, most often a company id. * The `summaryDisplayName` is used in the Pax8 UI, this is the label that partners will see on their invoices and throughout the month when monitoring their usage. It gives a friendly name to the group defined by a `summaryKey`. * If you are grouping usage by Company ID, then Company name is a good candidate for `summaryDisplayName` > NOTE: both `summaryKey` and `summaryDisplayName` have a 255 character limit. Example [](https://devx.pax8.com/docs/aggregate-usage-line#example) ----------------------------------------------------------------------- Let's assume usage pricing has been set up in the Pax8 system such that if users consume 0-99 units of usage, the cost is $1.00 per unit. Then, for users who use 100-999 units of usage, the cost is $0.90 per unit. Next, let's assume some example Partner manages 3 Companies, and each of the Companies consumes 40 units of usage per month. In this case, the `partnerAggregateQuantity` would be 120, or the sum of the usage from all of their companies. If you send this 120 as the value for `partnerAggregateQuantity` when posting each individual Company level usage line, the Pax8 system will set the partner price on the usage line to $0.90 per unit, and the end retail price will be $1.00 per unit. When reporting usage to Pax8 for the company, Amazing Company, you would send us the following request: Request `curl --request POST \ --url 'https://api.pax8.com/v2/usage/aggregate-lines?subscriptionId=ef29b3e0-2474-4c27-9405-9a8520ffc72c&billingPeriod=2025-08' \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' [ { "summaryKey": "12345", "summaryDisplayName": "Amazing Company", "quantity": 40, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "Unit", "partnerAggregateQuantity": 120 } ] ' '` And you would receive the following response: Response `[ { "summaryKey": "12345", "summaryDisplayName": "Amazing Company", "quantity": 40, "partnerAggregateQuantity": 120, "productId": "c53df278-d591-427d-8039-1dc5f4dec15e", "unitOfMeasurement": "Unit" } ]` Updated 3 months ago * * * Ask AI --- # Usage Line Grouping Examples Below are some examples of methodologies for grouping usage lines together into usage summaries Group by Company [](https://devx.pax8.com/docs/usage-line-grouping-examples#group-by-company) ------------------------------------------------------------------------------------------------- This is the grouping pattern recommended by Pax8 for the vast majority of our Vendors. Below is an example grouping scenario for a Pax8 Partner that has 2 Companies under their account. * Company A uses: * 10 units of product 123 * 15 units of Product 456 * Company B uses: * 15 units of product 123 * 15 units of product 789 When submitting usage lines: * `summaryKey` is set to the unique company id, which is often times a UUID, * `summaryDisplayName` is set to the company name * `productId` will be a UUID. It is set to a simple number for explanation purposes Request `curl --request POST \ --url 'https://api.pax8.com/v2/usage/lines?subscriptionId=39039087-c1ab-480a-9395-4f78bb5a0340&billingPeriod=2025-08' \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' [ { "summaryKey": "company-A-id", "summaryDisplayName": "Company A", "quantity": 10, "productId": "123", "unitOfMeasurement": "unit" }, { "summaryKey": "company-A-id", "summaryDisplayName": "Company A", "quantity": 15, "productId": "456", "unitOfMeasurement": "unit" }, { "summaryKey": "company-B-id", "summaryDisplayName": "Company B", "quantity": 15, "productId": "123", "unitOfMeasurement": "unit" }, { "summaryDisplayName": "Company B", "summaryKey": "company-B-id", "quantity": 15, "productId": "789", "unitOfMeasurement": "unit" } ] '` In the Pax8 system, the user will see 2 groupings of usage lines. The first one will show 2 usage lines for Company A and the second group will show the 2 usage lines for Company B. Group by Company and Product Type [](https://devx.pax8.com/docs/usage-line-grouping-examples#group-by-company-and-product-type) ----------------------------------------------------------------------------------------------------------------------------------- This grouping pattern is an option if your offering includes a very large array of products that make sense to group by product type. As a reminder, Pax8 recommends simply grouping by Company for the majority of cases. Below is an example grouping scenario for a Pax8 Partner that has 1 Company under their account with multiple product types. * Company A uses 10 units of product 1, which is Type VM * Company A uses 20 units of product 2, which is Type VM * Company A uses 30 units of product 3, which is Type Storage When submitting usage lines: * `summaryKey` is set to the concatenation of the unique company id, which is often times a UUID, and the product type * `summaryDisplayName` is set to the company name and product type, separated by a comma * `productId` will be a UUID. It is set to a simple number for explanation purposes Request `curl --request POST \ --url 'https://api.pax8.com/v2/usage/lines?subscriptionId=39039087-c1ab-480a-9395-4f78bb5a0340&billingPeriod=2025-08' \ --header 'accept: */*' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' [ { "summaryKey": "{company-A-id}-group-vm", "summaryDisplayName": "Company A, Group VM", "quantity": 10, "productId": "1", "unitOfMeasurement": "unit" }, { "summaryKey": "{company-A-id}-group-vm", "summaryDisplayName": "Company A, Group VM", "quantity": 20, "productId": "2", "unitOfMeasurement": "unit" }, { "summaryKey": "{company-A-id}-group-storage", "summaryDisplayName": "Company A, Group Storage", "quantity": 30, "productId": "3", "unitOfMeasurement": "unit" } ] '` In the Pax8 system, the user will see 2 groupings of usage lines. The first one will show 2 usage lines related to Type VM and the second group will show the 1 usage line related to Type Storage. Updated 3 months ago * * * Ask AI --- # Usage Overview Below is a quick introduction to the basics of using the usage endpoints. Base Url [](https://devx.pax8.com/docs/usage-overview#base-url) ------------------------------------------------------------------- The base url for all usage requests is `https://api.pax8.com/v2` Terminology [](https://devx.pax8.com/docs/usage-overview#terminology) ------------------------------------------------------------------------- The Pax8 Usage API provides a way for Vendors to upload usage data for Pax8 Subscriptions. Here are a few key terms * `Partner` - A Pax8 Partner, also known as a Managed Service Provider (MSP). Manages cloud software for a `Company` and are Pax8's primary users. * `Company` - A Pax8 Company, also known as an End User. A `Company` buys cloud software from a `Partner` * `Subscription` - A record in Pax8 for a specific `Partner`/`Company`/`Product` combination in the Pax8 system. * `Usage Line` - A single line of usage data represented by a specific `Subscription`/`Product`/`Quantity` combination in the Pax8 system. * `Billing Period` - A monthly timeframe, measured from from the first day to the last day of a month, for which Pax8 will create billable charges for `Partners` How Posting Usage Works [](https://devx.pax8.com/docs/usage-overview#how-posting-usage-works) ------------------------------------------------------------------------------------------------- 1. A `Partner` orders from Pax8, and a `Subscription` is created using the [Provisioning Endpoints](https://devx.pax8.com/docs/how-to-use-provisioning-endpoints) . 2. Vendors will post usage to Pax8 throughout an ongoing `Billing Period` in order to keep usage totals up to date within Pax8. 3. Two days after the end of a `Billing Period`, Pax8 will create billable charges for the `Partner` based on the _latest_ totals posted by Vendor for that billing period. 4. Vendors will be unable to submit usage for a previous `Billing Period` for any `Subscription` after midnight UTC on the 1st the following month. Key Concepts [](https://devx.pax8.com/docs/usage-overview#key-concepts) --------------------------------------------------------------------------- ### Daily Usage Tracking [](https://devx.pax8.com/docs/usage-overview#daily-usage-tracking) Pax8 tracks usage totals on a daily basis. Best practices: * Vendors should post the most current usage totals once per day. * Pax8 does not track usage cumulatively. The latest usage posted will represent the total for a Billing Period. * When multiple posts occur for the same `Subscription` and `summaryKey` on the same day. The default behavior is that older usage from that day is deleted. However overwriting same-day usage is configurable. See [documentation](https://devx.pax8.com/docs/overwrite-same-day-usage) for detailed examples ### Billing Period Deadlines [](https://devx.pax8.com/docs/usage-overview#billing-period-deadlines) When a Billing Period ends, Vendors have a limited window to post usage: * **Grace Period**: 1 day after the Billing Period ends * **Deadline**: Based on UTC time standard * After the grace period, Pax8 creates billable charges and no further usage can be posted for that period **Example:** * Billing Period ends on October 31 * Usage can still be posted on November 1 * Starting November 2, attempts to post usage for October will be rejected ### Performance Metrics [](https://devx.pax8.com/docs/usage-overview#performance-metrics) * **Average Latency**: 400-500 milliseconds at current volume levels * **Request Limit**: Maximum 1000 POST requests per minute Expectations when Pax8 Creates Billable Charges [](https://devx.pax8.com/docs/usage-overview#expectations-when-pax8-creates-billable-charges) ------------------------------------------------------------------------------------------------------------------------------------------------- * **Billable charges** are line items that appear on the actual invoice sent to `Partners` * Once created, billable charges **cannot be changed** * On the 2nd of each month, Pax8 will: * Look for the latest usage totals posted for subscriptions from the previous `Billing Period` * Convert these totals into billable charges * Finalize partner bills and prepare invoices * After the 1st, usage data for the previous month cannot be corrected via the API > **Note:** There are some caveats to this process. For detailed examples, please refer to the billing examples page. API Limitations [](https://devx.pax8.com/docs/usage-overview#api-limitations) --------------------------------------------------------------------------------- ### Synchronous Processing [](https://devx.pax8.com/docs/usage-overview#synchronous-processing) * Usage line posting is currently **synchronous**, meaning: * The client waits for the request to complete with an HTTP 200 status code. * The client remains connected until success or failure is confirmed. * Asynchronous processing (where Pax8 would accept payloads with a 201 status and provide polling capabilities) is **not supported** at this time ### Payload Size Constraints [](https://devx.pax8.com/docs/usage-overview#payload-size-constraints) * There is an upper limit to payload size before timeouts occur. * **Recommendation**: Send no more than fifty (50) usage lines in a single request payload. * This ensures the Pax8 system can process each request before client timeout. ### Managing Large Summaries [](https://devx.pax8.com/docs/usage-overview#managing-large-summaries) When creating summaries with more than 50 usage lines sharing the same `summaryKey`: * **Problem**: Default behavior causes the second batch of 50 lines to overwrite the first batch when sent on the same day. * **Solution**: Include the `overwriteSameDayUsage=false` parameter when posting usage. * This configures the API to append to existing lines rather than overwrite them. For detailed examples of this configuration, see the [overwrite same-day usage documentation](https://devx.pax8.com/docs/overwrite-same-day-usage) . OpenAPI Spec [](https://devx.pax8.com/docs/usage-overview#openapi-spec) --------------------------------------------------------------------------- You can find the complete OpenAPI Spec for the usage API [here](https://devx.pax8.com/openapi/661469e054fdd00030608528) Updated about 2 months ago * * * * [Usage Lines](https://devx.pax8.com/docs/usage-lines) * [Aggregate Usage Lines](https://devx.pax8.com/docs/aggregate-usage-line) Ask AI --- # Provision Request Overview [](https://devx.pax8.com/docs/provision-request#overview) ====================================================================== A `ProvisionRequest` contains basic information about a purchase which cannot change. This includes things such as partnerId, partnerAddress, companyAddress, productId, etc For collecting non-static information such as an admin email address or phone number, you should refer the [Provision Details](https://devx.pax8.com/docs/provision-detail) section of our guide which contains information a user entered at checkout. Endpoints [](https://devx.pax8.com/docs/provision-request#endpoints) ------------------------------------------------------------------------ ### List All Provision Requests [](https://devx.pax8.com/docs/provision-request#list-all-provision-requests) * Lists All Provision Requests * [GET /provision-requests](https://devx.pax8.com/reference/getallprovisionrequests) ### Get A Provision Request [](https://devx.pax8.com/docs/provision-request#get-a-provision-request) * Gets a Single Provision Request by ID * [GET v2/provision-requests/{id}](https://devx.pax8.com/reference/getoneprovisionrequest) ### List All Unfulfilled Provision Requests [](https://devx.pax8.com/docs/provision-request#list-all-unfulfilled-provision-requests) * Lists All Unfulfilled Provision Requests * [GET /provision-requests/unfulfilled](https://devx.pax8.com/reference/getallunfulfilledprovisionrequests) The Provision Request Object [](https://devx.pax8.com/docs/provision-request#the-provision-request-object) ============================================================================================================== JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerAddress": { "street": "123 Partner Avenue", "street2": "Unit A", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "Colorado" }, "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Avenue", "street2": "Unit A", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "oldProductId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "productName": "Product ABC", "quantity": 0, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "NetNew", "createdDate": "2025-07-09T19:52:34.641303Z", "trialEndDate": "2025-08-01T19:52:34.641303Z", "trialAutoConverts": true, "commitmentTermEndDate": "2026-07-31T19:50:02Z", "commitmentTermMonths": 12, "commitment": { "term": { "months": 12, "endDate": "2026-07-31T19:50:02Z" }, "volume": { "minAmount": 250.0000, "maxAmount": 500.0000, "unitOfMeasure": "USD", "months": 1 } }, "billingTerm": "Monthly" }` Null fields will be omitted. Additional Information [](https://devx.pax8.com/docs/provision-request#additional-information) -------------------------------------------------------------------------------------------------- ### Commitments [](https://devx.pax8.com/docs/provision-request#commitments) #### Terms [](https://devx.pax8.com/docs/provision-request#terms) If you require partners to agree to a set commitment term when buying a product, you can have that configured in Pax8. For example, if you require partners to buy a full year of service at a time, Pax8 can configure a 12 month commitment term for your products. In this example, any `ProvisionRequest` for your product would include a `commitment.term.months` field which would be 12, and a `commitment.term.endDate` field, which would contain a date 12 months in the future from the purchase date. #### Volume [](https://devx.pax8.com/docs/provision-request#volume) In addition to time only based commitment terms, Pax8 supports **volume commitments** that specify minimum and (optionally) maximum volume requirements for subscriptions for a certain unit and length of time. Volume commitments work alongside time-based commitments to provide more flexible commitment options. **Note:** Volume commitments are always paired with time-based commitments. Volume-only commitments are not currently available. #### Backward Compatibility [](https://devx.pax8.com/docs/provision-request#backward-compatibility) For backward compatibility, provision requests continue to include the legacy commitment fields: * `commitmentTermMonths` - Duration in months _(deprecated, use `commitment.term.months`)_ * `commitmentTermEndDate` - End date _(deprecated, use `commitment.term.endDate`)_ ### Billing Terms [](https://devx.pax8.com/docs/provision-request#billing-terms) All provision requests will contain a `billingTerm` whose value represents the frequency at which the product is billed. The possible values for `billingTerm` are as follows: * One-Time * Monthly * Annual * 2 Year * 3 Year * Trial * Activation ### Provision Request Types [](https://devx.pax8.com/docs/provision-request#provision-request-types) * The `type` field may contain * `NetNew` - Request to start new subscription for a given product * `Update` - Request to update existing subscription * `Deprovision` - Request to stop services for an existing trial or subscription * `TrialCreate` - Request to start a new trial subscription for the given product. * `TrialConvert` - Request to convert an existing trial subscription into a paid subscription * `ChangeProduct` - Request to upgrade or downgrade current subscription from one product to another * `PartnerEnrollment` - Optional request that allows the creation of a partner-level account * `Renewal` - Request to renew subscription at the end of it's current commitment term #### NetNew [](https://devx.pax8.com/docs/provision-request#netnew) `NetNew` requests represent a request for a new subscription. One company is allowed per provision request. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "NetNew", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### Update [](https://devx.pax8.com/docs/provision-request#update) `Update` requests represent a change to an existing subscription, usually a quantity change. They have the same form as `NetNew` requests. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "Update", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### Deprovision [](https://devx.pax8.com/docs/provision-request#deprovision) `Deprovision` requests represent a cancellation request for a subscription or trial. Unlike `NetNew` and `Update` requests, `Deprovision` requests do not have a `quantity` field. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "Deprovision", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### TrialCreate [](https://devx.pax8.com/docs/provision-request#trialcreate) `TrialCreate` requests represent a request to start a new trial subscription. These differ from a `NetNew` request in that `TrialCreate` requests contain two additional fields: a `trialEndDate` date field and a `trialAutoConverts` boolean field that are not included on any other request types. When `trialAutoConverts` is true, you can expect to receive a `TrialConvert` provision request from Pax8 on the `trialEndDate`. When `trialAutoConverts` is false, Pax8 will not send any request on the `trialEndDate` and the trial should simply expire. Please note that our system automatically converts trials at 12:30 a.m. MST on the specified trial end date. To ensure a smooth transition, it is advisable to implement a buffer period of several hours before canceling the trial on that day. Trials can be cancelled by partners in the Pax8 platform. When this happens, Pax8 will send a `Deprovision` request for that trial. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "trialEndDate": "2022-12-03T10:15:30Z", "trialAutoConverts": "true", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "TrialCreate", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### TrialConvert [](https://devx.pax8.com/docs/provision-request#trialconvert) A `TrialConvert` request represents a request to convert a trial into a paid subscription. They take the same form as a `NetNew` request JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "TrialConvert", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### ChangeProduct [](https://devx.pax8.com/docs/provision-request#changeproduct) A `ChangeProduct` request represents a request to upgrade or downgrade an existing subscription onto a new product. A `ChangeProduct` request has one additional field compared to a `NetNew` request called `oldProductId` in order to indicate the old product. The new product will be indicated by `productId`. At this time, Pax8 does not support upgrading or downgrading partial quantities on an existing subscription. It's all or nothing. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "oldProductId": "667a881b-31ef-4f95-8ebe-69bc95afa15e", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "ChangeProduct", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### Renewal [](https://devx.pax8.com/docs/provision-request#renewal) A `Renewal` request represents a request to confirm the continuation of an existing subscription for another commitment term. Term duration is determined – and, when applicable, selected - within the Pax8 Marketplace. The duration of the term will be passed in the request based on the product's renewal terms. Unlike an `Update` request, which is typically used for quantity changes, a `Renewal` request specifically handles the transition from one commitment term to the next while maintaining the same product and configuration. Renewal requests will be sent upon every renewal event and **cannot** be disabled. This will be configured by Pax8 on to fit your needs and will be communicated with you beforehand. Not all vendors require renewal support. The new renewal commitment date posted in the `Renewal` request will be the source of truth for billing and future renewal events. Even if no additional action is required on your end, you are expected to respond to every request. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99", "companyName": "Example Company Name", "companyDomain": "company.com", "companyAddress": { "street": "123 Company Ave.", "street2": "Unit c", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1", "productName": "Product ABC", "quantity": 1, "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064", "type": "Renewal", "createdDate": "2024-04-08T19:54:03Z", "commitmentTermMonths": 12, "commitmentTermEndDate": "2025-04-08T19:54:03Z", "commitment": { "term": { "months": 12, "endDate": "2025-04-08T19:54:03Z" }, "volume": { "minAmount": 1, "maxAmount": 10, "unitOfMeasure": "Users", "months": 1 } }, "billingTerm": "Monthly" }` #### PartnerEnrollment [](https://devx.pax8.com/docs/provision-request#partnerenrollment) A `PartnerEnrollment` request represents a request to create a new partner account. Pax8 recommends to ignore the `PartnerEnrollment` type. Creating a Partner account upon receiving a `NetNew` or `TrialCreate` provision is typically sufficient. If you require that a partner-level account is created _before_ the partner can even create an order. This type can be utilized to do so. A `PartnerEnrollment` request omits much of the data present in other provision requests, since only partner information will be relevant. JSON `{ "id": "eb77429f-b313-4916-9bed-ccc1c373dff7", "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02", "partnerName": "Example Partner Name", "partnerDomain": "partner.com", "partnerAddress": { "street": "123 Partner Ave.", "street2": "Unit b", "city": "Denver", "postcode": "80210", "country": "US", "stateOrProvince": "CO" }, "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02", "type": "PartnerEnrollment", "createdDate": "2022-10-03T10:15:30Z" }` Updated 3 months ago * * * Ask AI --- # Subscribing to Events Enhance your integrations and streamline your workflows with Pax8 Event Subscriptions. This new functionality allows you to subscribe to key events within the Pax8 platform, enabling you to build more efficient and responsive integrations. Instead of polling for updates, receive real-time notifications and retrieve detailed information only when necessary. Event subscription management is handled within the Pax8 application or with our APIs. Our webhooks are meant to be used as a notification system and not a full state transfer. Although we do try to provide useful information for each topic. We recommend users to set up their systems to call the relevant APIs to receive the full state of information. Key features and benefits: [](https://devx.pax8.com/docs/subscribe-to-events#key-features-and-benefits) ----------------------------------------------------------------------------------------------------------- * Real-time notifications: Receive immediate alerts when relevant events occur. * Efficient integrations: Eliminate unnecessary polling and reduce API calls. * Data on demand: Retrieve full event details only when needed, minimizing data transfer. * Improved responsiveness: React quickly to changes and updates within the Pax8 ecosystem. To get started with Pax8 Event Subscriptions: 1. Navigate to the Events tab in the Pax8 application: [https://app.pax8.com/integrations/events](https://app.pax8.com/integrations/events) 2. Create webhooks to specify the events you want to subscribe to. 3. View and manage your active webhooks on the Connections tab: [https://app.pax8.com/integrations/events?tab=webhooks](https://app.pax8.com/integrations/events?tab=webhooks) How it Works [](https://devx.pax8.com/docs/subscribe-to-events#how-it-works) -------------------------------------------------------------------------------- 1. Select events: Choose the specific events you want to subscribe to within the Pax8 application. 2. Configure webhooks: Set up webhooks to receive notifications when those events occur. 3. Receive notifications: Your designated endpoint will receive a notification when an event is triggered. 4. Retrieve details: Use the event notification to call the appropriate Pax8 API endpoint and retrieve the full event details. Available Event Categories [](https://devx.pax8.com/docs/subscribe-to-events#available-event-categories) ------------------------------------------------------------------------------------------------------------ Pax8 currently offers event subscriptions for the following categories: * **Client Events:** Triggered when client-related events occur. * Examples: Client Created, Client Updated, Client Deleted * **Invoice Events:** Triggered when invoice-related events occur. * Examples: Invoice Created, Invoice Voided * **Product Events:** Triggered when product-related events occur. * Examples: Product Created, Product Updated, Product Deleted * **Quote Events:** Triggered when quote-related events occur. * Examples: Quote Pending, Quote Ownership Taken, Quote Created, Quote Updated, Quote Customer Responded, Quote Expired, Quote Deleted, Line Items Added, Line Item Deleted, Line Items Updated * **Subscription Events:** Triggered when billing subscription related events occur. * Examples: Subscription Created, Subscription Updated, Subscription Cancelled, Subscription Vendor Mapping Updated, Subscription Commitment Term Updated, Subscription Purchase Order Updated * **User Events:** Triggered when user-related events occur. * Examples: User Created, User Deleted, User Marked Active, User Marked Inactive, User Info Updated, User Account Reassigned, User Country Changed, User Account Name Changed, User Partner Type Changed, Company User Promoted to Partner User (See the full documentation within the Pax8 application for a complete list of available events and detailed information on event structures.) By leveraging Pax8 Event Subscriptions, you can build more efficient, responsive, and data-driven integrations with the Pax8 platform. Updated 2 months ago * * * Ask AI --- # Providing 3rd Parties Access This guide is intended for Pax8 Partners. If you are an application developer and would like to develop an OAuth2 integration with Pax8, please review this [page](https://devx.pax8.com/docs/developingdelegationapplications) instead. If you would like to grant an application access to view your data or make changes on your behalf, please go to Integrations Hub and review the vendor's information. Within Integrations Hub, you'll be redirected to the vendor's integration page where you can set up that integration. **DO NOT PROVIDE YOUR API CREDENTIALS TO ANY 3RD PARTY APPLICATIONS**. When leveraging OAuth2 signin screens, always ensure you only enter your Pax8 credentials at urls staring with `https://login.pax8.com`. If in doubt, ensure that vendor is noted as an app in Pax8's Integrations Hub. Adding New Integrator Applications [](https://devx.pax8.com/docs/usingdelegationapplications#adding-new-integrator-applications) ------------------------------------------------------------------------------------------------------------------------------------ * Email `[[email protected]](https://devx.pax8.com/cdn-cgi/l/email-protection) ` if you have a vendor you'd like to integrate with thats not in Pax8's Integrations Hub. We can work with them to integrate with our APIs and get listed in Integrations Hub. Updated 3 months ago * * * Ask AI ---