Merge pull request #178368 from dannyevers/57262-reimagine

Split the SaaS fulfillment APIs doc

Author: GitHubber17

articles/marketplace/.openpublishing.redirection.marketplace.json

@@ -20,6 +20,11 @@
             "redirect_url": "/azure/marketplace/isv-app-license",
             "redirect_document_id": false
         },
+        {
+            "source_path_from_root": "/articles/azure/marketplace/partner-center-portal/pc-saas-fulfillment-api-v2.md",
+            "redirect_url": "/azure/marketplace/partner-center-portal/pc-saas-fulfillment-apis",
+            "redirect_document_id": false
+        },
         {
             "source_path_from_root": "/articles/cloud-partner-portal/cloud-partner-portal-manage-publisher-profile.md",
             "redirect_url": "/azure/marketplace/partner-center-portal/create-account",

articles/marketplace/TOC.yml

@@ -571,16 +571,24 @@
       href: marketplace-metering-service-apis-faq.yml
   - name: SaaS Fulfillment APIs
     items:
-    - name: SaaS Fulfillment API overview
+    - name: SaaS Fulfillment APIs overview
       href: partner-center-portal/pc-saas-fulfillment-apis.md
     - name: Register a SaaS application
       href: partner-center-portal/pc-saas-registration.md
     - name: SaaS Fulfillment APIs v2
-      href: partner-center-portal/pc-saas-fulfillment-api-v2.md
-    - name: SaaS Fulfillment APIs v1 (deprecated)
-      href: partner-center-portal/pc-saas-fulfillment-api-v1.md
+      items:  
+      - name: SaaS subscription life cycle
+        href: partner-center-portal/pc-saas-fulfillment-life-cycle.md
+      - name: Subscription APIs
+        href: partner-center-portal/pc-saas-fulfillment-subscription-api.md
+      - name: Operations APIs
+        href: partner-center-portal/pc-saas-fulfillment-operations-api.md
+    - name: Implement a webhook
+      href: partner-center-portal/pc-saas-fulfillment-webhook.md
     - name: SaaS fulfillment APIs - FAQ
       href: partner-center-portal/saas-fulfillment-apis-faq.yml
+    - name: SaaS Fulfillment APIs v1 (deprecated)
+      href: partner-center-portal/pc-saas-fulfillment-api-v1.md    
 - name: Resources
   items:
   - name: Commercial marketplace FAQ

articles/marketplace/azure-ad-saas.md

@@ -48,7 +48,7 @@ This table provides details for the purchase management process steps.
 | ------------ | ------------- | ------------- |
 | 1. The buyer signs in to the commercial marketplace with their Azure ID identity and selects a SaaS offer. | No publisher action required. | Not applicable |
 | 2. After purchasing, the buyer selects **Configure account** in Azure Marketplace or **Configure now** in AppSource, which directs the buyer to the publisher’s landing page for this offer. The buyer must be able to sign in to the publisher’s SaaS application with Azure AD SSO and must only be asked for minimal consent that does not require Azure AD administrator approval. | Design a [landing page](azure-ad-transactable-saas-landing-page.md) for the offer so that it receives a user with their Azure AD or Microsoft account (MSA) identity and facilitates any additional provisioning or setup that’s required. | Required |
-| 3. The publisher requests purchase details from the SaaS fulfillment API. | Using an [access token](./partner-center-portal/pc-saas-registration.md) generated from the landing page’s Application ID, [call the resolve endpoint](./partner-center-portal/pc-saas-fulfillment-api-v2.md#resolve-a-purchased-subscription) to retrieve specifics about the purchase. | Required |
+| 3. The publisher requests purchase details from the SaaS fulfillment API. | Using an [access token](./partner-center-portal/pc-saas-registration.md) generated from the landing page’s Application ID, [call the resolve endpoint](./partner-center-portal/pc-saas-fulfillment-subscription-api.md#resolve-a-purchased-subscription) to retrieve specifics about the purchase. | Required |
 | 4. Through Azure AD and the Microsoft Graph API, the publisher gathers the company and user details required to provision the buyer in the publisher’s SaaS application.  | Decompose the Azure AD user token to find name and email, or [call the Microsoft Graph API](/graph/use-the-api) and use delegated permissions to [retrieve information](/graph/api/user-get) about the user who is logged in. | Required |
 ||||
 
@@ -62,7 +62,7 @@ This table describes the details about the subscription management process steps
 
 | Process step | Publisher action | Recommended or required for publishers |
 | ------------ | ------------- | ------------- |
-| 5. The publisher manages the subscription to the SaaS application through the SaaS fulfillment API. | Handle subscription changes and other management tasks through the [SaaS fulfillment APIs](./partner-center-portal/pc-saas-fulfillment-api-v2.md).<br><br>This step requires an access token as described in process step 3. | Required |
+| 5. The publisher manages the subscription to the SaaS application through the SaaS fulfillment API. | Handle subscription changes and other management tasks through the [SaaS fulfillment APIs](./partner-center-portal/pc-saas-fulfillment-apis.md).<br><br>This step requires an access token as described in process step 3. | Required |
 | 6. When using metered pricing, the publisher emits usage events to the metering service API. | If your SaaS app features usage-based billing, make usage notifications through the [Marketplace metering service APIs](marketplace-metering-service-apis.md).<br><br>This step requires an access token as described in Step 3. | Required for metering |
 ||||
 

articles/marketplace/azure-ad-transactable-saas-landing-page.md

@@ -76,7 +76,7 @@ This enables the solution to work in scenarios that observe the [separation of c
 
 ## Resolve the marketplace purchase identification token
 
-When the buyer is sent to your landing page, a token is added to the URL parameter. This token is different from both the Azure AD-issued token and the access token used for service-to-service authentication, and is used as an input for the [SaaS fulfillment APIs](./partner-center-portal/pc-saas-fulfillment-api-v2.md#resolve-a-purchased-subscription) resolve call to get the details of the subscription. As with all calls to the SaaS fulfillment APIs, your service-to-service request will be authenticated with an access token that is based on the app's Azure AD Application ID user for service-to-service authentication.
+When the buyer is sent to your landing page, a token is added to the URL parameter. This token is different from both the Azure AD-issued token and the access token used for service-to-service authentication, and is used as an input for the [SaaS fulfillment APIs](./partner-center-portal/pc-saas-fulfillment-subscription-api.md#resolve-a-purchased-subscription) resolve call to get the details of the subscription. As with all calls to the SaaS fulfillment APIs, your service-to-service request will be authenticated with an access token that is based on the app's Azure AD Application ID user for service-to-service authentication.
 
 > [!NOTE]
 > In most cases, it's preferable to make this call from a second, single-tenant application. See [Use two Azure AD apps to improve security in production](#use-two-azure-ad-apps-to-improve-security-in-production) earlier in this article.
@@ -87,7 +87,7 @@ To authenticate your application with the SaaS fulfillment APIs, you need an acc
 
 ### Call the resolve endpoint
 
-The SaaS fulfillment APIs implement the [resolve](./partner-center-portal/pc-saas-fulfillment-api-v2.md#resolve-a-purchased-subscription) endpoint that can be called to confirm the validity of the marketplace token and to return information about the subscription.
+The SaaS fulfillment APIs implement the [resolve](./partner-center-portal/pc-saas-fulfillment-subscription-api.md#resolve-a-purchased-subscription) endpoint that can be called to confirm the validity of the marketplace token and to return information about the subscription.
 
 ## Read information from claims encoded in the ID token
 

articles/marketplace/create-new-saas-offer-technical.md

@@ -26,7 +26,7 @@ On the **Technical configuration** tab, you'll define the technical details that
   > [!IMPORTANT]
   > Your landing page should be up and running 24/7. This is the only way you will be notified about new purchases of your SaaS offers made in the commercial marketplace, or configuration requests of an active subscription of an offer. Don't include the pound sign character (#) in the landing page URL. Otherwise, customers will not be able to access your landing page.
 
-- **Connection webhook** (required) – For all asynchronous events that Microsoft needs to send to you (for example, SaaS subscription has been canceled), we require you to [provide a connection webhook URL](./partner-center-portal/pc-saas-fulfillment-api-v2.md#implementing-a-webhook-on-the-saas-service). We will call this URL to notify you of the event.
+- **Connection webhook** (required) – For all asynchronous events that Microsoft needs to send to you (for example, SaaS subscription has been canceled), we require you to [provide a connection webhook URL](./partner-center-portal/pc-saas-fulfillment-webhook.md). We will call this URL to notify you of the event.
 
   > [!IMPORTANT]
   > Your webhook should be up and running 24/7 as this is the only way you will be notified about updates about your customers' SaaS subscriptions that are purchased via the commercial marketplace.

articles/marketplace/index.yml

@@ -117,7 +117,7 @@ landingContent:
       - text: API prerequisites
         url: cloud-partner-portal-api-prerequisites.md
       - text: SaaS fulfillment APIs
-        url: partner-center-portal/pc-saas-fulfillment-api-v2.md
+        url: partner-center-portal/pc-saas-fulfillment-apis.md
       - text: Marketplace metering service APIs
         url: marketplace-metering-service-apis-faq.yml
       - text: Reporting API (PDF)

articles/marketplace/marketplace-apis-guide.md

@@ -22,9 +22,9 @@ The activities below are not sequential. The activity you use is dependent on yo
 | <center>**1. Product Marketing**<br><img src="media/api-guide/icon-product-marketing.png" alt="The icon for product marketing"> | Create product messaging, positioning, promotion, pricing | Create product messaging, positioning, promotion, pricing<br>[Partner Ingestion API](https://apidocs.microsoft.com/services/partneringestion/)<br>[Azure Apps Onboarding API](azure-app-apis.md)</ul> | Create product messaging, positioning, promotion, pricing<br>Partner Center (PC) → Offer Creation |
 | <center>**2. Demand Generation**<br><img src="media/api-guide/icon-demand-generation.png" alt="The icon for demand generation"> | Product Promotion<br>Lead nurturing<br>Eval, trial & PoC | Product Promotion<br>Lead nurturing<br>Eval, trial & PoC<br>[Lead CRM Connector for D365, SFDC and Marketo](partner-center-portal/commercial-marketplace-get-customer-leads.md)<br>[Co-Sell Connector for SalesForce CRM](/partner-center/connector-salesforce)<br>[Co-Sell Connector for Dynamics 365 CRM](/partner-center/connector-dynamics) | Product Promotion<br>Lead nurturing<br>Eval, trial & PoC<br>Azure Marketplace and AppSource<br>PC Marketplace Insights<br>PC Co-Sell Opportunities |
 | <center>**3. Negotiation and Quote Creation**<br><img src="media/api-guide/icon-negotiation-quote-creation.png" alt="The icon for negotiation and quote creation"> | T&Cs<br>Pricing<br>Discount approvals<br>Final quote | T&Cs<br>Pricing<br>Discount approvals<br>Final quote<br>[CPP API for VM's](cloud-partner-portal-api-overview.md)<br>[Microsoft Graph for AAD API](../active-directory/reports-monitoring/concept-reporting-api.md)<br>[Partner Center '7' API Family](https://apidocs.microsoft.com/services/partnercenter) | T&Cs<br>Pricing<br>Discount approvals<br>Final quote<br>PC → Plans (public or private) |
-| <center>**4. Sale**<br><img src="media/api-guide/icon-sale.png" alt="The icon for sale"> | Contract signing<br>Revenue Recognition<br>Invoicing<br>Billing | Contract signing<br>Revenue Recognition<br>Invoicing<br>Billing<br>[SaaS fulfillment API v.2](partner-center-portal/pc-saas-fulfillment-api-v2.md)<br>[Reporting APIs](https://partneranalytics-api.azureedge.net/partneranalytics-api/Programmatic%20Access%20to%20Commercial%20Marketplace%20Analytics%20Data_v1.pdf) | Contract signing<br>Revenue Recognition<br>Invoicing<br>Billing<br>Azure portal / Admin Center<br>PC Marketplace Rewards<br>PC Payouts Reports<br>PC Marketplace Analytics<br>PC Co-Sell Closing |
-| <center>**5. Maintenance**<br><img src="media/api-guide/icon-maintenance.png" alt="The icon for maintenance"> | Recurring billing<br>Overages<br>Product Support | Recurring billing<br>Overages<br>Product Support<br>[SaaS/AMAs: Billing APIs](https://partneranalytics-api.azureedge.net/partneranalytics-api/Programmatic%20Access%20to%20Commercial%20Marketplace%20Analytics%20Data_v1.pdf)<br>[SaaS fulfillment API v.2](partner-center-portal/pc-saas-fulfillment-api-v2.md)<br>[Partner Payouts API](https://apidocs.microsoft.com/services/partnerpayouts) <br>[github](https://github.com/microsoft/Partner-Center-Payout-APIs)<br>[Metered billing API](marketplace-metering-service-apis.md)<br>[(EA Customer) Azure Consumption API](/rest/api/consumption/)<br>[(EA Customer) Azure Charges List API](/rest/api/consumption/charges/list) | Recurring billing<br>Overages<br>Product Support<br>PC Payouts Reports<br>PC Marketplace Analytics |
-| <center>**6. Contract End**<br><img src="media/api-guide/icon-contract-end.png" alt="The icon for contract end"> | Renew or<br>Terminate |Renew or<br>Terminate <br>[SaaS fulfillment API v.2](partner-center-portal/pc-saas-fulfillment-api-v2.md)<br>AMA/VM's: auto-renew | Renew or<br>Terminate<br>PC Marketplace Analytics |
+| <center>**4. Sale**<br><img src="media/api-guide/icon-sale.png" alt="The icon for sale"> | Contract signing<br>Revenue Recognition<br>Invoicing<br>Billing | Contract signing<br>Revenue Recognition<br>Invoicing<br>Billing<br>[SaaS fulfillment API v.2](partner-center-portal/pc-saas-fulfillment-apis.md)<br>[Reporting APIs](https://partneranalytics-api.azureedge.net/partneranalytics-api/Programmatic%20Access%20to%20Commercial%20Marketplace%20Analytics%20Data_v1.pdf) | Contract signing<br>Revenue Recognition<br>Invoicing<br>Billing<br>Azure portal / Admin Center<br>PC Marketplace Rewards<br>PC Payouts Reports<br>PC Marketplace Analytics<br>PC Co-Sell Closing |
+| <center>**5. Maintenance**<br><img src="media/api-guide/icon-maintenance.png" alt="The icon for maintenance"> | Recurring billing<br>Overages<br>Product Support | Recurring billing<br>Overages<br>Product Support<br>[SaaS/AMAs: Billing APIs](https://partneranalytics-api.azureedge.net/partneranalytics-api/Programmatic%20Access%20to%20Commercial%20Marketplace%20Analytics%20Data_v1.pdf)<br>[SaaS fulfillment API v.2](partner-center-portal/pc-saas-fulfillment-apis.md)<br>[Partner Payouts API](https://apidocs.microsoft.com/services/partnerpayouts) <br>[github](https://github.com/microsoft/Partner-Center-Payout-APIs)<br>[Metered billing API](marketplace-metering-service-apis.md)<br>[(EA Customer) Azure Consumption API](/rest/api/consumption/)<br>[(EA Customer) Azure Charges List API](/rest/api/consumption/charges/list) | Recurring billing<br>Overages<br>Product Support<br>PC Payouts Reports<br>PC Marketplace Analytics |
+| <center>**6. Contract End**<br><img src="media/api-guide/icon-contract-end.png" alt="The icon for contract end"> | Renew or<br>Terminate |Renew or<br>Terminate <br>[SaaS fulfillment API v.2](./partner-center-portal/pc-saas-fulfillment-apis.md)<br>AMA/VM's: auto-renew | Renew or<br>Terminate<br>PC Marketplace Analytics |
 |
 
 ## Next steps

articles/marketplace/marketplace-commercial-transaction-capabilities-and-considerations.md

@@ -193,7 +193,7 @@ The ability to transact through Microsoft is available for the following commerc
 
 - **Azure Virtual Machine**: Select from free, BYOL, or usage-based pricing models. On the customer's Azure bill, Microsoft presents the publisher software license fees separately from the underlying Azure infrastructure fees. Azure infrastructure fees are driven by use of the publisher’s software.
 
-- **SaaS application**: Must be a multitenant solution, use [Azure Active Directory](https://azure.microsoft.com/services/active-directory/) for authentication, and integrate with the [SaaS Fulfillment APIs](partner-center-portal/pc-saas-fulfillment-api-v2.md). Azure infrastructure usage is managed and billed directly to you (the publisher), so you must account for Azure infrastructure usage fees and software licensing fees as a single cost item. For detailed guidance, see [How to plan a SaaS offer for the commercial marketplace](plan-saas-offer.md#plans).
+- **SaaS application**: Must be a multitenant solution, use [Azure Active Directory](https://azure.microsoft.com/services/active-directory/) for authentication, and integrate with the [SaaS Fulfillment APIs](partner-center-portal/pc-saas-fulfillment-apis.md). Azure infrastructure usage is managed and billed directly to you (the publisher), so you must account for Azure infrastructure usage fees and software licensing fees as a single cost item. For detailed guidance, see [How to plan a SaaS offer for the commercial marketplace](plan-saas-offer.md#plans).
 
 ## Private plans
 

articles/marketplace/marketplace-metering-service-apis-faq.yml

@@ -82,7 +82,7 @@ sections:
       - question: |
           Can you get a list of all SaaS subscriptions, including active and unsubscribed subscriptions?
         answer: |
-          Yes, when you call the [GET Subscriptions List API](partner-center-portal/pc-saas-fulfillment-api-v2.md#subscription-apis) as it includes a list of all SaaS subscriptions. The status field in the response for each SaaS subscription captures whether the subscription is active or unsubscribed.
+          Yes, when you call the [GET Subscriptions List API](./partner-center-portal/pc-saas-fulfillment-subscription-api.md#get-list-of-all-subscriptions) as it includes a list of all SaaS subscriptions. The status field in the response for each SaaS subscription captures whether the subscription is active or unsubscribed.
           
       - question: |
           Are the start and end dates of SaaS subscription term and overage usage emission connected?

articles/marketplace/marketplace-metering-service-apis.md

@@ -36,7 +36,7 @@ Only one usage event can be emitted for each hour of a calendar day per resource
 
 *Query parameters:*
 
-| Paramter | Recommendation          |
+| Parameter | Recommendation          |
 | ---------- | ---------------------- |
 | `ApiVersion` | Use 2018-08-31. |
 | | |
@@ -67,7 +67,7 @@ Only one usage event can be emitted for each hour of a calendar day per resource
 
 For Azure Application Managed Apps plans, the `resourceId` is the Managed App `resource group Id`. An example script for fetching it can be found in [using the Azure-managed identities token](./marketplace-metering-service-authentication.md#using-the-azure-managed-identities-token). 
 
-For SaaS offers, the `resourceId` is the SaaS subscription ID. For more details on SaaS subscriptions, see [list subscriptions](partner-center-portal/pc-saas-fulfillment-api-v2.md#get-list-of-all-subscriptions).
+For SaaS offers, the `resourceId` is the SaaS subscription ID. For more details on SaaS subscriptions, see [list subscriptions](partner-center-portal/pc-saas-fulfillment-subscription-api.md#get-list-of-all-subscriptions).
 
 ### Responses
 
@@ -165,7 +165,7 @@ The batch usage event API allows you to emit usage events for more than one purc
 >[!NOTE]
 >In the request body, the resource identifier has different meanings for SaaS app and for Azure Managed app emitting custom meter. The resource identifier for SaaS App is `resourceID`. The resource identifier for Azure Application Managed Apps plans is `resourceUri`.
 
-For SaaS offers, the `resourceId` is the SaaS subscription ID. For more details on SaaS subscriptions, see [list subscriptions](partner-center-portal/pc-saas-fulfillment-api-v2.md#get-list-of-all-subscriptions).
+For SaaS offers, the `resourceId` is the SaaS subscription ID. For more details on SaaS subscriptions, see [list subscriptions](partner-center-portal/pc-saas-fulfillment-subscription-api.md#get-list-of-all-subscriptions).
 
 *Request body example for SaaS apps:*