Manage package flight submissions
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.
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.
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.
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}/submissionsThe 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.
If you are adding new packages for the submission, prepare the packages and add them to a ZIP archive.
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.
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);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}/commitCheck 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}/statusTo 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.
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:
- Create a package flight submission or get a package flight submission.
- 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.
- 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
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:
|
| 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. |
Related topics
- Create and manage submissions using Microsoft Store services
- Manage package flights using the Microsoft Store submission API
- Get a package flight submission
- Create a package flight submission
- Update a package flight submission
- Commit a package flight submission
- Delete a package flight submission
- Get the status of a package flight submission
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for