API Task Flows

The sections below describe the API flows for common uses of the App Submission API.

• API prerequisites
• About ETags
• About Edits
• The Edit lifecycle
• Create a new Edit
• Get the open Edit
• Get the previous Edit
• Manage APK files
  • Replace an existing APK
  • Delete an existing APK
  • Add a new APK
  • Upload a large APK
• Listings, details, and APK targets
• Image uploads
• Video uploads
• Set a future release date
• Commit the Edit
• Supported languages
• Supported time zones
• Troubleshoot error responses

API prerequisites

Before you use the App Submission API, follow these steps to obtain the App ID key and the open Edit ID for your app.

1. Log in to the Developer Console.
2. Navigate to Apps & Services and click the app.
3. On the Upload Your App File screen, copy the App ID key from the Additional information section.

About ETags

The API provides a mechanism to ensure that concurrent API calls do not cause resource updates to be overwritten. To update a resource, you send a GET request to obtain the current value of the resource, and then send a PUT request to update the value. The GET response includes an ETag, which is unique to the current value of the resource. You return the ETag in the PUT request. The request fails if the ETag value does not match the value on the server, because a mismatch indicates that the resource value has changed since you issued the GET request.

You also need to send the ETag in each DELETE request.

About Edits

To modify information about your app in the Appstore, you create an Edit. You can think of an Edit as a container for the next version of the app. The Edit allows you to prepare a number of changes to your app and then deploy the changes all at the same time. For example, you can update description fields and upload new resources (such as APK files and images) for the next version of your app. You make these changes in a single Edit, which stays in a draft state until you commit the changes.

When you first create an Edit, the Edit is a copy of the currently-deployed active app. You can then modify the Edit by calling the API methods. When you are ready to submit the changes, you commit the Edit to submit this app version to the Appstore. You can also delete the Edit at any time, which discards the changes and leaves your app as it was.

Note: Each app may have only a single Edit open at a time. If you send a request to create an Edit, but an active Edit already exists, you will receive a response with an error message.

The Edit lifecycle

This section shows a typical flow for using an Edit to update app information. The flow is identical whether you create a new Edit or retrieve the open Edit.

1. Create a new Edit or get the editId of the existing Edit.

2. Modify the Edit fields as required. In all of the API requests, the path parameters include the appId and editId of the Edit.

   Because the API supports PUT rather than PATCH, use the following pattern to update fields:

   1. Send a GET request to retrieve the current value of the field. Also retrieve the ETag from the header in the response.
   2. Modify the data in the field as required.
   3. Use a PUT request to update the whole field. Include the ETag in the PUT request header.

3. Upload resources as required. Depending on the resource type, this action may add the new resource to the list of resources, or it may overwrite the existing resource. Refer to the detailed sections below.

4. When you are ready to deploy the new app version, commit the Edit.

Create a new Edit

Call createEdit with the appId of the app that you want to modify.

This creates a new Edit for the specified app. The initial field values and uploads for the Edit (such as the APKs, store listings, and images) are copied from the deployed version of the app.

The successful response to this request includes the editId of the Edit. Use this Id in subsequent requests to update Edit fields or to upload resources.

Get the open Edit

Call getActiveEdit to get the editId of the open Edit for your app.

Get the previous Edit

If you have an active Edit and want to access the previous Edit, you can call getPreviousEdit to get the editId of the previous version. The previous Edit is typically a copy of the live version of your app. If you don't have an active Edit, a call to getPreviousEdit returns null.

Manage APK files

For exact request syntax, see the Edits.apks section in the API reference.

Replace an existing APK

Use the REPLACE method to replace an existing APK and keep the existing APK device-targeting information.

1. Call listApks to get the list of APKs.
2. Call replaceApk to replace the APK, and preserve the existing device targeting.

Delete an existing APK

Use the DELETE method to delete an APK.

If you want to replace an APK and delete the current targeting information, delete the APK and then upload the new version of the APK.

1. Call listApks to get the list of APKs.
2. Call deleteApk to delete the specified APK.
3. (Optional) Call uploadApk to upload a new version of the APK.

Add a new APK

To add a new APK, call uploadApk.

Upload a large APK

If your APK file is larger than 300M, call the following methods to upload the APK:

1. call uploadLargeAPK to upload the file.
2. call attachAPK to attach the APK to the Edit.

Listings, details, and APK targets

A new Edit object contains listings for each locale. Use the following steps to add information for a new locale or modify the store listing for an existing locale:

1. Call getListing.
2. Update the listing. Copy the ETag from the getListing response.
3. Call updateListing. Ensure that you add the ETag to the request header.

Follow the same pattern to modify the Edit details. Call the Get method, update the details as required, and then call modifyDetails to save the changes.

Follow the same pattern to modify the APK target devices. Call the Get method, add and update the device targets as required, and then call modifyTargeting to save the changes. See App Submission API Reference.

Image uploads

Call uploadImage to upload a new image. If the image type supports a single image (such as icons), the new image replaces the old image. For fields that support multiple image (such as screen shots), the image is added to the set of existing images. You can delete any images that you no longer need.

Valid values for imageType include:

• small-icons
• large-icons
• screenshots
• promo-images
• firetv-screenshots
• firetv-icons
• firetv-backgrounds
• firetv-featured-backgrounds
• firetv-featured-logos

For information about image sizes, see Image Asset Guidelines.

Video uploads

Call uploadVideo to upload new videos.

Set a future release date

By default, the Edit contains a NULL release date. After you commit the Edit, the Appstore starts the publishing procedure for the new version of the app.

To set a future release date, call putAvailability. In the request body, specify the release date/time using a dateTime value and a zoneId value.

dateTime follows the UTC format: YYYY-MM-DDThh:mm:ss.s (such as 2017-07-16T19:20:30.45).

zoneId value is one of the supported time zones.

Commit the Edit

To submit the changes to the Appstore, call commitEdit.

If there are no validation errors, all the changes specified in the Edit will become part of the live app. These changes can take several hours to get published, just as when you make changes through the Play Console.

Supported languages

The following table displays the supported values for the language parameter.

Abbreviation	Language
zh_CN	Chinese
de_DE	German
en_AU	English (Australia)
en_GB	English (UK)
en_IN	English (India)
en_US	English (US)
es_ES	Spanish
fr_FR	French
it_IT	Italian
ja_JP	Japanese
pt_BR	Brazilan Portuguese

Supported time zones

The following tables display the supported values for the zoneId parameter.

Troubleshoot error responses

Apps cannot be updated when they are in the Amazon review process. If you get an HTTP 412 "Precondition Failed" response when updating your app through the App Submission API, this means the app is pending and might be in the review state. To determine the status of your app, log in to the Developer Console, select App List from the dashboard, choose your app and view the App Status screen. After you have addressed the issue and your app is live, you should no longer get the HTTP 412 "Precondition Failed" error.

For more details about API requests and responses see the App Submission API reference.

---

Last updated: Oct 02, 2023