Working with seller products - AWS Marketplace Catalog API

Working with seller products

You can use the AWS Marketplace Catalog API to manage products that you sell in AWS Marketplace.

The following topics describe how to use the Catalog API to perform actions on your single-AMI and container-based products.

Note

This chapter assumes that you have access to the API and have completed any seller prerequisites, as described in the API access control topic.

To understand the basics of using the AWS Marketplace Catalog API, see AWS Marketplace Catalog API.

Finding your product ID (server products)

You must get the product ID for your product before you can modify it with AWS Marketplace Catalog API. There are two ways to find the product ID for server products:

  • Open the AWS Marketplace Management Portal and sign in with your seller account. From the Products menu, select Server products, then choose the product you are interested in. The product ID is listed in the Product Summary section.

  • Use the ListEntities action with the EntityType AmiProduct or ContainerProduct to get a list of products, including their product IDs, via the Catalog API. ListEntities requires that you do not include the version of the entity type (for example, AmiProduct@1.0).

Note

The product ID is only available after your product has been published and is visible to at least yourself in AWS Marketplace. When you first create your product, it can take several days to be reviewed and fully created. During this time, it will not have a product ID available.

Change set status and errors

Making changes to seller products in the AWS Marketplace Catalog API involves creating change sets that describe the changes you want to make, and then using the StartChangeSet action to start the changes. The changes from the request can take minutes to hours or longer to complete, depending on the request. The response to this request looks like the following.

{ "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef" }

The change request is added to a queue and processed, including scanning the files and information to ensure that it meets the AWS Marketplace guidelines for products. Depending on the change requests, this process can take a few minutes to days. You can check the status of the request through the AWS Marketplace Management Portal, or in the Catalog API with the DescribeChangeSet action. For more information about change sets, see Working with change sets.

To check the status of your request, use the DescribeChangeSet action.

POST /DescribeChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSetID": "example123456789012abcdef" }

The result of this call looks like the following (in this case, for adding a new version to a container product).

{ "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef", "ChangeSetName": "Submitted by 123456789012", "StartTime": "2020-10-27T22:21:26Z", "EndTime": "2020-10-27T22:32:19Z", "Status": "SUCCEEDED", "ChangeSet": [ { "ChangeType": "AddDeliveryOptions", "Entity": { "Type": "ContainerProduct@1.0", "Identifier": "example-1234-abcd-56ef-abcdef12345678@4" }, "ErrorDetailList": [] } ] }

The Status field shows the current status of the request, in this case, SUCCEEDED.

If there are failures, the result can include two types of errors. For most errors, the error message is included directly. However, errors found while scanning the product for security vulnerabilities instead include a URL to a file that lists all of the errors found, in the ErrorMessage field. Errors found while scanning have the ErrorCode "SCAN_ERROR".

{ "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef", "ChangeSetName": "Submitted by 123456789012", "StartTime": "2020-10-27T22:21:26Z", "EndTime": "2020-10-27T22:32:19Z", "Status": "FAILED", "FailureDescription": "Change set preparation has failed. For details see 'ErrorDetailList'.", "ChangeSet": [ { "ChangeType": "AddDeliveryOptions", "Entity": { "Type": "ContainerProduct@1.0", "Identifier": "example-1234-abcd-56ef-abcdef12345678@4" }, "ErrorDetailList": [ { "ErrorCode": "DUPLICATE_VERSION_TITLE", "ErrorMessage": "The version title must be different from any other version titles of this product." }, { "ErrorCode": "SCAN_ERROR", "ErrorMessage": "https://123sample456.cloudfront.net/example-1234-abcd-5678-abcdef12345678/1234abcdef567890" } ] } ] }

In this example, there is one error directly reported (DUPLICATE_VERSION_TITLE). The other error has a file with error messages (a single SCAN_ERROR can have multiple found errors in the file that is linked).

Note

The link returned in the ErrorMessage is valid for 60 days.