Edit

Share via

Manage package flight submissions

  • Article

The Microsoft Store submission API provides methods you can use to manage package flight submissions for your apps, including gradual package rollouts. For an introduction to the Microsoft Store submission API, including prerequisites for using the API, see Create and manage submissions using Microsoft Store services.

Important

If you use the Microsoft Store submission API to create a submission for a package flight, be sure to make further changes to the submission only by using the API, rather than Partner Center. If you use the dashboard to change a submission that you originally created by using the API, you will no longer be able to change or commit that submission by using the API. In some cases, the submission could be left in an error state where it cannot proceed in the submission process. If this occurs, you must delete the submission and create a new submission.

Methods for managing package flight submissions

Use the following methods to get, create, update, commit, or delete a package flight submission. Before you can use these methods, the package flight must already exist in Partner Center. You can create a package flight in Partner Center or by using the Microsoft Store submission API methods in described in Manage package flights.

Method URI Description
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Get an existing package flight submission
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status Get the status of an existing package flight submission
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions Create a new package flight submission
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Update an existing package flight submission
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit Commit a new or updated package flight submission
DELETE https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Delete a package flight submission

Create a package flight submission

To create a submission for a package flight, follow this process.

  1. If you have not yet done so, complete the prerequisites described in Create and manage submissions using Microsoft Store services, including associating an Azure AD application with your Partner Center account and obtaining your client ID and key. You only need to do this one time; after you have the client ID and key, you can reuse them any time you need to create a new Azure AD access token.

  2. Obtain an Azure AD access token. You must pass this access token to the methods in the Microsoft Store submission API. After you obtain an access token, you have 60 minutes to use it before it expires. After the token expires, you can obtain a new one.

  3. Create a package flight submission by executing the following method in the Microsoft Store submission API. This method creates a new in-progress submission, which is a copy of your last published submission.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions

    The response body contains a flight submission resource that includes the ID of the new submission, the shared access signature (SAS) URI for uploading any packages for the submission to Azure Blob Storage, and the data for the new submission (including all the listings and pricing information).

    Note

    A SAS URI provides access to a secure resource in Azure storage without requiring account keys. For background information about SAS URIs and their use with Azure Blob Storage, see Shared Access Signatures, Part 1: Understanding the SAS model and Shared Access Signatures, Part 2: Create and use a SAS with Blob storage.

  4. If you are adding new packages for the submission, prepare the packages and add them to a ZIP archive.

  5. Revise the flight submission data with any required changes for the new submission, and execute the following method to update the package flight submission.

    PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}

    Note

    If you are adding new packages for the submission, make sure you update the submission data to refer to the name and relative path of these files in the ZIP archive.

  6. If you are adding new packages for the submission, upload the ZIP archive to Azure Blob Storage using the SAS URI that was provided in the response body of the POST method you called earlier. There are different Azure libraries you can use to do this on a variety of platforms, including:

    The following C# code example demonstrates how to upload a ZIP archive to Azure Blob Storage using the CloudBlockBlob class in the Azure Storage Client Library for .NET. This example assumes that the ZIP archive has already been written to a stream object.

    string sasUrl = "https://productingestionbin1.blob.core.windows.net/ingestion/26920f66-b592-4439-9a9d-fb0f014902ec?sv=2014-02-14&sr=b&sig=usAN0kNFNnYE2tGQBI%2BARQWejX1Guiz7hdFtRhyK%2Bog%3D&se=2016-06-17T20:45:51Z&sp=rwl";
Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob blockBob =
    new Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob(new System.Uri(sasUrl));
await blockBob.UploadFromStreamAsync(stream);

  7. Commit the package flight submission by executing the following method. This will alert Partner Center that you are done with your submission and that your updates should now be applied to your account.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit

  8. Check on the commit status by executing the following method to get the status of the package flight submission.

    GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status

    To confirm the submission status, review the status value in the response body. This value should change from CommitStarted to either PreProcessing if the request succeeds or to CommitFailed if there are errors in the request. If there are errors, the statusDetails field contains further details about the error.

  9. After the commit has successfully completed, the submission is sent to the Store for ingestion. You can continue to monitor the submission progress by using the previous method, or by visiting Partner Center.

Code examples

The following articles provide detailed code examples that demonstrate how to create a package flight submission in several different programming languages:

StoreBroker PowerShell module

As an alternative to calling the Microsoft Store submission API directly, we also provide an open-source PowerShell module which implements a command-line interface on top of the API. This module is called StoreBroker. You can use this module to manage your app, flight, and add-on submissions from the command line instead of calling the Microsoft Store submission API directly, or you can simply browse the source to see more examples for how to call this API. The StoreBroker module is actively used within Microsoft as the primary way that many first-party applications are submitted to the Store.

For more information, see our StoreBroker page on GitHub.

Manage a gradual package rollout for a package flight submission

You can gradually roll out the updated packages in a package flight submission to a percentage of your app’s customers on Windows 10 and Windows 11. This allows you to monitor feedback and analytic data for the specific packages to make sure you’re confident about the update before rolling it out more broadly. You can change the rollout percentage (or halt the update) for a published submission without having to create a new submission. For more details, including instructions for how to enable and manage a gradual package rollout in Partner Center, see this article.

To programmatically enable a gradual package rollout for a package flight submission, follow this process using methods in the Microsoft Store submission API:

  1. Create a package flight submission or get a package flight submission.
  2. In the response data, locate the packageRollout resource, set the isPackageRollout field to true, and set the packageRolloutPercentage field to the percentage of your app's customers who should get the updated packages.
  3. Pass the updated package flight submission data to the update a package flight submission method.

After a gradual package rollout is enabled for a package flight submission, you can use the following methods to programmatically get, update, halt, or finalize the gradual rollout.

Method URI Description
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout Get the gradual rollout info for a package flight submission
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage Update the gradual rollout percentage for a package flight submission
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout Halt the gradual rollout for a package flight submission
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout Finalize the gradual rollout for a package flight submission

Data resources

The Microsoft Store submission API methods for managing package flight submissions use the following JSON data resources.

Flight submission resource

This resource describes a package flight submission.

{
  "id": "1152921504621243649",
  "flightId": "cd2e368a-0da5-4026-9f34-0e7934bc6f23",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [],
    "warnings": [],
    "certificationReports": []
  },
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
  "fileUploadUrl": "https://productingestionbin1.blob.core.windows.net/ingestion/8b389577-5d5e-4cbe-a744-1ff2e97a9eb8?sv=2014-02-14&sr=b&sig=wgMCQPjPDkuuxNLkeG35rfHaMToebCxBNMPw7WABdXU%3D&se=2016-06-17T21:29:44Z&sp=rwl",
  "targetPublishMode": "Immediate",
  "targetPublishDate": "",
  "notesForCertification": "No special steps are required for certification of this app."
}

This resource has the following values.

Value Type Description
id string The ID for the submission.
flightId string The ID of the package flight that the submission is associated with.
status string The status of the submission. This can be one of the following values:
  • None
  • Canceled
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Publishing
  • Published
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Certification
  • CertificationFailed
  • Release
  • ReleaseFailed
statusDetails object A status details resource that contains additional details about the status of the submission, including information about any errors.
flightPackages array Contains flight package resources that provide details about each package in the submission.
packageDeliveryOptions object A package delivery options resource that contains gradual package rollout and mandatory update settings for the submission.
fileUploadUrl string The shared access signature (SAS) URI for uploading any packages for the submission. If you are adding new packages for the submission, upload the ZIP archive that contains the packages to this URI. For more information, see Create a package flight submission.
targetPublishMode string The publish mode for the submission. This can be one of the following values:
  • Immediate
  • Manual
  • SpecificDate
targetPublishDate string The publish date for the submission in ISO 8601 format, if the targetPublishMode is set to SpecificDate.
notesForCertification string Provides additional info for the certification testers, such as test account credentials and steps to access and verify features. For more information, see Notes for certification.

Status details resource

This resource contains additional details about the status of a submission. This resource has the following values.

Value Type Description
errors object An array of status detail resources that contain error details for the submission.
warnings object An array of status detail resources that contain warning details for the submission.
certificationReports object An array of certification report resources that provide access to the certification report data for the submission. You can examine these reports for more information if the certification fails.

Status detail resource

This resource contains additional information about any related errors or warnings for a submission. This resource has the following values.

Value Type Description
code string A submission status code that describes the type of error or warning.
details string A message with more details about the issue.

Certification report resource

This resource provides access to the certification report data for a submission. This resource has the following values.

Value Type Description
date string The date and time the report was generated, in ISO 8601 format.
reportUrl string The URL at which you can access the report.

Flight package resource

This resource provides details about a package in a submission.

{
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
}

This resource has the following values.

Note

When calling the update a package flight submission method, only the fileName, fileStatus, minimumDirectXVersion, and minimumSystemRam values of this object are required in the request body. The other values are populated by Partner Center.

Value Type Description
fileName string The name of the package.
fileStatus string The status of the package. This can be one of the following values:
  • None
  • PendingUpload
  • Uploaded
  • PendingDelete
id string An ID that uniquely identifies the package. This value is used by Partner Center.
version string The version of the app package. For more information, see Package version numbering.
architecture string The architecture of the app package (for example, ARM).
languages array An array of language codes for the languages the app supports. For more information, see For more information, see Supported languages.
capabilities array An array of capabilities required by the package. For more information about capabilities, see App capability declarations.
minimumDirectXVersion string The minimum DirectX version that is supported by the app package. This can be set only for apps that target Windows 8.x; it is ignored for apps that target other versions. This can be one of the following values:
  • None
  • DirectX93
  • DirectX100
minimumSystemRam string The minimum RAM that is required by the app package. This can be set only for apps that target Windows 8.x; it is ignored for apps that target other versions. This can be one of the following values:
  • None
  • Memory2GB

Package delivery options resource

This resource contains gradual package rollout and mandatory update settings for the submission.

{
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
}

This resource has the following values.

Value Type Description
packageRollout object A package rollout resource that contains gradual package rollout settings for the submission.
isMandatoryUpdate boolean Indicates whether you want to treat the packages in this submission as mandatory for self-installing app updates. For more information about mandatory packages for self-installing app updates, see Download and install package updates for your app.
mandatoryUpdateEffectiveDate date The date and time when the packages in this submission become mandatory, in ISO 8601 format and UTC time zone.

Package rollout resource

This resource contains gradual package rollout settings for the submission. This resource has the following values.

Value Type Description
isPackageRollout boolean Indicates whether gradual package rollout is enabled for the submission.
packageRolloutPercentage float The percentage of users who will receive the packages in the gradual rollout.
packageRolloutStatus string One of the following strings that indicates the status of the gradual package rollout:
  • PackageRolloutNotStarted
  • PackageRolloutInProgress
  • PackageRolloutComplete
  • PackageRolloutStopped
fallbackSubmissionId string The ID of the submission that will be received by customers who do not get the gradual rollout packages.

Note

The packageRolloutStatus and fallbackSubmissionId values are assigned by Partner Center, and are not intended to be set by the developer. If you include these values in a request body, these values will be ignored.

Enums

These methods use the following enums.

Submission status code

The following codes represent the status of a submission.

Code Description
None No code was specified.
InvalidArchive The ZIP archive containing the package is invalid or has an unrecognized archive format.
MissingFiles The ZIP archive does not have all files which were listed in your submission data, or they are in the wrong location in the archive.
PackageValidationFailed One or more packages in your submission failed to validate.
InvalidParameterValue One of the parameters in the request body is invalid.
InvalidOperation The operation you attempted is invalid.
InvalidState The operation you attempted is not valid for the current state of the package flight.
ResourceNotFound The specified package flight could not be found.
ServiceError An internal service error prevented the request from succeeding. Try the request again.
ListingOptOutWarning The developer removed a listing from a previous submission, or did not include listing information that is supported by the package.
ListingOptInWarning The developer added a listing.
UpdateOnlyWarning The developer is trying to insert something that only has update support.
Other The submission is in an unrecognized or uncategorized state.
PackageValidationWarning The package validation process resulted in a warning.