SaaS fulfillment operations APIs v2 in the Microsoft commercial marketplace

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

Operations are useful to respond to any requests that come through the webhook as part of ChangePlan, ChangeQuantity, and Reinstate actions. This provides an opportunity to accept or reject a request by patch that webhook operation with Success or Failure by using the below APIs.

This only applies to webhook events such as ChangePlan, ChangeQuantity, and Reinstate that need an ACK. No action is needed from the independent software vendor (ISV) on Renew, Suspend, and Unsubscribe events because they're notify-only events.

List outstanding operations

Get list of the pending operations for the specified SaaS subscription. The publisher should acknowledge returned operations by calling the Operation Patch API.

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

Query parameters:

Request headers:

Response codes:

Code: 200 Returns pending operations on the specified SaaS subscription.

Response payload example:

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Returns empty json if no operations are pending.

Code: 400 Bad request: validation failures.

Code: 403 Forbidden. The authorization token is invalid, expired, or wasn't provided. The request is attempting to access a SaaS subscription for an offer that's published with a different Microsoft Entra app ID from the one used to create the authorization token.

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

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

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

Get operation status

This API enables the publisher to track the status of the specified async operation: Unsubscribe, ChangePlan, or ChangeQuantity.

The operationId for this API call can be retrieved from the value returned by Operation-Location, the get pending Operations API call, or the <id> parameter value received in a webhook call.

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

Query parameters:

Request headers:

Response codes:

Code: 200 Gets details for the specified SaaS operation.

Response payload example:

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

Code: 403 Forbidden. The authorization token is invalid, expired, or wasn't provided. The request is attempting to access a SaaS subscription for an offer that's published with a different Microsoft Entra app ID from the one used to create the authorization token.

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

Code: 404 Not found.

• Subscription with subscriptionId isn't found.
• Operation with operationId isn't found.

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

Update the status of an operation

Use this API to update the status of a pending operation to indicate the operation's success or failure on the publisher side.

The operationId for this API call can be retrieved from the value returned by Operation-Location, the get pending Operations API call, or the <id> parameter value received in a webhook call.

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

Query parameters:

Request headers:

Request payload example:

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

Response codes:

Code: 200 A call to inform of completion of an operation on the partner side. For example, this response could signal the completion of change of seats or plans on the publisher side.

Code: 403

• Forbidden. The authorization token isn't available, is invalid, or expired. The request might be attempting to access a subscription that doesn't belong to the current publisher.
• Forbidden. The authorization token is invalid, expired, or wasn't provided. The request is attempting to access a SaaS subscription for an offer that's published with a different Microsoft Entra app ID from the one used to create the authorization token.

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

Code: 404 Not found.

• Subscription with subscriptionId isn't found.
• Operation with operationId isn't found.

Code: 409 Conflict. For example, a newer update is already fulfilled.

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

Related content

• See the commercial marketplace metering service APIs for more options for SaaS offers in the commercial marketplace.
• Review and use the clients for different programming languages and samples.