Manage add-on submissions

Article
01/04/2023

The Microsoft Store submission API provides methods you can use to manage add-on (also known as in-app product or IAP) submissions for your apps. 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 an add-on, be sure to make further changes to the submission only by using the API, rather than making changes in Partner Center. If you use Partner Center 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 add-on submissions

Use the following methods to get, create, update, commit, or delete an add-on submission. Before you can use these methods, the add-on must already exist in your Partner Center account. You can create an add-on in Partner Center by defining its product type and product ID or by using the Microsoft Store submission API methods in described in Manage add-ons.

Method	URI	Description
GET	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	Get an existing add-on submission
GET	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status	Get the status of an existing add-on submission
POST	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions	Create a new add-on submission
PUT	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	Update an existing add-on submission
POST	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit	Commit a new or updated add-on submission
DELETE	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	Delete an add-on submission

Create an add-on submission

To create a submission for an add-on, 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.
Execute 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. For more information, see Create an add-on submission.
```
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions
```
The response body contains an add-on submission resource that includes the ID of the new submission, the shared access signature (SAS) URI for uploading any add-on icons for the submission to Azure Blob Storage, and all of the data for the new submission (such as 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 icons for the submission, prepare the icons and add them to a ZIP archive.
Update the add-on submission data with any required changes for the new submission, and execute the following method to update the submission. For more information, see Update an add-on submission.
```
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}
```
Note

If you are adding new icons 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 icons 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 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. For more information, see Commit an add-on submission.
```
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit
```
Check on the commit status by executing the following method. For more information, see Get the status of an add-on submission.
```
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/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.
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 an add-on 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.

Data resources

The Microsoft Store submission API methods for managing add-on submissions use the following JSON data resources.

Add-on submission resource

This resource describes an add-on submission.

{
  "id": "1152921504621243680",
  "contentType": "EMagazine",
  "keywords": [
    "books"
  ],
  "lifetime": "FiveDays",
  "listings": {
    "en": {
      "description": "English add-on description",
      "icon": {
        "fileName": "add-on-en-us-listing2.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (English)"
    },
    "ru": {
      "description": "Russian add-on description",
      "icon": {
        "fileName": "add-on-ru-listing.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (Russian)"
    }
  },
  "pricing": {
    "marketSpecificPricings": {
      "RU": "Tier3",
      "US": "Tier4",
    },
    "sales": [],
    "priceId": "Free",
    "isAdvancedPricingModel": true
  },
  "targetPublishDate": "2016-03-15T05:10:58.047Z",
  "targetPublishMode": "Immediate",
  "tag": "SampleTag",
  "visibility": "Public",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [
      {
        "code": "None",
        "details": "string"
      }
    ],
    "warnings": [
      {
        "code": "ListingOptOutWarning",
        "details": "You have removed listing language(s): []"
      }
    ],
    "certificationReports": [
      {
      }
    ]
  },
  "fileUploadUrl": "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",
  "friendlyName": "Submission 2"
}

This resource has the following values.

Value	Type	Description
id	string	The ID of the submission. This ID is available in the response data for requests to create an add-on submission, get all add-ons, and get an add-on. For a submission that was created in Partner Center, this ID is also available in the URL for the submission page in Partner Center.
contentType	string	The type of content that is provided in the add-on. This can be one of the following values: NotSet BookDownload EMagazine ENewspaper MusicDownload MusicStream OnlineDataStorage VideoDownload VideoStream Asp OnlineDownload
keywords	array	An array of strings that contain up to 10 keywords for the add-on. Your app can query for add-ons using these keywords.
lifetime	string	The lifetime of the add-on. This can be one of the following values: Forever OneDay ThreeDays FiveDays OneWeek TwoWeeks OneMonth TwoMonths ThreeMonths SixMonths OneYear
listings	object	A dictionary of key and value pairs, where each key is a two-letter ISO 3166-1 alpha-2 country code and each value is a listing resource that contains listing info for the add-on.
pricing	object	A pricing resource that contains pricing info for the add-on.
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.
tag	string	The custom developer data for the add-on (this information was previously called the tag).
visibility	string	The visibility of the add-on. This can be one of the following values: Hidden Public Private NotSet
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.
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 an add-on submission.
friendlyName	string	The friendly name of the submission, as shown in Partner Center. This value is generated for you when you create the submission.

Listing resource

This resource contains listing info for an add-on. This resource has the following values.

Value	Type	Description
description	string	The description for the add-on listing.
icon	object	An icon resource that contains data for the icon for the add-on listing.
title	string	The title for the add-on listing.

Icon resource

This resource contains icon data for an add-on listing. This resource has the following values.

Value	Type	Description
fileName	string	The name of the icon file in the ZIP archive that you uploaded for the submission. The icon must be a .png file that measures exactly 300 x 300 pixels.
fileStatus	string	The status of the icon file. This can be one of the following values: None PendingUpload Uploaded PendingDelete

Pricing resource

This resource contains pricing info for the add-on. This resource has the following values.

Value	Type	Description
marketSpecificPricings	object	A dictionary of key and value pairs, where each key is a two-letter ISO 3166-1 alpha-2 country code and each value is a price tier. These items represent the custom prices for your add-on in specific markets. Any items in this dictionary override the base price specified by the priceId value for the specified market.
sales	array	Deprecated. An array of sale resources that contain sales information for the add-on.
priceId	string	A price tier that specifies the base price for the add-on.
isAdvancedPricingModel	boolean	If true, your developer account has access to the expanded set of price tiers from .99 USD to 1999.99 USD. If false, your developer account has access to the original set of price tiers from .99 USD to 999.99 USD. For more information about the different tiers, see price tiers. Note This field is read-only.

Sale resource

This resources contains sale info for an add-on.

Important

The Sale resource is no longer supported, and currently you cannot get or modify the sale data for an add-on submission using the Microsoft Store submission API. In the future, we will update the Microsoft Store submission API to introduce a new way to programmatically access sales information for add-on submissions.

After calling the GET method to get an add-on submission, the sales value will be empty. You can continue to use Partner Center to get the sale data for your add-on submission.
When calling the PUT method to update an add-on submission, the information in the sales value is ignored. You can continue to use Partner Center to change the sale data for your add-on submission.

This resource has the following values.

Value	Type	Description
name	string	The name of the sale.
basePriceId	string	The price tier to use for the base price of the sale.
startDate	string	The start date for the sale in ISO 8601 format.
endDate	string	The end date for the sale in ISO 8601 format.
marketSpecificPricings	object	A dictionary of key and value pairs, where each key is a two-letter ISO 3166-1 alpha-2 country code and each value is a price tier. These items represent the custom prices for your add-on in specific markets. Any items in this dictionary override the base price specified by the basePriceId value for the specified market.

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.

Enums

These methods use the following enums.

Price tiers

The following values represent available price tiers in the pricing resource resource for an add-on submission.

Value	Description
Base	The price tier is not set; use the base price for the add-on.
NotAvailable	The add-on is not available in the specified region.
Free	The add-on is free.
Tierxxxx	A string that specifies the price tier for the add-on, in the format Tierxxxx. Currently, the following ranges of price tiers are supported: If the isAdvancedPricingModel value of the pricing resource is true, the available price tier values for your account are Tier1012 - Tier1424. If the isAdvancedPricingModel value of the pricing resource is false, the available price tier values for your account are Tier2 - Tier96. To see the complete table of price tiers that are available for your developer account, including the market-specific prices that are associated with each tier, go to the Pricing and availability page for any of your app submissions in Partner Center and click the view table link in the Markets and custom prices section (for some developer accounts, this link is in the Pricing section).

Submission status code

The following values represent the status code of a submission.

Value	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.

Share via

Manage add-on submissions

Methods for managing add-on submissions

Create an add-on submission

Code examples

StoreBroker PowerShell module

Data resources

Add-on submission resource

Listing resource

Icon resource

Pricing resource

Sale resource

Status details resource

Status detail resource

Certification report resource

Enums

Price tiers

Submission status code

Feedback

Additional resources

Share via

Manage add-on submissions

Methods for managing add-on submissions

Create an add-on submission

Code examples

StoreBroker PowerShell module

Data resources

Add-on submission resource

Listing resource

Icon resource

Pricing resource

Sale resource

Status details resource

Status detail resource

Certification report resource

Enums

Price tiers

Submission status code

Related topics

Feedback

Additional resources