Create, Edit, and Retrieve A+ Media Assets

Learn how to create image and video media assets, retrieve media metadata and related pairings, and update media titles and accessibility descriptions. Media that you upload to the A+ Media Library can be referenced where required by certain A+ modules.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• The Product Listing role assigned to your developer profile.
• The Product Listing role selected in the app registration page for your application.
• One or more image or video files that you want to add to the A+ media library.

Step 1. Create a media asset

To create a media asset, you need to:

1. Upload your file
2. Create the media asset

Step 1a. Upload your file

Call the createUploadDestinationForResource operation of the Uploads API. Upload your file by making a POST request to the url from the createUploadDestinationForResource response. Confirm that you receive a 2XX response.

🚧

Important

Images must comply with Amazon's product image requirements. Videos must comply with video content requirements.

Save the uploadDestinationId value for the following step.

Step 1b. Create the media asset

Call the createMedia operation. The mediaType field determines the type of asset to create.

createMedia is idempotent. The response status code indicates the result:

• 201: A new media asset or pairing was created.
• 200: The asset or pairing already exists with identical metadata. The existing data is returned.
• 409: The asset or pairing already exists but the metadata fields differ.

The response returns the full unified Media shape, including the assigned mediaId, a composite status, a mediaUrl, any issues, and the relatedMedia associations. Newly created video assets typically return a status of PENDING_PROCESSING and PENDING_AMAZON while Amazon processes the file.

📘

Note

If you provide an uploadDestinationId, it is resolved to a mediaId before any further processing. A request that references an asset by uploadDestinationId and a later request that uses the resulting mediaId are treated as referring to the same asset.

Step 2. Retrieve a media asset

Call the getMedia operation and pass the mediaId value.

The response contains the unified Media shape and includes related media associations. The response also includes a composite status array and an issues array, which you can use to determine the state of the asset and whether action is required. Possible status values are:

• PENDING_PROCESSING: Media is being processed (transcoding, validation).
• PENDING_REVIEW: Processing is complete; the media is awaiting content compliance review.
• UNABLE_TO_PROCESS: Processing failed. This may require a re-upload or metadata correction.
• NOT_APPROVED: The media failed compliance review. This may require a re-upload or metadata correction.
• AVAILABLE: The media is available for display in A+ Content.
• PENDING_AMAZON: Amazon is the next actor. Applies when action is required from Amazon.
• PENDING_SELLING_PARTNER: The selling partner is the next actor. Applies when action is required from the seller.

📘

Note

The mediaUrl value is non-permanent. Re-retrieve the asset with getMedia rather than caching the URL indefinitely.

Step 3. Update a media asset

Call the updateMedia operation to update metadata on an existing asset, using mediaId to identify the target asset.

Each request updates either title or descriptions, but not both.

• To update a video-image pairing title, provide associatedMediaId as a query parameter and send title.
• To update video-level descriptions, omit associatedMediaId and send descriptions.
• To update a standalone image title, omit associatedMediaId and send title.

The response returns the full unified Media shape. When associatedMediaId is provided, relatedMedia contains only the specified pairing. When associatedMediaId is absent, relatedMedia contains all affected pairings.

📘

Note

Descriptions are upserted by locale. Only the locales you provide are modified; existing locales that are not in the request are preserved.