SaaS fulfillment Subscription APIs v2 in Microsoft Marketplace

This article describes version 2 of the SaaS fulfillment subscription APIs.

Resolve a purchased subscription

The resolve endpoint enables the publisher to exchange the purchase identification token from Microsoft Marketplace (referred to as token in Purchased but not yet activated) for a persistent purchased SaaS subscription ID and its details.

When a customer is redirected to the partner's landing page URL, the customer identification token is passed as the token parameter in this URL call. The partner uses this token to make a request to resolve it. The Resolve API response contains the SaaS subscription ID and other details to uniquely identify the purchase. The token provided with the landing page URL call is valid for 24 hours. If the token that you receive is expired, provide the following guidance to the end user:

"We couldn't identify this purchase. Reopen this SaaS subscription in the Azure portal or in Microsoft 365 Admin Center and select Configure Account or Manage Account again."

Calling the Resolve API returns subscription details and status for SaaS subscriptions in all supported statuses.

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<api-version>

Query parameters:

Request headers:

Response codes:

Code: 200 Returns unique SaaS subscription identifiers based on the x-ms-marketplace-token provided.

Response body example:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased licenses, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
      "tenantId": "<guid>", 
      "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>", //for informational purposes, showing who made the purchase
      "tenantId": "<guid>",
      "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Code: 400 Bad request. x-ms-marketplace-token is missing, malformed, invalid, or expired.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Activate a subscription

After configuring the SaaS account for an end user, the publisher must call the Activate Subscription API on the Microsoft side. The customer isn't billed unless this API call is successful.

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<api-version>

Query parameters:

Request headers:

Response codes:

Code: 200 Request to update the subscription and mark as "Subscribed" is received. Independent Software Vendors (ISVs) can check for the status of the subscription after a few minutes (read on for the Get operation to check subscription status). This operation gives you the definitive answer whether subscription was successfully updated. Failure to subscribe automatically sends an "Unsubscribe" webhook.

There's no response body for this call.

Code: 400 Bad request: validation failed.

• The SaaS subscription is in Suspended state.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 404 Not found. The SaaS subscription is in an Unsubscribed state.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Get list of all subscriptions

This API retrieves a list of all purchased SaaS subscriptions for all offers that the publisher publishes in Microsoft Marketplace. The API returns SaaS subscriptions in all possible statuses, including unsubscribed subscriptions, because Microsoft doesn't delete this information.

The API returns paginated results. You must pass the continuationToken to get the subsequent results.

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<api-version>

Query parameters:

Request headers:

Response codes:

Code: 200 Returns the list of all existing subscriptions for all offers made by this publisher, based on the publisher's authorization token.

Response body example:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of licenses, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>", //for informational purposes, showing who made the purchase
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>", //for informational purposes, showing who made the purchase
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

If no purchased SaaS subscriptions are found for this publisher, the response body is empty.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Get subscription

This API retrieves a specified purchased SaaS subscription for a SaaS offer that the publisher publishes in Microsoft Marketplace. Use this call to get all available information for a specific SaaS subscription by its ID rather than by calling the API that's used for getting a list of all subscriptions.

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

Query parameters:

Request headers:

Response codes:

Code: 200 Returns details for a SaaS subscription based on the subscriptionId you provide.

Response body example:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of licenses is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
    "tenantId": "<guid>",
    "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>", //for informational purposes, showing who made the purchase
    "tenantId": "<guid>",
    "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 404 Not found. SaaS subscription with the specified subscriptionId can't be found.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

List available plans

This API retrieves all plans for a SaaS offer identified by the subscriptionId of a specific purchase of this offer. Use this call to get a list of all private and public plans that the beneficiary of a SaaS subscription can update for the subscription. The plans returned are available in the same geography as the already purchased plan.

This call returns a list of plans available for that customer in addition to the one already purchased. You can present the list to an end user on the publisher site. An end user can change the subscription plan to any one of the plans in the returned list. Changing the plan to a plan not in the list doesn't work.

This API also retrieves the active private offer ID associated (if you call the API with planId filter). Calling API with planId filter shows the active private offer ID GUIDs in the response body under sourceOffers node. The planId passed in the filter param should match the planId the customer purchased.

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<api-version>&planId=<planId>

Query parameters:

Request headers:

Response codes:

Code: 200 Returns a list of all available plans for an existing SaaS subscription including the one already purchased.

Passing invalid (optional) planId returns empty list of plans.

Response body example:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Code: 404 Not Found. subscriptionId isn't found.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Change the plan on the subscription

Use this API to update the existing plan purchased for a SaaS subscription to a new plan (public or private). The publisher must call this API when they change a plan on the publisher side for a SaaS subscription purchased in Microsoft Marketplace.

You can call this API only for Active subscriptions. You can change any plan to any other existing plan (public or private) but not to itself. For private plans, you must define the customer's tenant as part of the plan's audience in Partner Center.

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

Query parameters:

Request headers:

Request payload example:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Response codes:

Code: 202 The request to change plan is accepted and handled asynchronously. The partner app should poll the Operation-Location URL to determine a success or failure of the change plan request. Poll every few seconds until the final status of Failed, Succeed, or Conflict is received for the operation. Final operation status returns quickly, but can take several minutes in some cases.

The partner app also gets webhook notification when the action is ready to be completed successfully in Microsoft Marketplace. Only then should the publisher make the plan change on the publisher side.

Response headers:

Code: 400 Bad request: validation failures.

• The requested plan can't be found or the plan isn't available for the user.
• The requested plan is the same as the subscribed plan.
• The SaaS subscription status isn't Subscribed.
• The SaaS subscription being updated is purchased by a Cloud Solution Provider (CSP). You must work with the CSP provider to perform this action.
• The SaaS subscription can't be managed until it's renewed after transfer. This restriction applies until renewal date.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 404 Not found. The SaaS subscription with the specified subscriptionId can't be found.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Change the quantity of licenses on the SaaS subscription

Use this API to update (increase or decrease) the quantity of licenses purchased for a SaaS subscription. The publisher must call this API when the number of licenses changes from the publisher side for a SaaS subscription created in Microsoft Marketplace.

The quantity of licenses can't exceed the quantity allowed in the current plan. In this case, the publisher should change the plan before changing the quantity of licenses.

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

Query parameters:

Request headers:

Request payload example:

{
  "quantity": 5 // the new amount of licenses to be purchased
}

Response codes:

Code: 202 The request to change quantity is accepted and handled asynchronously. The partner is expected to poll the Operation-Location URL to determine a success or failure of the change quantity request. Poll every several seconds until the final status of Failed, Succeed, or Conflict is received for the operation. The final operation status returns quickly but can take several minutes in some cases.

The partner also gets webhook notification when the action is ready to be completed successfully in Microsoft Marketplace. Only then should the publisher make the quantity change on the publisher side.

Response headers:

Code: 400 Bad request: validation failures.

• The new quantity isn't within the allowed range.
• The new quantity is missing or 0.
• The new quantity is the same as the current quantity.
• The SaaS Subscription status isn't Subscribed.
• The SaaS subscription being updated is purchased by a Cloud Solution Provider (CSP). You must work with the CSP provider to perform this action.
• The SaaS subscription can't be managed until it's renewed after transfer. This restriction applies until renewal date.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error is often a symptom of not performing the SaaS registration correctly.

Code: 404 Not found. The SaaS subscription with the specified subscriptionId can't be found.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Cancel a subscription

Use this API to unsubscribe a specified SaaS subscription. The publisher doesn't have to use this API. Direct customers to Microsoft Marketplace to cancel SaaS subscriptions.

If the publisher decides to implement the cancellation of a SaaS subscription purchased in Microsoft Marketplace on the publisher's side, they must call this API. After the completion of this call, the subscription's status becomes Unsubscribed on the Microsoft side.

The customer isn't billed if a subscription is canceled within 72 hours from purchase.

The customer is billed if a subscription is canceled after the preceding grace period. The customer loses access to the SaaS subscription on the Microsoft side immediately after cancellation.

Delete https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

Query parameters:

Request headers:

Response codes:

Code: 202 The request to unsubscribe is accepted and handled asynchronously. The partner is expected to poll the Operation-Location URL to determine a success or failure of this request. Poll every several seconds until the final status of Failed, Succeed, or Conflict is received for the operation. The final operation status returns quickly but can take several minutes in some cases.

The partner also gets webhook notification when the action is completed successfully in Microsoft Marketplace. Only then should the publisher cancel the subscription on the publisher side.

Code: 200 The subscription is already in an Unsubscribed state.

Response headers:

Code: 400

• Bad request. Delete isn't in allowedCustomerOperations list for this SaaS subscription.
• The SaaS subscription can't be managed until it's renewed after transfer. This restriction applies until renewal date.

Code: 401 Unauthorized. The authorization token is invalid or expired. The request is attempting to access a SaaS subscription for an offer that was published with a different Microsoft Entra app ID from the one used to create the authentication token.

Code: 403 Forbidden. The authorization token is invalid, wasn't provided, or was provided with insufficient permissions. Provide a valid authorization token.

This error often indicates that the SaaS registration wasn't performed correctly.

Code: 404 Not found. The SaaS subscription with subscriptionId isn't found.

Code: 409

Delete can't be completed because subscription is locked due to pending operations.

Code: 500 Internal server error. Retry the API call. If the error persists, contact Microsoft support.

Free trials

A SaaS subscription can be in a free trial when the customer purchases a trial-enabled plan. Use the subscription APIs to activate trial-enabled subscriptions, identify whether a subscription is currently in a free trial, identify which available plans have free trials configured, change a customer from a free trial to a paid plan, and cancel a free trial before it converts to paid.

When isFreeTrial is true, the subscription is active, but the customer isn't charged for the plan until the trial ends or the customer upgrades to paid before the trial ends.

When the free trial ends or the customer upgrades to paid, isFreeTrial is set to false.

Related content

• For more options for SaaS offers in Microsoft Marketplace, see the Microsoft Marketplace metering service APIs.
• Review and use the clients for different programming languages and samples.
• For testing guidance, see Implementing a webhook on the SaaS service.