# Using the AWS Marketplace API as a seller
The following sections provide information on how to use the API as a seller.
**Topics**
+ [Work with seller products](work-with-seller-products.md)
+ [Work with offers using the AWS Marketplace APIs](work-with-offers.md)
+ [Work with multi-product solutions](work-with-multi-product-solutions.md)
+ [Build interfaces with catalog data](build-interfaces-with-catalog-data.md)
# Work with seller products
You can use the AWS Marketplace Catalog API to automate tasks for working with seller products. This includes the ability to create, update, view, list, and sort products. This enables you to automate product management. For example, you can provide self-service publishing capabilities on the AWS Marketplace Management Portal.
A *product* is a unit or resource that you intend to sell in AWS Marketplace, often referred to as a base product. Buyers can't consume a base product until you add product information, deployment attributes, and billing information.
A *product* describes the product information, software deployment attributes, and billing mechanism of the listing that you intend to sell. The *product* must be paired with an *offer* to become a transactable unit that you can sell and buyers can use in AWS Marketplace.
You can also use the AWS Marketplace Catalog API to:
+ [Work with private offers using the AWS Marketplace APIs](work-with-private-offers.md)
+ [Work with resale authorizations using the AWS Marketplace APIs](work-with-resale-authorizations.md)
+ [Work with channel partner private offers using the AWS Marketplace APIs](work-with-cppos.md)
Each product type has a different product entity. An *entity* can be a product or an offer on AWS Marketplace. The following product types and entities are supported:
| Product type | Entity |
| --- | --- |
| Amazon Machine Image (AMI) products | AmiProduct@1.0 |
| Container products | ContainerProduct@1.0 |
| Software as a service (SaaS) products | SaaSProduct@1.0 |
| Machine learning (ML) products | MachineLearningProduct@1.0 |
**Note**
Single-AMI with CloudFormation product types, AWS Data Exchange data products, and professional services products are not supported.
The following topics assume you have access to the API and have completed any seller prerequisites, as described in [Access control for the AWS Marketplace Catalog API](catalog-api-access-control.md).
See the following resources:
+ To understand the basics of using the AWS Marketplace Catalog API, see [Welcome to the AWS Marketplace API Reference](welcome.md).
+ For end-to-end labs with working code examples, see [Manage products with API](https://catalog.workshops.aws/mpseller/en-US/manage-products-with-api) in the *AWS Marketplace seller workshop*.
+ For code examples of API requests, see [Python](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/python/src/catalog_api/products) and [Java](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/java/resources/changeSets/products) examples in *AWS Samples* on GitHub.
The following topics describe how to use the Catalog API to perform actions on your single-AMI products, container-based products, or SaaS products.
**Topics**
+ [Create a product](#create-product)
+ [Update product details](#update-information)
+ [Add pricing dimensions](#add-dimensions)
+ [Update pricing dimensions](#update-dimensions)
+ [Restrict pricing dimensions](#restrict-dimensions)
+ [Update targeting configuration](#update-targeting)
+ [Update product visibility](#update-visibility)
+ [Publish a product](#release-product)
+ [Find your product ID](#seller-product-id)
+ [Change set status and errors](#seller-product-change-set-errors)
+ [Work with AMI-based products](work-with-single-ami-products.md)
+ [Work with EC2 Image Builder component products](work-with-ec2-image-builder-products.md)
+ [Work with container-based products using the AWS Marketplace APIs](work-with-container-products.md)
+ [Work with SaaS products using the AWS Marketplace APIs](work-with-saas-products.md)
+ [Work with machine learning products using AWS Marketplace APIs](work-with-ml-products.md)
## Create a product
**Note**
This change type is only needed when you intend to create a brand new product entity in the AWS Marketplace catalog. It is not needed when updating existing products.
You can use the Catalog API to create an AMI, container, machine learning, or SaaS product document with identifiers (product code and product ID) in AWS Marketplace.
You create a product in `Draft` state by calling the `StartChangeSet` API operation with the `CreateProduct` change type.
If your request is processed successfully, then AWS Marketplace Catalog API generates a product in `Draft` state for you. This is an incomplete product and isn’t visible to buyers in AWS Marketplace.
You then use `Update` change types to complete the create product process: [UpdateInformation](#update-information), [UpdateDimensions](#update-dimensions), [UpdateTargeting](#update-targeting), and [UpdateVisibility](#update-visibility).
After the product is completed, you can use the [ReleaseProduct](#release-product) change type to complete the product creation process, and then release the offer. This process validates the entire product and moves the product to the `Limited` state.
**Note**
For more information about creating a product using the AWS Marketplace Management Portal, see the following topics in the *AWS Marketplace Seller Guide*:
[Create your single-AMI product](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#ami-create-product)
You cannot update the AMI for the version. If you need to update the AMI, create a new version instead.
[Creating a container product](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#create-container-product)
[Creating a SaaS product](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-create-product.html)
[Creating a machine learning product](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-creating-your-listing.html)
If you use the AWS Marketplace Management Portal to create a product, the product will be in the `Staging` state.
To create a product in `Draft` state, call the `StartChangeSet` API operation with the `CreateProduct` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType":"CreateProduct",
"Entity":{
"Type": "SaaSProduct@1.0" // choose from ["AmiProduct@1.0", "ContainerProduct@1.0", "SaaSProduct@1.0", "MachineLearningProduct@1.0"]
},
"DetailsDocument": {
"ProductTitle": "Test product title set in CreateProduct"
}
}
]
}
```
Provide information for the fields to add the `CreateProduct` change type. This change type can take in `ProductTitle` attribute, subject to the same restrictions as that sent into `UpdateInformation` change type.
+ `Entity` (object) (required) – The named type of object being created.
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`, `ContainerProduct@1.0`, `MachineLearningProduct@1.0` or `SaaSProduct@1.0`. For more information, see [Identifier](catalog-apis.md#identifier).
+ `DetailsDocument` (object) (required) – It may be empty.
+ `ProductTitle` (optional) – The title for your product, max length is 72 characters. Note that you can also later set or update the product title via the `UpdateInformation` change type.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
When the request is complete (if the `Status` is `SUCCEEDED`), a new `ProductId` is generated.
**Synchronous Validations**
The following schema validations are specific to `CreateProduct` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| ProductTitle (string) | Max length: 72 | 400 |
**Asynchronous Errors**
The following errors are specific to `CreateProduct` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more details about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1INPUT | Inappropriate content '\$1InappropriateContent\$1' found in ProductTitle field. Provide ProductTitle with no inappropriate content. |
## Update product details
If you already have a product in AWS Marketplace, you can use the Catalog API to update the product details for an AMI, container, ML, or SaaS product.
**Note**
For more information about updating the product details using the AWS Marketplace Management Portal, see the following topics in the *AWS Marketplace Seller Guide*:
AMI-based product: [Update product information](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-updating-product)
Container-based product: [Creating or updating product information for your container product](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-product-updating-version)
SaaS-based product: [Update product information](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-settings.html#update-product-information)
Machine learning product: [Updating product information](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-update-product.html)
To update product details, call the `StartChangeSet` API operation with the `UpdateInformation` change type and the details that you want to change, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateInformation",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "AmiProduct@1.0"
},
"DetailsDocument":
{
"ProductTitle": "My Product Title",
"ShortDescription": "My product short description.",
"LongDescription": "My product longer description.",
"Sku": "123example456",
"LogoUrl": "https://awsmp-logos.s3.amazonaws.com/ca60b754fe05a24257176cdbf31c4e0d",
"VideoUrls":
[
"https://example.com/my-video"
],
"Highlights":
[
"123example45"
],
"AdditionalResources":
[
{
"Text": "123example456",
"Url": "https://example.com/some-link"
}
],
"SupportDescription": "Need help? Contact our experts at support@example.com \n\nYour purchase includes 24x7 support.",
"Categories":
[
"Operating Systems",
"Network Infrastructure",
"Application Development"
],
"SearchKeywords":
[
"123example456"
]
}
}
]
}
```
Provide information for the fields to add the `UpdateInformation` change type:
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`, `ContainerProduct@1.0`, `MachineLearningProduct@1.0`, or `SaaSProduct@1.0`.
+ `DetailsDocument` (object) (required) – The details of the request including the information that you want to update for your product. Each field is optional, but you must include at least one change to update.
+ `ProductTitle` (string) – The name of the product to be displayed to buyers.
+ `ShortDescription` (string) – The description of key aspects of the product to be displayed to buyers. This is usually 2–3 sentences.
+ `LongDescription` (string) – The longer description of your product to be displayed to buyers. This is usually 1–3 paragraphs.
+ `Sku` (string or null) – The free-form string that you define as a reference for your own use. Use `null` to unset this field.
+ `LogoUrl` (string) – The URL to an image in a publicly accessible Amazon Simple Storage Service (Amazon S3) bucket. For more information, see [Company and product logo requirements](https://docs.aws.amazon.com/marketplace/latest/userguide/product-submission.html#seller-and-product-logos).
+ `VideoUrls` (array of strings) – The list of URLs to publicly available, externally hosted videos to be provided as a reference to buyers in your product information.
**Note**
Currently, AWS Marketplace supports one URL in the array.
+ `Highlights` (array of strings) – The list of short callouts for key product features.
+ `AdditionalResources` (array of structures) – The list of references to additional resources to learn about your product. Each reference is made up of a text name and a URL:
+ `Text` (string) – The name or title of the resource.
+ `Url` (string) – The URL to a resource that might be helpful for a buyer to understand your product.
+ `SupportDescription` (string) – The details about your support offering for your product.
+ `Categories` (array of strings) – The list of AWS Marketplace defined product categories that describe your product. For more information, see [Product categories](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-product-categories.html) in the *AWS Marketplace Buyer Guide*.
+ `SearchKeywords` (array of strings) – The list of keywords for your product to enhance the search experience. Seller name, product name, and product categories are automatically included in search keywords and don’t need to be repeated here.
**Note**
When you are initially populating product information (metadata) for a `Draft` product, you will need to supply all of the following in the `DetailsDocument` object of `UpdateInformation` change type: `ProductTitle`, `ShortDescription`, `LongDescription`, `LogoUrl`, `Highlights`, `AdditionalResources`, `SupportDescription`, `Categories`, and `SearchKeywords`.
The `ProductTitle` can be omitted if it has already been provided during `CreateProduct` change type. However, when you are updating existing fields on the product, you can include only the attributes that need to be changed in the `DetailsDocument` object of the `UpdateInformation` change type.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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.
To check request status, use the AWS Marketplace Management Portal or call the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API.
**Synchronous Validations**
The following schema validations are specific to `UpdateInformation` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| String (general) | No control characters "\$1\$1x00-\$1\$1x08\$1\$1x0B-\$1\$1x1F" | 400 |
| ProductTitle (string) | Max length: 72 Required | 400 |
| ShortDescription (string) | Max length: 1000 Required | 400 |
| LongDescription (string) | Max length: 5000 Required | 400 |
| Sku (string) | Max length: 100 Optional | 400 |
| LogoUrl (string) | URL pattern: ^https://(www\$1.)?[-a-zA-Z0- 9@.]\$11,256\$1\$1.[a-zA-Z0-9()]\$12,63\$1\$1b([-a-zA- Z0-9@\$1./]\$1) Required | 400 |
| VideoUrls (array of strings) | URL pattern: https://(www\$1\$1.)?[-a-zA-Z0- 9@.\$1]\$11,256\$1\$1\$1.[a-zA-Z0-9()]\$12,63\$1\$1\$1b([-a-zA-Z0-9@\$1\$1.\$1/] Optional | 400 |
| Highlights (array of strings) | Required: Min 1 - Max 3 | 400 |
| AdditionalResources (array of structures) | Max length: 500 Optional | 400 |
| SupportDescription (string) | Max length: 2000Required | 400 |
| Categories (array of strings) | Min 1 - Max 3 Required | 400 |
| SearchKeywords (array of strings) | Min 1 - Max 15 Max 50 chars for each itemRequired | 400 |
**Asynchronous Errors**
The following errors are specific to `UpdateInformation` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| MISSING\$1DATA | No data provided to perform an update. Provide data for at least 1 field of the product. |
| INVALID\$1INPUT | Provide LogoUrl. |
| INVALID\$1INPUT | Provide ProductTitle. |
| INVALID\$1INPUT | Provide ShortDescription. |
| INVALID\$1INPUT | Provide LongDescription. |
| INVALID\$1INPUT | Provide SupportDescription. |
| INVALID\$1INPUT | Provide at least one search keyword. |
| INVALID\$1INPUT | Provide at least one highlight. |
| INVALID\$1INPUT | Provide between 1 and 3 product categories. |
| INVALID\$1INPUT | Inappropriate content '\$1InappropriateContent\$1' found in ProductTitle field. Provide ProductTitle with no inappropriate content. |
| INVALID\$1INPUT | Inappropriate content '\$1InappropriateContent\$1' found in ShortDescription field. Provide ShortDescription with no inappropriate content. |
| INVALID\$1INPUT | Inappropriate content '\$1InappropriateContent\$1' found in LongDescription field. Provide LongDescription with no inappropriate content. |
| INVALID\$1INPUT | Inappropriate content '\$1InappropriateContent\$1' found in SupportDescription field. Provide SupportDescription with no inappropriate content. |
| INVALID\$1INPUT | Invalid ProductTitle field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid ShortDescription field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid LongDescription field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid SupportDescription field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid ProductTitle field. Remove unsupported characters [UnsupportedCharacters]. |
| INVALID\$1INPUT | Invalid ShortDescription field. Remove unsupported characters [UnsupportedCharacters]. |
| INVALID\$1INPUT | Invalid LongDescription field. Remove unsupported characters [UnsupportedCharacters]. |
| INVALID\$1INPUT | Invalid SupportDescription field. Remove unsupported characters [UnsupportedCharacters]. |
| INVALID\$1INPUT | Search keywords must be no more than 250 combined characters. |
| INVALID\$1INPUT | The input for this change type could not be read. Submit a properly formatted input. |
| INVALID\$1ADDITIONAL\$1RESOURCES | Invalid URLs in AdditionalResources: [InvalidAdditionalResourcesUrls] Provide valid URLs. |
| INVALID\$1CATEGORY\$1NAMES | Provide valid category names supported by AWS Marketplace. |
| InvalidImageProperties | Validation errors found: The file is not image type. Supported image types: [png\$1jpg\$1gif]. |
| EXPLICIT\$1CONTENT | Explicit content: '\$1ExplicitContent\$1' detected. Provide media with no explicit content. |
| INVALID\$1MEDIA | Invalid URL: \$1MediaUrl\$1 Provide a new URL for media stored in S3. |
| INVALID\$1MEDIA | Invalid URL: \$1MediaUrl\$1 Provide a valid URL that does not exceed 2048 characters. |
| INVALID\$1MEDIA | Location provided not accessible: \$1MediaUrl\$1 Provide an accessible URL for media stored in S3. |
| INVALID\$1MEDIA | There was an issue copying the media from S3. Image size exceeds 5 MB. Provide an image that is under 5 MB. |
| INVALID\$1MEDIA | Malware detected in media. Please resubmit media without malware. |
| TOO\$1MANY\$1MEDIA | Provide no more than 15 media items. |
| DUPLICATE\$1MEDIA | Duplicate media is not allowed for a product. Please provide media with no duplicates. |
## Add pricing dimensions
You can use the [AWS Marketplace Catalog API](API_Operations_AWS_Marketplace_Catalog_Service.md) to add billable pricing dimensions that enable you to charge users for AMI, container, or SaaS products.
A *pricing dimension* is a unit of measure that sellers define for charging buyers. Sellers must set up this information to bill buyers for using the product, whether it's a usage-based or contract-based pricing model. The type of dimension depends on the product's pricing model.
**Note**
For SaaS products with Free pricing model, you must create at least one dimension with UsageBasedPricingTerm or ConfigurableUpfrontPricingTerm, and all dimensions must be priced at \$10.00. This requirement is unique to SaaS products and does not apply to AMI, container, or machine learning products.
**Note**
New pricing dimensions have the following impacts on SaaS buyers:
For buyers with agreements created from public offers, you can report consumption on the new dimensions even though they did not exist in the offer when the agreement was created.
For buyers with agreements created from private offers, you can't report consumption on the new dimensions because they did not exist in the private offer when the agreement was created. Calls to the [BatchMeterUsage](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_BatchMeterUsage.html) API will succeed, but the buyer will not be billed, so you must keep track of which buyer can and cannot be billed for any new dimensions. You can also use the [GetAgreementTerms](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-agreements_GetAgreementTerms.html) API to see the dimensions included in each buyer agreement.
To report consumption on a new dimension and bill the buyer, you must [extend a replacement offer](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-upgrades-and-renewals.html#private-offers-upgrades-and-renewals-supported-products) that includes the dimension, and the buyer must accept the offer.
For more information about product pricing, see the following topics in the *AWS Marketplace Seller Guide*:
+ [AMI product pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/pricing-ami-products.html)
+ [Container products pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/pricing-container-products.html)
+ [SaaS product pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-pricing-models.html)
+ [Machine learning product pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/machine-learning-pricing.html)
For more information about adding pricing dimensions using the AWS Marketplace Management Portal, see the following topics in the *AWS Marketplace Seller Guide*:
+ AMI-based products: [Update pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-update-product-pricing).
+ Container-based products: [Adding a pricing dimension](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-add-pricing-dimensions).
+ SaaS-based products: [Add pricing dimensions](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-settings.html#saas-add-pricing-dimensions).
+ ML products: Not supported. Machine learning products have fixed pricing dimensions. However, you can [Update pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-update-product-pricing).
To add pricing dimensions, call the `StartChangeSet` API with the `AddDimensions` change type, as shown in the following example.
**Note**
After submitting the first `AddDimensions` change type with dimensions specifying a type of pricing model—usage, contract, or contract with consumption— you must work with the AWS Marketplace Seller Operations team. They help you add a dimension with types that are outside of the original pricing model.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddDimensions",
"DetailsDocument":
[
{
"Description": "Description of the dimension",
"Key": "UniqueApiKey",
"Unit": "HostHrs",
"Name": "First Dimension",
"Types":
[
"ExternallyMetered"
]
}
],
"Entity":
{
"Identifier": "prod-example12345",
"Type": "SaaSProduct@1.0"
}
}
]
}
```
Provide the following fields for the `AddDimensions` change type.
+ `DetailsDocument` (array of objects) (required) – Details of the request.
+ `Description` (string) (required) – Full details of the dimension that will be the long description on the buyer’s viewing page.
+ `Key` (string) (required) – Enter in the facet that will be used for defining the rates in the offer. Also, enter the dimensions published to the AWS Marketplace Metering Service (MMS) if the dimension can’t be metered externally. After the dimension is created, this can’t be changed.
+ `Units` (string) (required) – The unit type for the dimension. Possible units are Users, Hosts, GB, MB, TB, Gbps, Mbps, Requests, Units, UserHrs, UnitHrs, Units, HostHrs, TierHrs, and TaskHrs.
+ `Name` (string) (required) – The display name for the dimension on the website and customer's bill.
+ `Types` (array of strings) (required) (also known as **Tags**) – These indicate whether the dimension covers metering, entitlement, or support for external metering. This is not changeable after the dimension is created.
+
+ `Metered` – Indicates that Commerce Platform usage types should be created to allow metering to occur for this dimension.
+ `ExternallyMetered` – Indicates that AWS Marketplace Metering Service (MMS) dimensions should be created during publishing to allow sellers to meter through the AWS SDK.
+ `Entitled` – Indicates that entitlements can be granted for the dimension during the product or offer publishing.
The following table lists the supported combinations of pricing dimensions and products.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-seller-products.html)
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0` or `SaaSProduct@1.0`.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This includes validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
**Synchronous Validations**
The following schema validations are specific to `AddDimensions` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Description | Max length: 1000 Required | 400 |
| Key | Max length: 100 Pattern: [A-Za-z0-9\$1.-]\$1\$1 Required | 400 |
| Dimension Units | Max length: 20 Required | 400 |
| Name | Max length: 500 Required | 400 |
| Type (tag) | Required: Min 1 - Max 3 Inputs: Entitled, Metered, ExternallyMetered Required | 400 |
**Asynchronous Errors**
The following errors are specific to `AddDimensions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| MISSING\$1DATA | No data provided to perform an update. Provide data for at least 1 dimension. |
| INVALID\$1DIMENSION | Provide no more than 200 dimensions. |
| INVALID\$1DIMENSION | Can't add duplicate dimensions. |
| INVALID\$1DIMENSION | Dimension can't be added in current state '%s'. States that support dimension updates are %s. |
| INVALID\$1DIMENSION | Can't add dimension. The field '%s' has duplicate values '%s' in other dimensions. |
| INVALID\$1DIMENSION | Provide non-empty fields (Key, Unit, Name, Types) for each dimension. |
| IINVALID\$1TYPE | Remove invalid type '%s'. Valid types are ["Metered", "Entitled", "ExternallyMetered"]. |
| INVALID\$1UNIT | Remove invalid Unit '%s'. Valid units are ["GB", "Gbps", "HostHrs", "Hosts", "MB", "Mbps", "Requests", "TaskHrs", "TB", "TierHrs", "UnitHrs", "Units", "UserHrs", "Users"]. |
| INVALID\$1INPUT | Inappropriate content '%s' found in %s field. Provide %s with no inappropriate content. |
| INVALID\$1INPUT | Invalid '%s' field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid '%s' field. Remove unsupported characters %s. |
| INVALID\$1DIMENSION | Remove invalid dimension type combination %s. Allowed values are %s. |
| INVALID\$1DIMENSION | Remove invalid dimension key '%s' for Metered dimension. |
| INVALID\$1DIMENSION | Dimension named '%s' for productCode '%s' did not pass AWS Marketplace Metering Service validation %s. |
| INVALID\$1DIMENSION | Dimension named '%s' for productCode '%s' has no metering record present in Metering Service. The product has either never been launched for testing or is misconfigured and does not make the appropriate calls to the AWS Marketplace Metering Service. |
## Update pricing dimensions
You can use the Catalog API to update existing pricing dimensions of an AMI, container, or SaaS product in AWS Marketplace.
Each dimension is uniquely identified by the dimension key and dimension types to perform the update. Updating a dimension doesn’t affect any active offer or customers that the original dimension had created.
**Note**
For more information about updating pricing dimensions using the AWS Marketplace Management Portal, see the following topics in the *AWS Marketplace Seller Guide*:
AMI-based product: [Update pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-update-product-pricing)
Container-based product: [Updating dimension information](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-update-dimensions-information)
SaaS-based product: [Update pricing dimensions](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-settings.html#saas-update-dimension)
Machine learning product: [Update product pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-update-public-offer.html)
To update pricing dimensions, call the `StartChangeSet` API operation with the `UpdateDimensions` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateDimensions",
"DetailsDocument":
[
{
"Key": "UniqueApiKey",
"Types":
[
"ExternallyMetered"
],
"Name": "First Dimension",
"Description": "Description of the dimension"
}
],
"Entity":
{
"Identifier": "prod-example12345",
"Type": "SaaSProduct@1.0"
}
}
]
}
```
Use the following fields with the `UpdateDimensions` change type:
+ `DetailsDocument` (array of objects) (required) – Details of the request.
+ `Key` (string) (required) – Provide key of existing dimension from the product to change description and name on. For `UpdateDimension`, this field is only for identifying the dimension to be changed.
+ `Types` (array of strings) (required) (also known as **Tags**) – These indicate whether the dimension covers metering, entitlement, or support for external metering. This is not changeable after the dimension is created.
+ `Metered` – Indicates that Commerce Platform usage types should be created to allow metering to occur for this dimension.
+ `ExternallyMetered` – Indicates that AWS Marketplace Metering Service (MMS) dimensions should be created during publishing to allow sellers to meter through the AWS SDK.
+ `Entitled` – Indicates that entitlements can be granted for the dimension during product/offer publishing.
**Valid Pricing Dimension Types Combinations**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-seller-products.html)
+ `Description` (string) (optional – Full description of the dimension that will be the long description on the buyer's viewing page.
+ `Name` (string) optional – DIsplay name for the dimension on the website and customer's bill.
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0` or `SaaSProduct@1.0`.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
**Synchronous Validations**
The following schema validations are specific to `UpdateDimensions` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Description | Max length: 1000 Required | 400 |
| Key | Max length: 100 Pattern: [A-Za-z0-9\$1.-]\$1\$1 Required | 400 |
| Name | Max length: 5 Required | 400 |
| Types (tag) | Required: Min 1 - Max 3 Inputs: `Entitled`, `Metered`, `ExternallyMetered` Required | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateDimensions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1INPUT | Invalid '%s' field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid '%s' field. Remove unsupported characters %s. |
| INVALID\$1DIMENSION | Provide non-empty fields (Key, Types, Name and/or Description) for each dimension. |
| INVALID\$1DIMENSION | Cannot update dimension. The field Name has duplicate values '%s' in other dimensions. |
| INVALID\$1DIMENSION | Cannot update same dimension with key '%s' and types '%s' multiple times in the same request. |
| INVALID\$1DIMENSION | Cannot restrict dimension. The dimension key '%s' with types '%s' does not exist. |
| INVALID\$1DIMENSION | Cannot update dimension. The dimension key '%s' is Metered. |
| INVALID\$1DIMENSION | Dimension cannot be updated for an already restricted dimension. |
## Restrict pricing dimensions
You can use the Catalog API to restrict existing pricing dimensions of an AMI or SaaS product in AWS Marketplace.
Each dimension is uniquely identified by the dimension key and dimension types to perform the update. Restricting a dimension doesn’t affect any active offer or customers that the original dimension had created.
To restrict pricing dimensions, call the `StartChangeSet` API with the `RestrictDimensions` change type.
**Note**
Pricing dimension restrictions are only available while the product is in draft state. Changes are not permitted once the product moves to limited or public state.
The following example shows how to restrict the `Entitled` dimension for a SaaS product.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "RestrictDimensions",
"DetailsDocument":
[
{
"Key": "UniqueApiKey",
"Types": ["Entitled"]
}
],
"Entity":
{
"Identifier": "prod-example12345",
"Type": "SaaSProduct@1.0"
}
}
]
}
```
Use the following fields with the `RestrictDimensions` change type:
+ `DetailsDocument` (array of objects) (required) – Details of the request.
+ `Key` (string) (required) – Provide key of existing dimension from the product to change description and name on. For `RestrictDimensions`, this field is only for identifying the dimension to be changed.
+ `Types` (array of strings) (required) (also known as **Tags**) – These indicate whether the dimension covers metering, entitlement, or support for external metering. This is not changeable after the dimension is created.
+ `["ExternallyMetered", "Entitled"]` – You can only combine these types for SaaS Contract with Consumption pricing where dimensions can be prepaid or metered.
+ `["Metered"]` – For hourly pricing dimensions of AMI products. Indicates that Commerce Platform usage types should be created to allow metering to take place for this dimension.
+ `["ExternallyMetered"]` – For flexible consumption pricing dimensions (also known as custom metering) of AMI, container, and SaaS products. Indicates that AWS Marketplace Metering Service (MMS) dimensions should be created during publishing to allow sellers to meter through the AWS SDK.
+ `["Entitled"]` – For contract pricing dimensions of SaaS Contracts and professional services products. This tag grants rights to use a software or service, sets start and end dates for the usage, and grants usage-discount rights for AMI annual products. Each entitlement is identified by a Dimension Key in AWS Marketplace Entitlement Service for creating and updating the entitlements. The key indicates that entitlements can be granted for the dimension during product and offer publishing.
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on your product's delivery method (product type): `AmiProduct@1.0` or `SaaSProduct@1.0`.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or by calling the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API.
**Synchronous Validations**
The following schema validations are specific to `RestrictDimensions` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Description | Max length: 1000 Required | 400 |
| Key | Max length: 100 Pattern: [A-Za-z0-9\$1.-]\$1\$1 Required | 400 |
| Name | Max length: 5 Required | 400 |
| Types (tag) | Required: Min 1 - Max 3 Inputs: `Entitled`, `Metered`, `ExternallyMetered` Required | 400 |
**Asynchronous Errors**
The following errors are specific to `RestrictDimensions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` while a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1INPUT | Invalid '%s' field. Remove spaces before trademark symbol. |
| INVALID\$1INPUT | Invalid '%s' field. Remove unsupported characters %s. |
| INVALID\$1DIMENSION | The dimension key '%s' with types '%s' was already restricted |
| INVALID\$1DIMENSION | Cannot restrict dimension. The dimension key '%s' with types '%s' does not exist |
| INVALID\$1DIMENSION | Cannot restrict duplicate dimensions. |
| INVALID\$1DIMENSION | All Entitled dimensions cannot be restricted. There must be at least one active Entitled dimension. |
| INVALID\$1DIMENSION | The dimension key '%s' with types '%s' is associated with another dimension of different types '%s'. Both dimensions of the same key must be restricted at the same time to be valid. |
## Update targeting configuration
You can use the Catalog API to add AWS account IDs that are allowed to view the AMI, container, ML, or SaaS product in AWS Marketplace before it’s moved to a `Public` state by calling the `UpdateTargeting` change type.
Managed Catalog Operations (MCO) accounts are automatically added to the allowed accounts list when new products are created. These MCO accounts are visible to sellers in the AWS Marketplace Management Portal (AMMP) when viewing allowed accounts, and in the `Targeting` section of the `DescribeEntity` API response.
**Note**
For more information about adding AWS account IDs using the AWS Marketplace Management Portal, see the following topics in the *AWS Marketplace Seller Guide*:
AMI-based product: [Update the allowlist (preview accounts)](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-updating-allowlist)
Container-based product: [Updating the allowlist of AWS account IDs](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-update-allowlist)
SaaS-based product: [Updating the allowlist of AWS account IDs](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-settings.html#update-allowlist)
Machine learning product: [Updating the allowlist](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-update-allowlist.html)
To add AWS account IDs that are allowed to view the AMI, container, ML, or SaaS product, call the `StartChangeSet` API operation with the `UpdateTargeting` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateTargeting",
"Entity":
{
"Type": "SaaSProduct@1.0",
"Identifier": "prod-example12345"
},
"DetailsDocument":
{
"PositiveTargeting":
{
"BuyerAccounts":
[
"1112223334444"
]
}
}
}
]
}
```
Use the following the fields with the `UpdateTargeting` change type.
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`, `MachineLearningProduct@1.0`, or `SaaSProduct@1.0`.
+ `DetailsDocument` (object) (required) – The details required to run the ChangeSet.
+ `PositiveTargeting` (object) (optional) – Positive targeting defines the criteria which any buyer's profile should fulfill in order to be allowed to access the offer. This field is optional, but at least one targeting option should be provided when this field is present.
+ `BuyerAccounts` (array of strings) (optional) – List as an option to allow targeting based on AWS accounts (also known as, Private Offer). If the intention is to not target the offer to an AWS account, this field should be omitted.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
To check request status, use the AWS Marketplace Management Portal or call the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API.
When the request is complete (if the `Status` is `SUCCEEDED`), a new `ProductId` is generated.
**Synchronous Validations**
The following schema validations are specific to `UpdateTargeting` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Type of targeting | Valid current visibility states | BuyerAccounts (input) | Check |
| --- | --- | --- | --- |
| Positive | Public, Limited, or Draft | Array of 12-digit AWS account ID strings. Min size: 0. Max size: 5000. | The input must be different from the current document targeted accounts.Input must be in valid AWS accounts. |
**Asynchronous Errors**
The following errors are specific to `DescribeChangeSet` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1PRODUCT\$1VISIBILITY | Use an existing Public, Limited or Draft product. |
| INVALID\$1AWS\$1ACCOUNT\$1IDS | Provide valid AWS account IDs. AWS accounts not found: [x, y, z]. |
| ValidationException | Professional services products do not have allowlists. Unlike other product types, professional services products in the limited state can be extended to any buyer without requiring an allowlist. |
## Update product visibility
You can use the Catalog API to update the visibility (also known as lifecycle state) of an AMI, container, ML, or SaaS product in AWS Marketplace.
**Note**
For more information updating product visibility using the AWS Marketplace Management Portal, see the following topics in the *AWS Marketplace Seller Guide*:
AMI-based product: [Update product visibility](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#ami-update-self-service-visibility)
Container-based product: [Updating product visibility](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-product-visibility)
SaaS-based product: [Update product visibility](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-settings.html#saas-update-visibility)
Machine learning product: [Updating product visibility](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-update-visibility.html)
Allowed target lifecycle states are `Limited`, `Public`, or `Restricted`.
`Limited`
The product is complete and has successfully completed the `ReleaseProduct` `ChangeType`. Sellers can view details of the product in this state. The product is not public. However, sellers can target specific buyers to allow to preview the product.
`Public`
The product is visible in AWS Marketplace. Buyers can view and subscribe to the product.
`Restricted`
The product is no longer visible to the public and doesn’t accept new subscribers. Existing subscribers can continue using this product until their subscription expires.
**Note**
The `UpdateVisibility` change type requires a manual review from the AWS Marketplace Seller Operations team, which results in a longer execution time. Use `UpdateVisibility` separately in its own change set.
To update your product's visibility, call the `StartChangeSet` API operation with the `UpdateVisibility` change type, as shown in the following example.
**Request Syntax**
For when `TargetVisibility` is `Public` or `Limited`.
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateVisibility",
"Entity":
{
"Type": "SaaSProduct@1.0",
"Identifier": "prod-example12345"
},
"DetailsDocument":
{
"TargetVisibility": "Public"
}
}
]
}
```
For when `TargetVisibility` is `Restricted`.
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateVisibility",
"Entity":
{
"Type": "SaaSProduct@1.0",
"Identifier": "prod-example12345"
},
"DetailsDocument":
{
"TargetVisibility": "Restricted",
"ReplacementProductId": "prod-example54321"
}
}
]
}
```
Provide information for the fields to add the `UpdateVisibility` change type.
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`, `SaaSProduct@1.0`, `ContainerProduct@1.0`, `MachineLearningProduct@1.0`. For more information, see [Identifier](catalog-apis.md#identifier).
+ `DetailsDocument` (object) (required) – The details required to run the `ChangeSet`.
+
+ `TargetVisibility` – The intended new visibility of the product.
Possible values: `Public`, `Limited`, and `Restricted`
+ `ReplacementProductId` (string) (optional) – Replacement product ID for the product to be `Restricted`. Used to notify current subscribers about the product restriction.
Only accepts `Restricted` for `TargetVisibility`.
**Synchronous Validations**
The following schema validations are specific to `UpdateVisibility` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Type of targeting | Valid current states | ReplacementProductId (input) | Validation checks |
| --- | --- | --- | --- |
| Public | Limited and Restricted | Not allowed | Valid current state |
| Limited | Public and Restricted | Not allowed | Valid current state |
| Restricted | Public and Limited | String (Optional) | ReplacementProductId must belong to an existing Limited or Public product. |
After triggering this change type, it can take up to 37 days to complete. This includes the time the AWS Marketplace Seller Operations Team needs to review, audit, and approve. When restricting a product, you have 24 hours to change your mind, by calling `CancelChangeSet`, before the AWS Marketplace Seller Operations Team begins auditing. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_CancelChangeSet.html](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_CancelChangeSet.html).
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
When the request is complete (if the `Status` is `SUCCEEDED`), a new `ProductId` is generated.
**Asynchronous Errors**
The following errors are specific to `UpdateVisibility` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1PRODUCT\$1STATE | Use an existing Public, Limited, or Restricted product. |
| INVALID\$1TARGET\$1VISIBILITY | Provide a valid target visibility state: Public, Limited, or Restricted. |
| EMPTY\$1TARGET\$1VISIBILITY | Provide a valid target visibility state: Public, Limited, or Restricted. |
| INVALID\$1REPLACEMENT\$1PRODUCT\$1ID | Use an existing Public or Limited product as replacement. |
| INVALID\$1REPLACEMENT\$1PRODUCT\$1ID | Replacement product ID is only valid when restricting a product. |
| AUDIT\$1ERROR | Varies based on MCO manual review. |
| MISSING\$1SELLER\$1PROFILE\$1INFORMATION | Before you can update your product to Public, you must add a public profile to your seller account. |
## Publish a product
You can use the Catalog API to publish a `Draft` AMI, container, ML, or SaaS product into `Limited` state in AWS Marketplace.
**Note**
For `AmiProduct@1.0` and `SaaSProduct@1.0`, the `ReleaseProduct` change type must be accompanied by `ReleaseOffer` change type on the corresponding draft public `Offer@1.0` entity created for this product.
To publish a product, call the `StartChangeSet` API operation with the `ReleaseProduct` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "ReleaseProduct",
"Entity":
{
"Type": "SaaSProduct@1.0",
"Identifier": "prod-example12345"
},
"DetailsDocument": {}
}
]
}
```
Provide information for the fields to add to the `ReleaseProduct` change type. This change type does not take any parameter payload.
+ `Entity` (object) (required) – The named type of entity being created.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`, `SaaSProduct@1.0`, `ContainerProduct@1.0`, `MachineLearningProduct@1.0`. For more information, see [Identifier](catalog-apis.md#identifier).
+ `DetailsDocument` (object) (required) - Must be an empty object. The change type `ReleaseProduct` doesn't accept any details.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
When the request is complete (if the `Status` is `SUCCEEDED`), a new `ProductId` is generated.
**Asynchronous Errors**
The following errors are specific to `ReleaseProduct` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| VALIDATION\$1FAILED | Provide Description information. |
| VALIDATION\$1FAILED | Provide Versions information. |
| VALIDATION\$1FAILED | Provide Dimensions information. |
| VALIDATION\$1FAILED | Provide Description\$1PromotionalResources\$1SupportInformation information. |
## Find your product ID
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 [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_ListEntities.html](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_ListEntities.html) action with the `EntityType` **AmiProduct** or **ContainerProduct**, **SaaSProduct**, **MachineLearningProduct**,or **DataProduct** 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.
The following topics explain how to find a product by filtering on entity id, product title, last modified date, or visibility.
**Topics**
+ [Find a product based on product title](#find-product-using-title)
+ [Find a product based on last modified date](#find-product-using-last-mod-date)
+ [Find a product based on product visibility](#find-product-using-visibility)
+ [Find a product based on product title, last modified date, and product visibility](#find-product-using-all)
+ [Get additional details about a product](#get-additional-details)
### Find a product based on product title
**Request**
```
POST /ListEntities HTTP/1.1
Content-Type: application/json
{
"Catalog": "AWSMarketplace",
"EntityType": "AmiProduct",
"MaxResults": 10,
"EntityTypeFilters": {
"AmiProductFilters": {
"ProductTitle": {
"WildCardValue": "XYZ"
}
}
}
}
```
**Response**
```
HTTP/1.1 200
Content-type: application/json
{
"EntitySummaryList": [
{
"EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
"EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
"EntityType": "AmiProduct",
"LastModifiedDate": "2018-02-27T13:45:22Z",
"AmiProductSummary": {
"ProductTitle": "ABC-XYZ-123",
"Visibility": "Public"
}
}
],
"NextToken": ""
}
```
### Find a product based on last modified date
**Request**
```
POST /ListEntities HTTP/1.1
Content-Type: application/json
{
"Catalog": "AWSMarketplace",
"EntityType": "AmiProduct",
"MaxResults": 10,
"EntityTypeFilters": {
"AmiProductFilters": {
"LastModifiedDate": {
"DateRange": {
"BeforeValue": "2018-03-27T13:45:22Z",
"AfterValue": "2018-01-27T13:45:22Z"
}
}
}
}
}
```
**Response**
```
HTTP/1.1 200
Content-type: application/json
{
"EntitySummaryList": [
{
"EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
"EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
"EntityType": "AmiProduct",
"LastModifiedDate": "2018-02-27T13:45:22Z",
"AmiProductSummary": {
"ProductTitle": "ABC-XYZ-123",
"Visibility": "Public"
}
}
],
"NextToken": ""
}
```
### Find a product based on product visibility
**Request**
```
POST /ListEntities HTTP/1.1
Content-Type: application/json
{
"Catalog": "AWSMarketplace",
"EntityType": "AmiProduct",
"MaxResults": 10,
"EntityTypeFilters": {
"AmiProductFilters": {
"Visibility": {
"ValueList": [
"Public"
]
}
}
}
}
```
**Response**
```
HTTP/1.1 200
Content-type: application/json
{
"EntitySummaryList": [
{
"EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
"EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
"EntityType": "AmiProduct",
"LastModifiedDate": "2018-02-27T13:45:22Z",
"AmiProductSummary": {
"ProductTitle": "ABC-XYZ-123",
"Visibility": "Public"
}
}
],
"NextToken": ""
}
```
### Find a product based on product title, last modified date, and product visibility
**Request**
```
POST /ListEntities HTTP/1.1
Content-Type: application/json
{
"Catalog": "AWSMarketplace",
"EntityType": "AmiProduct",
"MaxResults": 10,
"EntityTypeFilters": {
"AmiProductFilters": {
"LastModifiedDate": {
"DateRange": {
"BeforeValue": "2018-03-27T13:45:22Z",
"AfterValue": "2018-01-27T13:45:22Z"
}
},
"Visibility": {
"ValueList": [
"Public"
]
},
"ProductTitle": {
"ValueList": [
"ABC-XYZ-123"
]
}
}
}
}
```
**Response**
```
HTTP/1.1 200
Content-type: application/json
{
"EntitySummaryList": [
{
"EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
"EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
"EntityType": "AmiProduct",
"LastModifiedDate": "2018-02-27T13:45:22Z",
"AmiProductSummary": {
"ProductTitle": "ABC-XYZ-123",
"Visibility": "Public"
}
}
],
"NextToken": ""
}
```
### Get additional details about a product
You can get additional details about the product using the entity id with the `DescribeEntity` action.
**Request**
```
GET /DescribeEntity?catalog=AWSMarketplace&entityId=example-abcd-1234 HTTP/1.1
```
**Response**
```
HTTP/1.1 200
Content-type: application/json
{
"DetailsDocument": {
"ProductTitle": "ABC-XYZ-123",
"ShortDescription": "My product short description.",
"LongDescription": "My product longer description.",
"Sku": "123example456",
"SupportDescription": "Need help? Contact our experts at support@example.com \n\nYour purchase includes 24x7 support.",
"Categories": [
"Operating Systems",
"Network Infrastructure",
"Application Development"
]
}
"EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
"EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
"EntityType": "AmiProduct",
"LastModifiedDate": "2018-02-27T13:45:22Z",
}
```
## 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](catalog-apis.md#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"
},
"Details": "{\"Version\": {\"VersionTitle\": \"1.1\",\"ReleaseNotes\": \"Minor bug fix\"},\"DeliveryOptions\": [{\"DeliveryOptionTitle\": \"EKSDelivery\",\"Details\": {\"EcrDeliveryOptionDetails\" : {\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"DeploymentResources\": [{\"Name\": \"HelmDeploymentTemplate\",\"Url\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}],\"CompatibleServices\": [\"EKS\"],\"Description\": \"Sample Description\",\"UsageInstructions\":\"helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}}},{\"DeliveryOptionTitle\": \"HelmChartDeliveryOption\",\"Details\": {\"HelmDeliveryOptionDetails\": {\"CompatibleServices\": [\"EKS\", \"EKS-Anywhere\"],\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"HelmChartUri\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1\",\"Description\": \"Helm chart description\",\"UsageInstructions\": \"Usage instructions\",\"MarketplaceServiceAccountName\": \"Service account name\",\"ReleaseName\": \"Optional release name\",\"Namespace\": \"Optional Kubernetes namespace\",\"OverrideParameters\": [{\"Key\": \"HelmKeyName1\",\"DefaultValue\": \"${AWSMP_LICENSE_SECRET}\"},{\"Key\": \"HelmKeyName2\",\"DefaultValue\": \"${AWSMP_SERVICE_ACCOUNT}\"}]}}}]}",
"DetailsDocument":
{
"Version":
{
"VersionTitle": "1.1",
"ReleaseNotes": "Minor bug fix"
},
"DeliveryOptions":
[
{
"DeliveryOptionTitle": "EKSDelivery",
"Details":
{
"EcrDeliveryOptionDetails":
{
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"DeploymentResources":
[
{
"Name": "HelmDeploymentTemplate",
"Url": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
}
],
"CompatibleServices":
[
"EKS"
],
"Description": "Sample Description",
"UsageInstructions": "helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
}
}
},
{
"DeliveryOptionTitle": "HelmChartDeliveryOption",
"Details":
{
"HelmDeliveryOptionDetails":
{
"CompatibleServices":
[
"EKS",
"EKS-Anywhere"
],
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"HelmChartUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1",
"Description": "Helm chart description",
"UsageInstructions": "Usage instructions",
"MarketplaceServiceAccountName": "Service account name",
"ReleaseName": "Optional release name",
"Namespace": "Optional Kubernetes namespace",
"OverrideParameters":
[
{
"Key": "HelmKeyName1",
"DefaultValue": "${AWSMP_LICENSE_SECRET}"
},
{
"Key": "HelmKeyName2",
"DefaultValue": "${AWSMP_SERVICE_ACCOUNT}"
}
]
}
}
}
]
},
"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"
},
"Details": "{\"Version\": {\"VersionTitle\": \"1.1\",\"ReleaseNotes\": \"Minor bug fix\"},\"DeliveryOptions\": [{\"DeliveryOptionTitle\": \"EKSDelivery\",\"Details\": {\"EcrDeliveryOptionDetails\" : {\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"DeploymentResources\": [{\"Name\": \"HelmDeploymentTemplate\",\"Url\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}],\"CompatibleServices\": [\"EKS\"],\"Description\": \"Sample Description\",\"UsageInstructions\":\"helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}}},{\"DeliveryOptionTitle\": \"HelmChartDeliveryOption\",\"Details\": {\"HelmDeliveryOptionDetails\": {\"CompatibleServices\": [\"EKS\", \"EKS-Anywhere\"],\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"HelmChartUri\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1\",\"Description\": \"Helm chart description\",\"UsageInstructions\": \"Usage instructions\",\"MarketplaceServiceAccountName\": \"Service account name\",\"ReleaseName\": \"Optional release name\",\"Namespace\": \"Optional Kubernetes namespace\",\"OverrideParameters\": [{\"Key\": \"HelmKeyName1\",\"DefaultValue\": \"${AWSMP_LICENSE_SECRET}\"},{\"Key\": \"HelmKeyName2\",\"DefaultValue\": \"${AWSMP_SERVICE_ACCOUNT}\"}]}}}]}",
"DetailsDocument":
{
"Version":
{
"VersionTitle": "1.1",
"ReleaseNotes": "Minor bug fix"
},
"DeliveryOptions":
[
{
"DeliveryOptionTitle": "EKSDelivery",
"Details":
{
"EcrDeliveryOptionDetails":
{
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"DeploymentResources":
[
{
"Name": "HelmDeploymentTemplate",
"Url": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
}
],
"CompatibleServices":
[
"EKS"
],
"Description": "Sample Description",
"UsageInstructions": "helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
}
}
},
{
"DeliveryOptionTitle": "HelmChartDeliveryOption",
"Details":
{
"HelmDeliveryOptionDetails":
{
"CompatibleServices":
[
"EKS",
"EKS-Anywhere"
],
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"HelmChartUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1",
"Description": "Helm chart description",
"UsageInstructions": "Usage instructions",
"MarketplaceServiceAccountName": "Service account name",
"ReleaseName": "Optional release name",
"Namespace": "Optional Kubernetes namespace",
"OverrideParameters":
[
{
"Key": "HelmKeyName1",
"DefaultValue": "${AWSMP_LICENSE_SECRET}"
},
{
"Key": "HelmKeyName2",
"DefaultValue": "${AWSMP_SERVICE_ACCOUNT}"
}
]
}
}
}
]
},
"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.
# Work with AMI-based products
You can use the AWS Marketplace Catalog API to automate tasks for working with Amazon Machine Image (AMI)-based products.
For information about creating a AMI-based product using the Catalog API, see [Create a product](work-with-seller-products.md#create-product).
The following topics describe how to use the Catalog API to perform actions on your AMI-based products:
**Topics**
+ [Add a new version](#ami-add-version)
+ [Update version information](#ami-update-version)
+ [Restrict a version](#ami-restrict-version)
+ [Update future AWS Region support](#update-future-region-support)
+ [Add a supported AWS Region](#add-regions)
+ [Restrict an AWS Region](#restrict-regions)
+ [Add a new instance type](#add-instance-types)
+ [Restrict an instance type](#restrict-instance-types)
## Add a new version
You can use the Catalog API to add a new version to an existing AMI-based product in AWS Marketplace. For more information about adding new AMI versions to your product using the AWS Marketplace Management Portal, see [ Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-version) in the *AWS Marketplace Seller Guide*.
When you create a request that includes adding a new AMI to AWS Marketplace, the AMI must be copied into the AWS Marketplace system and then scanned for security issues. You must give AWS Marketplace access to the AMI by creating an AWS Identity and Access Management (IAM) role with permissions to perform actions on your AMI. For more information on the required permissions, see [Giving AWS Marktplace access to your AMI](https://docs.aws.amazon.com/marketplace/latest/userguide/single-ami-marketplace-ami-access.html) in the *AWS Marketplace Seller Guide*.
To add a new version, call the `StartChangeSet` API operation with the `AddDeliveryOptions` change type for AMI-based products, as shown in the following example. To test your API call without actually creating a new version, set the `Intent` parameter to `VALIDATE`. For more information, see [Intent](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_StartChangeSet.html#API_StartChangeSet_RequestBody).
**Note**
For AMI products, a version is made up of one or more delivery options. All delivery options in the same version must have the same `AmiSource` object with the same details. All delivery options must be added to a version when the version is created. It is not possible to add delivery options to an existing version.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddDeliveryOptions",
"Entity":
{
"Type": "AmiProduct@1.0",
"Identifier": "prod-example12345"
},
"DetailsDocument":
{
"Version":
{
"VersionTitle": "My new title",
"ReleaseNotes": "My new Release notes"
},
"DeliveryOptions":
[
{
"Details":
{
"AmiDeliveryOptionDetails":
{
"AmiSource":
{
"AmiId": "ami-1234567890abcdef",
"AccessRoleArn": "arn:aws:iam::12345678901:role/AwsMarketplaceAmiIngestion",
"UserName": "ec2-user",
"OperatingSystemName": "AMAZONLINUX",
"OperatingSystemVersion": "Amazon Linux 2 AMI 2.0.20210126.0 x86_64 HVM gp2",
"AfiIds": ["afi-1234567890abcdefg", "afi-abcdefg1234567890"] //Optional (Required only for FPGA products)
},
"UsageInstructions": "Easy to use AMI",
"RecommendedInstanceType": "m4.xlarge",
"SecurityGroups":
[
{
"IpProtocol": "tcp",
"FromPort": 443,
"ToPort": 443,
"IpRanges":
[
"0.0.0.0/0"
]
}
]
}
}
},
{
"DeliveryOptionTitle": "My new AMI with CFTdelivery option",
"Details":
{
"DeploymentTemplateDeliveryOptionDetails":
{
"ShortDescription": "My new short description",
"LongDescription": "My new long description",
"UsageInstructions": "My new usage instructions",
"RecommendedInstanceType": "m4.xlarge",
"ArchitectureDiagram": "https://my-bucket.s3.amazonaws.com/my-folder/diagram.png",
"Template": "https://my-bucket.s3.amazonaws.com/my-folder/cft.template",
"TemplateSources":
[
{
"ParameterName": "MyAmiParam",
"AmiSource":
{
"AmiId": "ami-1234567890abcdef",
"AccessRoleArn": "arn:aws:iam::12345678901:role/AwsMarketplaceAmiIngestion",
"UserName": "ec2-user",
"OperatingSystemName": "AMAZONLINUX",
"OperatingSystemVersion": "Amazon Linux 2 AMI 2.0.20210126.0 x86_64 HVM gp2"
}
}
]
}
}
}
]
}
}
],
"Intent": "APPLY"
}
```
The following list provides information about the input fields you use with the `AddDeliveryOptions` change type. All fields are required unless otherwise noted. For more information about these fields, see [Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-version) in the AWS Marketplace Seller Guide.
+ **DeliveryOptions** (array of objects) – A list of delivery option objects, including the details of each. You must include at least one.
+ For *AMI (standalone)* delivery option, specify an object with the following details. You can only have one delivery option with this type.
+ **Details** (object) – Holds the details of this delivery option. Note that this nested details object does not need to be double-escaped.
+ **AmiDeliveryOptionDetails** (object) – Use to provide the details of each AMI delivery option.
+ **AmiSource** (object) – Details about the AMI to be used for the added version.
+ **AmiId** (string) – ID for the source AMI, located in the AWS Region where the API is being called. This must always be US East (N. Virginia) because that is the only region where the Catalog API is available. Must belong to the caller account.
+ **AccessRoleArn **(string) – IAM role Amazon Resource Name (ARN) used by AWS Marketplaceto access the provided AMI. For details about creating and using this ARN, see [Giving AWS Marketplace access to your AMI](https://docs.aws.amazon.com//marketplace/latest/userguide/ami-single-ami-products.html#single-ami-marketplace-ami-access) in the *AWS Marketplace Seller Guide*.
+ **UserName** (string) – Login user name to access the operating system (OS) in the AMI. Typically ec2-user for Linux AMIs or Administrator for Windows.
+ **ScanningPort** (integer) – SSH or RDP port used to access the OS. Used for scanning the provided AMI for security vulnerabilities. Defaults to 22.
+ **OperatingSystemName** (string) – Name of the operating system displayed to buyers.
+ **OperatingSystemVersion** (string) – Operating system version string displayed to buyers.
+ **AfiIds** (array of strings) (optional) – Amazon FPGA Image (AFI) IDs to enable FPGA support for this version. When provided, this enables your product to run on FPGA-enabled F2 instance types. You can provide up to 15 AFI IDs per version. All AFI IDs you provide must originate from the US East (N. Virginia) region, reside within your AWS Marketplace seller account, and the provided IAM access role should have permissions to share this AFI with AWS Marketplace. For more details about the required permissions, see [Giving AWS Marketplace access to your FPGA images](https://docs.aws.amazon.com/marketplace/latest/userguide/single-ami-marketplace-ami-access.html#single-ami-marketplace-afi-access) in the *AWS Marketplace Seller Guide*.
+ **UsageInstructions** (string) – Instructions for using the AMI, or a link to more information about the AMI.
+ **AccessEndpointUrl** (object) (optional) – Used to create a path to access the AMI after it is used.
+ **Port** (string) – The port number used to access the service running on the AMI.
+ **Protocol** (string) – The protocol (http or https) used to access the service running on the AMI.
+ **RelativePath** (string) – The path from the web root to access the service running on the AMI (for example /index.html).
+ **RecommendedInstanceType** (string) – The instance type that is recommended to run the service with the AMI and is the default for 1-click installs of your service. For a list of instance types, see [Instance types](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-types.html) in the *Amazon Elastic Compute Cloud User Guide for Linux Instances*.
+ **SecurityGroups** (array of objects) – A list of objects representing ingress rules for the automatically created groups for the version.
+ **IpProtocol** (string) – The protocol to use (tcp or udp).
+ **FromPort** (integer) – The source port.
+ **ToPort** (integer) – The destination port.
+ **IpRanges** (array of strings) – IP ranges to allow, in CIDR format (in the form xxx.xxx.xxx.xxx/nn, for example, *192.0.2.0/24*).
+ For *AMI with CloudFormation* delivery option, specify an object with the following details. You can have up to three delivery options of this type.
+ **DeliveryOptionTitle** (string) – Title for delivery option.
+ **Details** (object) – Holds the details of an AMI delivery option. Note that this nested details object does not need to be double-escaped.
+ **DeploymentTemplateDeliveryOptionDetails** (object) – Use to provide the details of each CFT delivery option.
+ **ShortDescription** (string) – Brief description of your CloudFormation template delivery option.
+ **LongDescription** (string) – Detailed description of your CloudFormation template delivery option.
+ **UsageInstructions** (string) – Instructions for using the AMI, or a link to more information about the AMI.
+ **RecommendedInstanceType** (string) – The instance type that is recommended to run the service with the AMI and is the default for 1-click installs of your service. For a list of instance types, see [Instance types](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-types.html) in the *Amazon Elastic Compute Cloud User Guide for Linux Instances*.
+ **ArchitectureDiagram** (string) – URL to the location of your architectural diagram in Amazon S3.
+ **Template** (string) – URL to the location of your CloudFormation Template in Amazon S3.
+ **TemplateSources** (array of objects)
+ **ParameterName** (string) – Name of the parameter in the CloudFormation Template that the AMI in this version should be passed in to. For more information, see [Requirements for AMI details](https://docs.aws.amazon.com//marketplace/latest/userguide/cloudformation.html#ami-requirements-sse).
+ **AmiSource** (object)
+ **AmiId** (string) – ID for the source AMI, located in the AWS Region where the API is being called (currently must always be US East (N. Virginia) because that is the only region where the Catalog API is available). Must belong to the caller account.
+ **AccessRoleArn** (string) – IAM role Amazon Resource Name (ARN) used by AWS Region to access the provided AMI. For details about creating and using this ARN, see [Giving AWS Marketplace access to your AMI](https://docs.aws.amazon.com//marketplace/latest/userguide/ami-single-ami-products.html#single-ami-marketplace-ami-access) in the *AWS Marketplace Seller Guide*.
+ **UserName** (string) – Login user name to access the operating system (OS) in the AMI. Typically `ec2-user` for Linux AMIs or `Administrator` for Windows.
+ **OperatingSystemName** (string) – Name of the operating system displayed to buyers.
+ **OperatingSystemVersion** (string) – Operating system version string displayed to buyers.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
For more information about errors in seller product change sets, see [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors).
When the request is complete, the version is added, and any existing subscribers will receive an email message telling them about the new version. For more information about the process of adding a new version, see [ Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-version) in the *AWS Marketplace Seller Guide*.
**Asynchronous Errors**
The following errors are specific to `AddDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1AMI\$1NAME | The prefix (x) in the AMI name is invalid. Provide a new name using your company or brand name as a prefix. |
| INVALID\$1PRODUCT | Use an existing limited or public product. |
| DUPLICATE\$1VERSION\$1TITLE | The version title must be different from any other version titles of this product. |
| INVALID\$1VERSION\$1TITLE | Remove spaces before the trademark symbol. |
| INVALID\$1VERSION\$1TITLE | Remove unsupported characters: [x, y, z] |
| INVALID\$1VERSION\$1TITLE | Remove spaces from the beginning of the version title. |
| INVALID\$1VERSION\$1TITLE | Provide version title with fewer than [x] characters. |
| INVALID\$1RELEASE\$1NOTES | Remove spaces before the trademark symbol. |
| INVALID\$1RELEASE\$1NOTES | Remove unsupported characters: [x, y, z] |
| INVALID\$1RELEASE\$1NOTES | Remove spaces from the beginning of release notes. |
| INVALID\$1RELEASE\$1NOTES | Provide release notes with fewer than (x) characters. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove spaces before the trademark symbol. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove unsupported characters: [x, y, z] |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove spaces from the beginning of release notes. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Provide usage instructions with fewer than (x) characters. |
| RECOMMENDED\$1INSTANCE\$1TYPE\$1NOT\$1AVAILABLE | Provide an existing, available instance type. |
| INVALID\$1RECOMMENDED\$1INSTANCE\$1TYPE | Provide a valid instance type. |
| INVALID\$1SECURITY\$1GROUP | Security group ports must be between 1 and [max]. |
| INVALID\$1SECURITY\$1GROUP | Provide a value for CIDR IP ranges. |
| INVALID\$1SECURITY\$1GROUP | Provide security group start port that is not greater than end port. |
| INVALID\$1SECURITY\$1GROUP\$1PROTOCOL | Security group protocol must either be ‘tcp’ or ‘udp’. |
| INVALID\$1CIDR\$1IP | Provide standard CIDR IP range in form '0.0.0.0/0'. |
| INVALID\$1ACCESS\$1ENDPOINT\$1PORT | Provide endpoint port less than [x]. |
| INVALID\$1ACCESS\$1ENDPOINT\$1PORT | Provide endpoint port between 1 and [max]. |
| INVALID\$1ACCESS\$1ENDPOINT\$1PORT | Provide endpoint port. |
| INVALID\$1ACCESS\$1ENDPOINT\$1RELATIVE\$1PATH | Remove spaces in the relative path. |
| INVALID\$1ACCESS\$1ENDPOINT\$1RELATIVE\$1PATH | Remove preceding '/' from relative path. |
| INCOMPATIBLE\$1OPERATING\$1SYSTEM | Provide operating system name and version that is compatible with instance types: [x] |
| INCOMPATIBLE\$1OPERATING\$1SYSTEM\$1NAME | Provide name with fewer than (x) characters. |
| INCOMPATIBLE\$1OPERATING\$1SYSTEM\$1NAME | Provide operating system name that is supported. |
| INCOMPATIBLE\$1OPERATING\$1SYSTEM\$1VERSION | Provide version with fewer than (x) characters. |
| INVALID\$1SCANNING\$1PORT | Provide scanning port between 1 and [max]. |
| INVALID\$1AMI\$1ID | Provide valid AMI ID. |
| EXISTING\$1AMI\$1PRODUCT\$1CODE | Remove product code attached to image X. |
| INVALID\$1AMI\$1ARCHITECTURE | Provide new AMI with architecture [x]. |
| INVALID\$1AMI\$1VIRTUALIZATION\$1TYPE | Provide new AMI with virtualization type [x]. |
| INVALID\$1AMI\$1VIRTUALIZATION\$1TYPE | Provide expected [z] volume on image [x]. |
| INCOMPATIBLE\$1AMI | Provide new AMI as architecture [x] on [y] is not supported by following instance types: [z] |
| INCOMPATIBLE\$1AMI | Provide new AMI as virtualization type [x] on [y] is not supported by following instance types: [z] |
| INCOMPATIBLE\$1AMI | Enable ENA support for image x because following instance types require ENA support: [y] |
| ASSET\$1NOT\$1FOUND | Check if [ami-id] exists in us-east-1 Region of [account-id] AWS account and the AccessARN provided [ARN] has permissions to share this AMI with AWS Marketplace. |
| ASSET\$1ACCESS\$1EXCEPTION | Unable to copy AMI [x] into AWS Marketplace account. |
| SCAN\$1ERROR | Fix security vulnerability [y] on Image [x]. |
| ASSET\$1NOT\$1FOUND | Check if [afi-id] exists in us-east-1 Region of [account-id] AWS account and the AccessARN provided [ARN] has permissions to share this AFI with AWS Marketplace. |
| ASSET\$1ACCESS\$1EXCEPTION | Unable to access AFI. Check if AccessARN provided [ARN] has permissions to share this AFI with AWS Marketplace and access role Account is AFI owner. |
| MISSING\$1FPGA\$1INSTANCE\$1TYPE | No FPGA based instance type found. Use AddInstanceTypes change type to add FPGA based instance type. |
You can also create a AMI-based product using the AWS Marketplace Management Portal. For more information, see [ AMI products](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html) in the *AWS Marketplace Seller Guide*.
For a walk-through showing how to automate updating your AMI-based product, you can also refer to the video, [ Automating updates to your product listings in AWS Marketplace with Catalog API](https://www.youtube.com/watch?v=7KpUJ6Wcqrg) (5:08).
## Update version information
You can use the Catalog API to update the details of an existing version of your AMI-based product in AWS Marketplace.
**Note**
For more information about updating version information using the AWS Marketplace Management Portal, see [ Updating version information](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-updating-version) in the *AWS Marketplace Seller Guide*.
You cannot update the AMI for the version. If you need to update the AMI, create a new version instead.
To add a new version, call the `StartChangeSet` API operation with the `UpdateDeliveryOptions` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateDeliveryOptions",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1",
"Type": "AmiProduct@1.0"
},
"DetailsDocument":
{
"Version":
{
"ReleaseNotes": "*My new Release notes*"
},
"DeliveryOptions":
[
{
"Id": "example1-2222-cccc-2222-cccccccccccc",
"Details":
{
"AmiDeliveryOptionDetails":
{
"UsageInstructions": "Easy to use AMI"
}
}
},
{
"Id": "example1-2222-dddd-2222-dddddddddddd",
"Details":
{
"DeploymentTemplateDeliveryOptionDetails":
{work with ami
"DeliveryOptionTitle": "My updated delivery option title",
"UsageInstructions": "Updated usage instructions here."
}
}
}
]
}
}
]
}
```
The following is information about the input fields you provide for adding the `UpdateDeliveryOptions` change type. For more information about these fields, see [ Updating version information](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-updating-version) in the AWS Marketplace Seller Guide.
+ **Entity** (object) (required) – Your AMI-based product.
+ **Identifier** (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **Type** (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+ **DetailsDocument** (object) (required) – Details of the request. It includes any information about the version of your AMI-based product that you would like to update. The included fields are all optional, but you must include at least one field to update.
+ **Version** (object) – Details about the software version.
+ **ReleaseNotes** (string) – Notes for buyers to tell them about changes from one version to the next.
+ **DeliveryOptions** (array of objects) – List of delivery option objects. Include only the delivery options you want to update.
+ For *AMI (standalone)* delivery option, specify an object with the following details. Include only the fields you want to update. All fields are optional unless otherwise noted.
+ **Id** (string) (required) – Unique identifier for the delivery option (you can get the unique identifier for the delivery option by calling the `DescribeEntity` action on the product you are updating).
+ **Details** (object) – Holds the details of an AMI delivery option. Note that this nested details object does *not* need to be double-escaped.
+ **AmiDeliveryOptionDetails** (object) – The details of one AMI delivery option.
+ **UsageInstructions** (string) – Instructions for using the AMI, or a link to more information about the AMI.
+ **AccessEndpointUrl** (object) – Used to create a path to access the AMI after it is used.
+ **Port** (string) – The port number used to access the service running on the AMI.
+ **Protocol** (string) – The protocol (`http` or `https`) used to access the service running on the AMI.
+ **RelativePath** (string) – The path from the web root to access the service running on the AMI (for example */index.html*).
+ **RecommendedInstanceType** (string) – The instance type that is recommended to run the service with the AMI and is the default for 1-click installs of your service.
+ **SecurityGroups** (array of objects) – A list of objects representing ingress rules for the automatically created groups for the version:
+ **FromPort** (integer) – The source port.
+ **IpProtocol** (string) – The protocol to use (`tcp` or `idp`).
+ **IpRanges** (array of strings) – IP ranges to allow, in CIDR format (in the form *xxx.xxx.xxx.xxx/nn*, for example, *192.0.2.0/24*).
+ **ToPort** (integer) – The destination port.
+ For *AMI with CloudFormation* delivery option, specify an object with the following details. Include only the fields you want to update. All fields are optional unless otherwise noted.
+ **Id** (string) (required) – Unique identifier for the delivery option (you can get the unique identifier for the delivery option by calling the `DescribeEntity` action on the product you are updating).
+ **Details** (object) – Holds the details of an AMI delivery option. Note that this nested details object does *not* need to be double-escaped.
+ **DeploymentTemplateDeliveryOptionDetails** (object) – Use to provide the details of each CFT delivery option.
+ **DeliveryOptionTitle** (string) – Title for delivery option.
+ **ShortDescription** (string) – Brief description of your CloudFormation template delivery option.
+ **LongDescription** (string) – Detailed description of your CloudFormation template delivery option.
+ **UsageInstructions** (string) – Instructions for using the AMI, or a link to more information about the AMI.
+ **RecommendedInstanceType** (string) – The instance type that is recommended to run the service with the AMI and is the default for 1-click installs of your service. For a list of instance types, see [Instance types](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-types.html) in the *Amazon Elastic Compute Cloud User Guide for Linux Instances*.
+ **ArchitectureDiagram** (string) – URL to the location of your architectural diagram in Amazon S3.
+ **Template** (string) – URL to the location of your CloudFormation Template in Amazon S3.
+ **TemplateSources** (array of objects)
+ **ParameterName** (string) – Name of the parameter in the CloudFormation Template that the AMI in this version should be passed in to. For more information, see [Requirements for AMI details](https://docs.aws.amazon.com//marketplace/latest/userguide/cloudformation.html#ami-requirements-sse).
+ **AmiSource** (object)
+ **AmiId** (string) – ID for the source AMI, located in the AWS Region where the API is being called (currently must always be US East (N. Virginia) because that is the only region where the Catalog API is available). Must belong to the caller account.
+ **AccessRoleArn** (string) – IAM role Amazon Resource Name (ARN) used by AWS Region to access the provided AMI. For details about creating and using this ARN, see [Giving AWS Marketplace access to your AMI](https://docs.aws.amazon.com//marketplace/latest/userguide/ami-single-ami-products.html#single-ami-marketplace-ami-access) in the *AWS Marketplace Seller Guide*.
+ **UserName** (string) – Login user name to access the operating system (OS) in the AMI. Typically `ec2-user` for Linux AMIs or `Administrator` for Windows.
+ **OperatingSystemName** (string) – Name of the operating system displayed to buyers.
+ **OperatingSystemVersion** (string) – Operating system version string displayed to buyers.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
For more information about change sets, see [Working with change sets](catalog-apis.md#working-with-change-sets). For more information about errors in seller product change sets, see [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors).
**Asynchronous Errors**
The following errors are specific to `UpdateDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
You can retrieve `UpdatePricingTerms` actions by using the `DescribeChangeSet` operation after the change set begins processing. For more information about error details and troubleshooting, refer to [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors), earlier in this guide.
| Error code | Error message |
| --- | --- |
| INVALID\$1PRODUCT | Use an existing limited or public product. |
| MISSING\$1DELIVERY\$1OPTION\$1IDS | Provide at least one delivery option ID. |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| INVALID\$1DELIVERY\$1OPTIONS | Provide delivery option IDs that belong to the same version. |
## Restrict a version
You can use the Catalog API to restrict a version of your AMI-based product. This prevents new buyers from using that version, but keeps it available to existing buyers. Restricting all delivery options from a version restricts the version. Restricting one or more, but not all, delivery options from a version restricts just the delivery options in that version. You must always have at least one unrestricted version of a product available, so you cannot restrict the last publicly available version of a product.
**Note**
For more information about restricting AMI versions in AWS Marketplace via the AWS Marketplace Management Portal, see [Restricting a version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-restricting-version) in the *AWS Marketplace Seller Guide*.
To restrict a version, call the `StartChangeSet` API operation with the `RestrictDeliveryOptions` change type, as shown in the following example.
**Note**
All subscribers can use the current version regardless of the restriction status. AWS Marketplace guidelines require that you continue to offer support to existing buyers for 90 days after restricting the version. Your AMI will be marked as deprecated after the version is restricted. For more information, see [Deprecate an AMI](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-deprecate.html) in the *Amazon Elastic Compute Cloud User Guide for Windows Instances*.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "RestrictDeliveryOptions",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1",
"Type": "AmiProduct@1.0"
},
"DetailsDocument":
{
"DeliveryOptionIds":
[
"example1-2222-cccc-2222-cccccccccccc"
]
}
}
]
}
```
The following is information about the input fields you provide for adding the `RestrictDeliveryOptions` change type:
+ **Entity** (object) (required) – Your AMI-based product.
+ **Identifier** (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **Type** (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+ **DetailsDocument** (object) (required) – Details of the request. It includes IDs for the versions of your AMI-based product that you would like to restrict.
+ **DeliveryOptionIds** (array of objects) – List of `DeliveryOption` IDs for the versions that you want to restrict. You can get the unique identifier for the `DeliveryOption` by calling the `DescribeEntity` action on the version you are restricting.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
**Asynchronous Errors**
The following errors are specific to `RestrictDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1PRODUCT | Use an existing public product. |
| MISSING\$1DELIVERY\$1OPTION\$1IDS | Provide at least one delivery option ID. |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| INVALID\$1DELIVERY\$1OPTION | Provide delivery option IDs that are in a public state. IDs not in public state: [x] |
| ALL\$1DELIVERY\$1OPTIONS\$1RESTRICTED | Provide fewer delivery options to restrict as at least one must remain in public state. |
## Update future AWS Region support
You can use the Catalog API to change future AWS Region support preferences for your AMI-based product in AWS Marketplace.
**Note**
For more information about changing future Region support using the AWS Marketplace Management Portal, see [ Update support for future AWS Regions](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-updating-future-region-support) in the *AWS Marketplace Seller Guide*.
**Note**
The `UpdateFutureRegionSupport` change type is only available on `AmiProduct@1.0`.
To change future AWS Region support preferences, call the `StartChangeSet` API operation with the `UpdateFutureRegionSupport` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateFutureRegionSupport",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "AmiProduct@1.0"
},
"DetailsDocument":
{
"FutureRegionSupport":
{
"SupportedRegions":
[
"All"
]
}
}
}
]
}
```
Provide information for the fields to add the `UpdateFutureRegionSupport` change type:
+ `Entity` (object) (required) – Your AMI-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+ `DetailsDocument` (object) (required) – The details required to execute the ChangeSet.
+ `FutureRegionSupport` – Object
+ `SupportedRegions` – Single-element array of strings
Element supported values: one of [`"All"`, `"US"`, `"None”`]
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
**Asynchronous Errors**
The following errors are specific to `UpdateFutureRegionSupport` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| TOO\$1MANY\$1REGIONS | Currently, only 1 value is supported for FutureRegionSupport: All, US, or None |
| INVALID\$1REGIONS | Requested Regions [a, b, c] are invalid or unavailable. Only supported values are [x, y, z]. |
| INVALID\$1INPUT | SupportedRegions can't be empty. |
## Add a supported AWS Region
You can use the Catalog API to add new supported AWS Regions for your AMI-based product in AWS Marketplace.
**Note**
For more information about adding new supported Regions using the AWS Marketplace Management Portal, see [ Add an AWS Region](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-regions) in the *AWS Marketplace Seller Guide*.
**Note**
The `AddRegions` change type is only available on `AmiProduct@1.0`.
To add new supported Regions, call the `StartChangeSet` API operation with the `AddRegions` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "AddRegions",
"DetailsDocument": {
"Regions": [
"us-east-1",
"ap-northeast-2"
]
},
"Entity": {
"Identifier": "prod-123456@1",
"Type": "AmiProduct@1.0"
}
}
]
}
```
Provide information for the fields to add the `AddRegions` change type.
+ `Entity` (object) (required) – Your AMI-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+
**Example**
+ `Regions`: Array of strings
Element supported values: Valid AWS Region code strings.
For example, [`"us-east- 1"`].
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
+ If the change set execution status is `SUCCEEDED`: A new Entity `Identifier` (or `EntityId`) is generated. You can use the [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeEntity.html](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeEntity.html) API operation on the product entity to check the result.
+ If the change set execution status is `CLIENT_ERROR`: The `DescribeChangeSet` response gives the details of the error, as well as corresponding actions to take to fix the error.
**Asynchronous Errors**
The following errors are specific to `AddRegions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1REGIONS | Requested regions [a, b, c] are invalid or unavailable. Only supported values are [x, y, z]. |
| INVALID\$1INPUT | Regions can't be empty. |
## Restrict an AWS Region
You can use the Catalog API to restrict previously supported AWS Regions for your AMI-based product in AWS Marketplace.
**Note**
For more information about restricting previously supported Regions using the AWS Marketplace Management Portal, see [ Restrict an AWS Region](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-restricting-regions) in the *AWS Marketplace Seller Guide*.
**Note**
The `RestrictRegions` change type is only available on `AmiProduct@1.0`.
To restrict previously supported Regions, call the `StartChangeSet` API operation with the `RestrictRegions` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "RestrictRegions",
"DetailsDocument": {
"Regions": [
"us-east-1",
"ap-northeast-2"
]
},
"Entity": {
"Identifier": "prod-123456@1",
"Type": "AmiProduct@1.0"
}
}
]
}
```
Provide information for the fields to add the `AddRegions` change type.
+ `Entity` (object) (required) – Your AMI-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+ **DetailsDocument** (object) (required) – The details required to execute the ChangeSet.
+ `Regions` – Array of strings
Element supported values: Valid AWS Region code strings, such as `"us-east-1"`.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
+ If the change set execution status is `SUCCEEDED` – A new Entity `Identifier` (or `EntityId`) is generated. You can use `DescribeEntity` on the product entity to check the result. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeEntity.html](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeEntity.html).
+ If the change set execution status is `CLIENT_ERROR`: The `DescribeChangeSet` response gives the details of the error, as well as corresponding actions to take to fix the error.
**Asynchronous Errors**
The following errors are specific to `AddRegions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1REGIONS | Requested regions [a, b, c] are invalid or unavailable. Only supported values are [x, y, z]. |
| INVALID\$1INPUT | Regions can't be empty. |
## Add a new instance type
You can use the Catalog API to add new instance types for your AMI-based product in AWS Marketplace.
**Note**
For more information about adding instance types using the AWS Marketplace Management Portal, see [ Add an instance](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-instance-types) in the *AWS Marketplace Seller Guide*.
`AddInstanceTypes` will add new instance types to existing products and newly created products when creating a product. The change type will update all versions in product document with a new instance type.
**Note**
The `AddInstanceTypes` change type is only available on `AmiProduct@1.0`.
When adding a restricted instance type, the instance type can be removed from the restricted list and added to the available instance type list. This gives sellers more control to change their product restriction. The instance type list is interchangeable and not a permanent restricted status for a product.
For internally metered products, sellers need to call separate change types `AddDimensions` and `UpdatePricingTerms` to update pricing for the instance type.
To add new instance types, call the `StartChangeSet` API operation with the `RestrictRegions` change type, as shown in the following example.
**Request Syntax**
Only `AddInstanceTypes` change type is shown below. Although internally metered AMI sellers are required to call `AddInstanceTypes` and `UpdatePricingTerms` change types for their AMI.
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddInstanceTypes",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "AmiProduct@1.0"
},
"DetailsDocument":
{
"InstanceTypes":
[
"m1.medium"
]
}
}
]
}
```
Provide information for the fields to add the `AddInstanceTypes` change type:
+ `Entity` (object) (required) – Your AMI-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+ **DetailsDocument** (object) (required) – The details required to execute the `ChangeSet`, in this case `InstanceTypes`.
+ `InstanceTypes` (array of strings) (required) – List of `InstanceTypes` to add to the product. These instances will be added to the existing `InstanceTypes`.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
**Synchronous Validations**
The following schema validations are specific to `AddInstanceTypes` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP |
| --- | --- | --- |
| InstanceTypes | Required | 422 |
| InstanceTypes | Must not be empty | 422 |
| InstanceTypes | Entries must be between 1 to 24 characters long. Must match ^[A-Za-z0-9\$1.-]\$1\$1 | 422 |
| InstanceTypes | Entries must be unique | 422 |
| InstanceTypes | Must not be more than 1500 entries | 422 |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `AddInstanceTypes` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1INSTANCE\$1TYPES | The following instance types are not valid: [x] |
| INVALID\$1INSTANCE\$1VIRTUALIZATION | Virtualization of the product is [x]. It is not supported by the following instance types: [x] |
| INVALID\$1AMI\$1ARCHITECTURE | CPU architecture of the product is '%s'." \$1 "It is not supported by the following instance types: [x] |
| INCOMPATIBLE\$1OPERATING\$1SYSTEM | The instance types are incompatible with the OS defined in the product. Provide instance types that are compatible with the OS defined in the product. |
| INVALID\$1PRODUCT\$1TYPE | Use an existing single AMI product. |
| INVALID\$1ENA\$1SETTING | The product does not support ENA. ENA support is required by the following instance types: [x] |
| INVALID\$1DIMENSIONS | No internally metered dimensions found for instance types: [x] |
| UPDATE\$1PRICING\$1REQUIRED | UpdatePricingTerms change type is required when internally metered dimensions are available on the product. |
## Restrict an instance type
You can use the Catalog API to limit or restrict the instance types available for your AMI-based product in AWS Marketplace.
**Note**
For more information about limiting or restrict the instance types available using the AWS Marketplace Management Portal, see [ Restrict an instance](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-restricting-instance-types) in the *AWS Marketplace Seller Guide*.
Existing subscribers won't be impacted by this change and they are able to use the restricted instance types. However, no new buyers will be able to use restricted instance types. To stop current instance types subscriptions (once instance types are restricted), you must contact the AWS Marketplace Seller Operations Team.
`RestrictInstanctTypes` restricts instance types to all the versions in the product document. In the `AddInstanceTypes` change type, you are updating all versions of the product. You won’t be able to restrict the recommended instance types. The recommended instance type is at the version level, so it’s possible that the seller won’t be able to restrict multiple instance types.
For an internally metered product, you need to call separate change types when calling `RestrictDimensions`. This prevents new offers being created for the restricted instance types.
**Note**
The `RestrictInstanceTypes` change type is only available on `AmiProduct@1.0`.
To limit or restrict the instance types available for your AMI-based product, call the `StartChangeSet` API operation with the `RestrictInstanceTypes` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "RestrictInstanceTypes",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "AmiProduct@1.0"
},
"DetailsDocument":
{
"InstanceTypes":
[
"m1.medium"
]
}
}
]
}
```
Provide information for the fields to add the `RestrictInstanceTypes` change type.
+ `Entity` (object) (required) – Your AMI-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `AmiProduct@1.0`.
+ **DetailsDocument** (object) (required) – The details required to execute the `ChangeSet`, in this case `InstanceTypes`.
+ `InstanceTypes` (array of strings) (required) – List of `InstanceTypes` to restrict to the product. These instances are added to the current (or if there are no existing instance types, it will add) to restricted `InstanceTypes`.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This included validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
**Synchronous Validations**
The following schema validations are specific to `RestrictInstanceTypes` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP |
| --- | --- | --- |
| InstanceTypes | Required | 422 |
| InstanceTypes | Must not be empty | 422 |
| InstanceTypes | Entries must be between 1 to 24 characters long. Must match ^[A-Za-z0-9\$1.-]\$1\$1 | 422 |
| InstanceTypes | Entries must be unique | 422 |
| InstanceTypes | Must not be more than 1500 entries | 422 |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `RestrictInstanceTypes` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1 INSTANCE\$1TYPES | The following instance types are not valid: [x] |
| INVALID\$1 PRODUCT\$1TYPE | Use an existing single AMI product. |
| DUPLICATE\$1INSTANCE\$1TYPE | Provide instance types with no duplicates. |
| UNAVAILABLE\$1INSTANCE\$1TYPE | Provide an available instance type. |
| RECOMMENDED\$1INSTANCE\$1TYPE\$1RESTRICTED | The following instance types cannot be restricted. Recommended instance type must be changed to a different one before being restricted. Delivery Options Id [X] Instance Type[X] |
| DIMENSIONS\$1NOT\$1RESTICTED | Restrict dimensions before restricting internally metered instance types: [x] |
| REGION\$1NO\$1INSTANCES | Your restricted instance types would cause product launch failure in region: X. Consider restricting fewer instances. |
| INCOMPATIBLE\$1RESTRICTION | Your restricted instance types would cause product with no FPGA based instance types for AFIs. Product needs to support at least one FPGA based instance type. |
# Work with EC2 Image Builder component products
As an AWS Marketplace seller, you can list AMI-based products delivered to AWS Marketplace buyers using EC2 Image Builder components. To create your component and publish an AWS Marketplace listing, proceed sequentially through the following sections.
**Topics**
+ [Building and testing your Image Builder component](#build-and-test-ib-component)
+ [Copying the component ARN](#ib-copy-component-arn)
+ [Creating AWS Marketplace IAM policies](#ib-create-iam-policies)
+ [Creating the AWS Marketplace IAM role](#ib-create-iam-role)
+ [Prepare your Image Builder component listing](#prepare-ec2-ib-listing)
+ [Publishing your Image Builder component product listing](#publishing-ib-component-listing)
+ [Updating Image Builder component product information](#updating-ec2-image-builder-product)
+ [Adding a new version to an existing Image Builder component product](#adding-new-ec2-ib-version-existing-product)
+ [Updating information about an existing version](#updating-ec2-ib-product-version)
+ [Restricting an Image Builder component product version](#restricting-ec2-ib-product-version)
+ [Monitoring a change set](#monitor-changeset)
+ [Securing software downloads](#securing-software-downloads)
## Building and testing your Image Builder component
Build and test your component on Image Builder. For instructions, refer to [Develop custom components for your Image Builder image](https://docs.aws.amazon.com//imagebuilder/latest/userguide/create-custom-components.html) in the *Image Builder User Guide*. When creating your component using Image Builder, ensure that you do the following:
+ The component and all of its underlying dependencies, such as an Amazon Simple Storage Service (Amazon S3) bucket, secrets, or parameters, must be created in the US East (N. Virginia) (`us-east-1`) AWS Region.
+ Include supported architecture and any software dependencies in the component description.
+ Test your component in your AWS account by creating an [image pipeline](https://docs.aws.amazon.com/imagebuilder/latest/userguide/start-build-image-pipeline.html) and deploying the AMI created by the pipeline.
+ If your component contains instructions to copy binaries, packages, or files from an S3 bucket, use the `S3Download` action module. In the `S3Download` module, for `source`, enter the static location of your file in the S3 bucket. The following example copies a binary from an S3 bucket as part of the component installation.
```
- name: DownloadMyFile
action: S3Download
inputs:
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
```
+ Components can ingest files of up to 2 GB when using the `S3Download` action.
+ If your component uses [parameters](https://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-user-defined-variables.html#user-defined-vars-parameters), ensure that all parameters have default values. For example, if you have a parameter named `region`, ensure that you have a valid default value such as `us-east-1`. These default values are for AWS Marketplace processing and testing. Testing may fail if you do not include default values.
+ If your component uses AWS Secrets Manager, Parameter Store, or a capability of AWS Systems Manager to store parameters, do the following:
+
+ To retrieve values as a step in your component, embed AWS Command Line Interface commands in your YAML configuration file.
+ Create a corresponding entry in Secrets Manager or Parameter Store in your AWS account. Use the default key and provide a valid value that will assist in building the component during the AWS Marketplace testing process. For example, say you have a parameter called `saas_token` with a default value of `token` that uses Parameter Store. In this case, create a key-value pair in Parameter Store. Use `token` as the key. For the value, enter a valid SaaS token for your application.
Note that values stored in your AWS Marketplace seller account will only be used for AWS Marketplace testing purposes. These values will not be shared with buyers.
+ AWS Marketplace automatically generates Amazon Machine Images (AMIs) for your component across all compatible operating system versions you choose during the component creation process. When building your component, choose at least one compatible operating system version. Validate your component's compatibility with all chosen operating system versions by using EC2 Image Builder pipelines to create and test AMIs.
## Copying the component ARN
After creating and testing the component on Image Builder, copy and save the component ARN. You will use the ARN when you publish the product listing using the AWS Marketplace Catalog API.
**To copy the Image Builder component ARN**
1. Sign in to the AWS Management Console and open the Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/).
1. In the left navigation bar, under **Saved resources**, choose **Components**.
1. On the **Components** page, for **Filter owner**, choose **Owned by me**.
1. Choose the component name.
1. On the component detail page, in the **Summary** section, copy the ARN.
## Creating AWS Marketplace IAM policies
Create the following IAM policies to grant AWS Marketplace access to your Image Builder component and related resources like Amazon S3 buckets and secrets. Use the example policies provided. You attach these policies to an [AWS Marketplace IAM role](#ib-create-iam-role). For help creating policies, see [Creating policies using the JSON editor](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) in the *IAM User Guide*.
+ Image Builder get-component policy, to allow AWS Marketplace to access your component on Image Builder. This policy is required. Name the policy `mp_ib_ingest`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "imagebuilder:GetComponent",
"Resource": "*"
}
]
}
```
------
+ Amazon S3 read-access policy, to allow AWS Marketplace to retrieve binaries from an S3 bucket. This policy is only required if your component uses the `S3Download` action module and stores associated binaries in an S3 bucket. Name the policy `mp_ib_s3_read_only`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ListObjectsInBucket",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::bucket_name"
]
},
{
"Sid": "ReadObjectsInBucket",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectAttributes"
],
"Resource": [
"arn:aws:s3:::bucket_name/*"
]
}
]
}
```
------
+ Secrets Manager read-access policy, to allow AWS Marketplace to retrieve secrets stored in Secrets Manager. This policy is only required if your component uses Secrets Manager to store secrets. Name the policy `mp_ib_sm_read_only`. To restrict the policy to just your secret, replace the `*` in the `Resource` section with your secret.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"*"
]
}
]
}
```
------
+ Parameter Store read-access policy, to allow AWS Marketplace to retrieve secrets stored in Parameter Store. This policy is only required if your component uses Parameter Store to store secrets. Name the policy `mp_ib_ssm_parameter_read_only`. To restrict the policy to just your secret, replace the `*` in the `Resource` section with your secret.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": [
"ssm:getParameter"
],
"Resource": [
"*"
]
}
]
}
```
------
## Creating the AWS Marketplace IAM role
Use the following procedure to create an AWS Marketplace IAM role with policies to grant AWS Marketplace access to your component and its dependencies.
**To create the AWS Marketplace IAM role**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the left navigation bar, choose **Roles**.
1. Choose **Create role**.
1. Select **Custom trust policy**.
1. Enter the following statement:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "assets.marketplace.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Choose **Next**.
1. Add the Image Builder get-component policy you created previously. The get-component policy is required. Add the relevant policies for S3, Secrets Manager, and Parameter Store if your component uses these AWS services.
1. Choose **Next**.
1. Enter a role name, such as `MPEC2IBIngestion`.
1. Choose **Create role**.
### Copy AWS Marketplace IAM role ARN
After creating the AWS Marketplace IAM role, copy and save the role ARN. You will use the ARN when publishing the listing using the AWS Marketplace Catalog API.
**To copy the AWS Marketplace IAM role ARN**
1. In the IAM console, in the left navigation bar, choose **Roles**.
1. Choose the AWS Marketplace IAM role you created previously, such as `MPEC2IBIngestion`.
1. On the role detail page, in the **Summary** section, copy the ARN.
## Prepare your Image Builder component listing
Before publishing your AWS Marketplace listing, ensure that you have the following information ready:
+ **Product metadata – **Metadata includes the product logo, product title, End User License agreement, supported instance types, and AWS Region.
+ **Pricing information – ** You can offer your product for free, at an hourly rate, or at an hourly rate with an initial free trial period. Bring your own license (BYOL) is not supported.
+ **Component details – **Details include the component Amazon Resource Number (ARN), usage details, and AWS Identity and Access Management (IAM) role that AWS Marketplace will assume to process your component.
## Publishing your Image Builder component product listing
This topic contains instructions to publish your EC2 Image Builder component listing on AWS Marketplace using the AWS Marketplace Catalog API.
### Prerequisites
Ensure that you have the following before publishing your Image Builder component product listing:
+ Registration as a seller in AWS Marketplace. For more information, refer to [Register as an AWS Marketplace seller](https://catalog.workshops.aws/mpseller/en-US/pre-requisite-register-as-seller).
+ An IAM user with `AWSMarketplaceSellerFullAccess` permission.
+ A publicly accessible Amazon Simple Storage Service (Amazon S3) bucket to host your company logo and EULA, if used in your component. You will enter the URL for the S3 bucket in your `ChangeSet` JSON file.
+ AWS Command Line Interface (AWS CLI). For more information, refer to [What is the AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) in the *AWS Command Line Interface User Guide*.
### Creating an Image Builder component product on AWS Marketplace
To create an EC2 Image Builder component product on AWS Marketplace using the Catalog API, refer to [Create a product](work-with-seller-products.md#create-product).
## Updating Image Builder component product information
You can update information about a Image Builder component product on the AWS Marketplace Management Portal.
**To update Image Builder component product information**
1. Open the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/tour/) and sign in to your seller account.
1. On the **Products** menu, choose **Server**.
1. On the **Server products** page, select the product.
1. On the product detail page, on the **Request changes** menu, choose the item that corresponds to the information you want to update.
1. After submitting any changes, the request will appear on the **Requests** tab in "Under review" status, and will change to "Succeeded" once completed.
## Adding a new version to an existing Image Builder component product
You can add a new version to an Image Builder component product on AWS Marketplace using the AWS Marketplace Catalog API.
**To add a new version**
1. From the AWS Marketplace Management Portal, obtain the Product ID.
1. Open the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/tour/) and sign in to your seller account.
1. On the **Products** menu, choose **Server**.
1. On the **Server products** page, select the product.
1. In the **Product summary**, copy the **Product ID**.
1. Using the following code example, create a changeset file in JSON format. In the example, replace *your-product-ID* with the product ID you obtained in step 1. Replace *new-version-name* with your version title. Replace *new-delivery-option-title* with your delivery option title.
```
[
{
"ChangeType": "AddDeliveryOptions",
"Entity": {
"Identifier": "your-product-ID",
"Type": "AmiProduct@1.0"
},
"DetailsDocument": {
"Version": {
"VersionTitle": "new-version-name",
"ReleaseNotes": "Release notes goes here."
},
"DeliveryOptions": [
{
"DeliveryOptionTitle": "new title",
"Details": {
"Ec2ImageBuilderComponentDeliveryOptionDetails": {
"UsageInstructions": "Test usage instructions for IB",
"AccessRoleArn": "arn:aws:iam::123456789:role/sample",
"ComponentArn": "arn:aws:imagebuilder:us-east-1:123456789:component/sample/2.0.0/1"
}
}
}
]
}
}
]
```
1. Save the changeset file with the name `addIBversion.json`.
1. In your terminal or AWS CloudShell, run the following command:
```
aws marketplace-catalog start-change-set --catalog AWSMarketplace --region us-east-1 --change-set file://addIBversion.json
```
The `start-change-set` command will return a `ChangeSetId` value. To monitor a change set, see [Monitoring a change set](#monitor-changeset).
**Asynchronous Errors**
The following errors are specific to `AddDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
**Note**
The following error codes are specific to the Image Builder delivery method. For existing error messages on fields such as `Usage Instructions`, `Recommended Instance type`, and `AccessRoleArn`, see [Add a new version](work-with-single-ami-products.md#ami-add-version).
| Error code | Error message |
| --- | --- |
| ASSET\$1NOT\$1FOUND | Check if [component arn] exists in [account-id] AWS account and the AccessARN provided [ARN] has permissions to share this Image Builder component with AWS Marketplace. |
| ASSET\$1NOT\$1FOUND | The specified S3 link [x] within the component[x] does not exist. Provide a valid S3 link within the component. |
| DUPLICATE\$1COMPONENT\$1NAME | The component name [x] already exists within the same version. Provide a different component name. |
| DUPLICATE\$1COMPONENT\$1NAME | The component name [x] you provided is already in use by a different product. Provide a different component name. |
| DUPLICATE\$1COMPONENT\$1ARN | The component Arn [x] must be different from Component Arn used in other delivery options of the same version of this product. |
| DUPLICATE\$1COMPONENT\$1ARN | The component ARN [x] must be different from component ARN used in other versions of this product. |
| SCAN\$1ERROR | Fix security vulnerability [y] on Component [x]. |
| ASSET\$1ACCESS\$1EXCEPTION | We don't have the necessary permissions to read the contents from the specified S3 bucket[x]. Ensure the S3 bucket has the appropriate read permissions. |
| ASSET\$1ACCESS\$1EXCEPTION | We don't have the necessary permissions to read the contents of the specified component ARN[x]. Ensure the component ARN has the appropriate read permissions. |
| ASSET\$1ACCESS\$1EXCEPTION | We don't have the necessary permissions to read the contents of the specified package URI [x]. Ensure the package URI has the appropriate read permissions. |
| ASSET\$1ACCESS\$1EXCEPTION | Failed to read from the HTTP source [x]. Verify that the provided HTTP source is correct. |
| INVALID\$1IMAGE\$1BUILDER\$1COMPONENT\$1PACKAGE | Component assets exceed the size limit for ingestion. Reduce the size of S3/web downloads or eliminate unnecessary downloads to proceed. |
| INVALID\$1IMAGE\$1BUILDER\$1COMPONENT\$1PACKAGE | Component assets are taking too long to ingest. Ensure that your network connection is stable and has adequate bandwidth. |
| TOO\$1MANY\$1IMAGE\$1BUILDER\$1COMPONENTS | Max of 5 unique component names are supported per product, restrict the additional delivery option. |
| INCOMPLETE\$1SELLER\$1PUBLIC\$1PROFILE | Your seller public profile is not complete. Complete your public profile before adding versions to the product. |
| INVALID\$1DESCRIPTION | The description is missing. Provide a description with fewer than 1024 characters in component [x]. |
| INVALID\$1COMPONENT\$1NAME | Provide a component name with fewer than [x] characters. |
| INVALID\$1SUPPORTED\$1OS\$1VERSION | The OS version is missing. Provide a valid supported OS version in component [x]. |
| INVALID\$1PATH\$1FORMAT | Step [STEP\$1NAME] in phase [PHASE\$1NAME] is not allowed to use S3 or web URLs for the InstallMSI/UninstallMSI actions. Ensure that the path specified is a valid local path accessible from the system executing the action. |
| INCOMPATIBLE\$1OS\$1TYPE | The specified component OS type[x] is not compatible with the platform of the base image. Provide an OS type that is compatible with the base image. |
| ASSET\$1ACCESS\$1EXCEPTION | We don't have the necessary permissions to read the contents from the specified SSM parameter [x]. Ensure that the IAM access role provided in the API input has the required read permissions. |
| ASSET\$1ACCESS\$1EXCEPTION | We don't have the necessary permissions to read the contents from the specified SecretsManager secret [x]. Ensure that the IAM access role provided in the API input has the required read permissions. |
| INVALID\$1IB\$1COMPONENT\$1BUILD\$1VERSION | Component ARN [x] has a build version of [y]. AWS Marketplace only supports build version 1. Create a new EC2 Image Builder version with Build versions 1, and try again on AWS Marketplace |
| INVALID\$1IB\$1COMPONENT\$1PARAMETER | Unable to parse the SSM parameter in input [x] for component [y]. |
| INVALID\$1IB\$1COMPONENT\$1PARAMETER | Unable to parse the SecretsManager secret in input [x] for component [y]. |
| MISSING\$1IB\$1COMPONENT\$1PARAMETER | Parameter not found in component [x] for input [y] |
| INVALID\$1IB\$1COMPONENT\$1PARAMETER | Provide a default value for parameter [x] in component [y]. |
| FAILED\$1LAUNCH\$1TEST | The launch test for component [x] has failed. Error message: [z] |
| SSHAuthFailedForUserAndKeypair | Unable to log into the instance with OS default username [X]. |
| INVALID\$1IB\$1COMPONENT | A component build phase is required. Add a valid build phase to component [x] |
| DUPLICATE\$1VERSION\$1TITLE | The version title must be different from any other version titles of this product. |
| INVALID\$1VERSION\$1TITLE | Remove spaces before the trademark symbol. |
| INVALID\$1VERSION\$1TITLE | Remove unsupported characters: [x, y, z] |
| INVALID\$1VERSION\$1TITLE | Remove spaces from the beginning of the version title. |
| INVALID\$1VERSION\$1TITLE | Provide version title with fewer than [x] characters. |
| INVALID\$1RELEASE\$1NOTES | Remove spaces before the trademark symbol. |
| INVALID\$1RELEASE\$1NOTES | Remove unsupported characters: [x, y, z] |
| INVALID\$1RELEASE\$1NOTES | Remove spaces from the beginning of release notes. |
| INVALID\$1RELEASE\$1NOTES | Provide release notes with fewer than (x) characters. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove spaces before the trademark symbol. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove unsupported characters: [x, y, z] |
| INVALID\$1USAGE\$1INSTRUCTIONS | Provide usage instructions with fewer than (x) characters. |
| DUPLICATE\$1DELIVERY\$1OPTION\$1TITLES | Provide unique delivery option title. |
| INVALID\$1DELIVERY\$1OPTION\$1TITLES | Delivery option title already exists, retry with a different title. |
## Updating information about an existing version
**To update information about an existing version**
1. From the AWS Marketplace Management Portal, obtain the Product ID.
1. Open the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/tour/) and sign in to your seller account.
1. On the **Products** menu, choose **Server**.
1. On the **Server products** page, select the product.
1. In the **Product summary**, copy the **Product ID**.
1. In your terminal, run the following command. In the command, replace *your-product-ID* with the ID you obtained in step 1.
```
aws marketplace-catalog describe-entity --catalog AWSMarketplace --region us-east-1 --entity-id 'your-product-ID'
```
1. In the output returned, go to the `DetailsDocument`, `Versions` section. Copy the `DeliveryOptions`, `Id` value for the version you want to update.
1. Using the following code example, create a changeset file in JSON format. In the example, replace *your-product-ID* with the product ID you obtained in step 1. Replace *your-release-notes* with your release notes. Replace *your-delivery-option-ID* with the ID of the delivery option you obtained in step 3. Replace *your-usage-instructions* with your usage instructions.
```
[
{
"ChangeType": "UpdateDeliveryOptions",
"Entity": {
"Identifier": "your-product-ID",
"Type": "AmiProduct@1.0"
},
"DetailsDocument": {
"Version": {
"ReleaseNotes": "your-release-notes"
},
"DeliveryOptions": [
{
"Id": "your-delivery-option-ID",
"Details": {
"Ec2ImageBuilderComponentDeliveryOptionDetails": {
"UsageInstructions": "your-usage-instructions"
}
}
}
]
}
}
]
```
1. Save the changeset file with the name `updateVersionInfo.json`.
1. In your terminal or AWS CloudShell, run the following command:
```
aws marketplace-catalog start-change-set --catalog AWSMarketplace --region us-east-1 --change-set file://updateVersionInfo.json
```
The `start-change-set` command will return a `ChangeSetId` value. To monitor a change set, see [Monitoring a change set](#monitor-changeset).
## Restricting an Image Builder component product version
Restricting a version makes it unavailable to buyers. You can restrict a version of your Image Builder component product on AWS Marketplace using the AWS Marketplace Catalog API. You must keep at least one version of your product unrestricted on AWS Marketplace. You can't restrict access to the only public version.
**To update information about an existing version**
1. From the AWS Marketplace Management Portal, obtain the Product ID.
1. Open the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/tour/) and sign in to your seller account.
1. On the **Products** menu, choose **Server**.
1. On the **Server products** page, select the product.
1. In the **Product summary**, copy the **Product ID**.
1. In your terminal, run the following command. In the command, replace *your-product-ID* with the ID you obtained in step 1.
```
aws marketplace-catalog describe-entity --catalog AWSMarketplace --region us-east-1 --entity-id 'your-product-ID'
```
1. In the output returned, go to the `DetailsDocument`, `Versions` section. Copy the `DeliveryOptions`, `Id` value for the version you want to update.
1. Using the following code example, create a changeset file in JSON format. In the example, replace *your-product-ID* with the product ID you obtained in step 1. Replace *your-delivery-option-ID* with the ID of the delivery option you obtained in step 3.
```
[
{
"ChangeType": "RestrictDeliveryOptions",
"Entity": {
"Identifier": "your-product-ID",
"Type": "AmiProduct@1.0"
},
"DetailsDocument": {
"DeliveryOptionIds": [
"your-delivery-option-ID"
]
}
}
]
```
1. Save the changeset file with the name `restrictec2ibversion.json`.
1. In your terminal or AWS CloudShell, run the following command:
```
aws marketplace-catalog start-change-set --catalog AWSMarketplace --region us-east-1 --change-set file://restrictec2ibversion.json
```
The `start-change-set` command will return a `ChangeSetId` value. To monitor a change set, see [Monitoring a change set](#monitor-changeset).
## Monitoring a change set
The `start-change-set` command will return a `ChangeSetId` value. You can monitor change set progress in the following ways:
+ Run the following command in your terminal. In the command. replace *changeset-ID* with the `ChangeSetId` value returned by the `start-change-set` command.
```
aws marketplace-catalog describe-change-set ‐‐catalog AWSMarketplace ‐‐change-set-id changesetID
```
+ View the request status on the **Requests** tab in the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/).
## Securing software downloads
To safeguard ISV software intellectual property and ensure stable, consistent software delivery to AWS Marketplace buyers, AWS Marketplace automatically parses `S3Download` and `WebDownload` action modules in your component. The referenced files are then securely stored in a private Amazon S3 bucket managed by AWS Marketplace. To opt out of this ingestion process and manage software downloads independently, run bash scripts that use the `wget` or `curl` download commands.
# Work with container-based products using the AWS Marketplace APIs
You can use the AWS Marketplace Catalog API to automate tasks for working with container-based products.
For information about creating a container-based product using the Catalog API, see [Create a product](work-with-seller-products.md#create-product).
The following topics describe how to use the Catalog API to perform actions on your container-based products:
**Topics**
+ [Add a new version](#container-add-version)
+ [Update the visibility for an Amazon EKS add-on](#update-delivery-option-visibility)
+ [Create repositories and resources](#container-repos)
+ [Update version information](#container-update-version)
+ [Restrict a version](#container-restrict-version)
## Add a new version
If you already have a container-based product in AWS Marketplace, you can use the AWS Marketplace Catalog API to add a new version. This requires that you have already created repositories in AWS Marketplace for each container image or artifact that is part of your product, and that you can copy them from your local Docker and Helm files.
**Note**
For details about creating a container-based product using the AWS Marketplace Management Portal, see [Getting started with container products](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html) in the *AWS Marketplace Seller Guide*.
For details about adding a new version, including creating repositories and building Docker and Helm files into those repositories, by using the AWS Marketplace Management Portal, see [Add a new version of your product](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-add-version) in the *AWS Marketplace Seller Guide*.
If you have not already created new repositories, you can create them using the Catalog API, see [Create repositories and resources](#container-repos).
To add a new version, call the `StartChangeSet` API operation with the `AddDeliveryOptions` change type, as shown in the following example.
**Note**
A version of a container-based product is made up of one or more delivery options. For example, you might have two delivery options, one that works with a noSQL database, and another that works with MySQL, so that your users can choose how they want to work with your product. You create the version of your product and add multiple delivery options in a single request with `AddDeliveryOptions`.
**Container Image Delivery Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddDeliveryOptions",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12",
"Type": "ContainerProduct@1.0"
},
"DetailsDocument":
{
"Version":
{
"VersionTitle": "1.1",
"ReleaseNotes": "Minor bug fix"
},
"DeliveryOptions":
[
{
"DeliveryOptionTitle": "EKS Container image only delivery option",
"Details":
{
"EcrDeliveryOptionDetails":
{
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"DeploymentResources":
[
{
"Name": "HelmDeploymentTemplate",
"Url": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
}
],
"CompatibleServices":
[
"EKS"
],
"Description": "Sample Description",
"UsageInstructions": "helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
}
}
}
]
}
}
]
}
```
**Amazon Bedrock AgentCore Runtime delivery request syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddDeliveryOptions",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12",
"Type": "ContainerProduct@1.0"
},
"DetailsDocument":
{
"Version":
{
"VersionTitle": "1.1",
"ReleaseNotes": "Minor bug fix"
},
"DeliveryOptions":
[
{
"DeliveryOptionTitle": "Amazon Bedrock AgentCore Runtime Delivery Option",
"Details":
{
"EcrDeliveryOptionDetails":
{
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"CompatibleServices":
[
"Bedrock-AgentCore"
],
"AgenticType":
[
"AGENT"
],
"Description": "Sample Description",
"UsageInstructions": "To launch and invoke this agent on Amazon Bedrock AgentCore Runtime",
"EnvironmentVariables":
[
{
"Name": "HTTP_PORT",
"Description": "Port of the server",
"DefaultValue": "8080"
},
{
"Name": "API_KEY",
"Description": "Provide your unique API key here."
}
]
}
}
}
]
}
}
]
}
```
**Helm Chart Delivery Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddDeliveryOptions",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12",
"Type": "ContainerProduct@1.0"
},
"DetailsDocument":
{
"Version":
{
"VersionTitle": "1.1",
"ReleaseNotes": "Minor bug fix"
},
"DeliveryOptions":
[
{
"DeliveryOptionTitle": "HelmChartDeliveryOption",
"Details":
{
"HelmDeliveryOptionDetails":
{
"CompatibleServices":
[
"EKS",
"EKS-Anywhere"
],
"ContainerImages":
[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
],
"HelmChartUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1",
"Description": "Helm chart description",
"UsageInstructions": "Usage instructions",
"MarketplaceServiceAccountName": "Service account name",
"ReleaseName": "Optional release name",
"Namespace": "Optional Kubernetes namespace",
"OverrideParameters":
[
{
"Key": "HelmKeyName1",
"DefaultValue": "${AWSMP_LICENSE_SECRET}"
},
{
"Key": "HelmKeyName2",
"DefaultValue": "${AWSMP_SERVICE_ACCOUNT}"
}
]
}
}
}
]
}
}
]
}
```
**Amazon EKS Add-On Delivery Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "AddDeliveryOptions",
"Entity": {
"Type": "ContainerProduct@1.0",
"Identifier": "$CreateProductChange.Entity.Identifier"
},
"DetailsDocument": {
"Version": {
"VersionTitle": "1.1",
"ReleaseNotes": "New Add-on Release"
},
"DeliveryOptions": [
{
"DeliveryOptionTitle": "AWS Marketplace Test AddOn from CAPI 1",
"Visibility": "Limited",
"Details": {
"EksAddOnDeliveryOptionDetails": {
"ContainerImages": [
"111122223333.dkr.ecr.us-east-1.amazonaws.com/test-seller/canary-test-repo-product-6:mongo"
],
"HelmChartUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/rocket/rocket-product-helm:1.0",
"Description": "Description for delivery option provided by ISV",
"UsageInstructions": "Usage instructions with launch instructions",
"AddOnName": "aws-mp-test",
"AddOnVersion": "1.2.1",
"AddOnType": "networking",
"CompatibleKubernetesVersions": [
"1.25",
"1.26"
],
"SupportedArchitectures": [
"amd64",
"arm64"
],
"Namespace": "my-test-namespace",
"EnvironmentOverrideParameters": [
{
"Key": "cluster-name",
"Value": "${AWS_EKS_CLUSTER_NAME}"
},
{
"Key": "region-name",
"Value": "${AWS_REGION}"
}
]
}
}
}
]
},
"ChangeName": "PublishAddonNew"
}
]
}
```
Provide information for the fields to add the `AddDeliveryOptions` change type:
+ `Entity` (object) (required) – Your container-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `ContainerProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request. It includes all the information about the version that you are adding. This field is a string field.
+ `Version` (object) – Details about the version that you are adding to your product.
+ `VersionTitle` (string) – The title of the version that you are creating. Typically this is a description of the version, like **Version 1.1** or simply **1.1**. Your buyers will be able to choose the version to deploy from a list of version titles.
+ `ReleaseNotes` (string) – The detailed notes about this version. Must be less than 30,000 characters.
+ `DeliveryOptions` (array of objects) – An array of delivery options, where each is a method of delivery for your product version. For example, if you have one delivery option for Amazon Elastic Container Service (Amazon ECS) and another for Amazon Elastic Kubernetes Service (Amazon EKS), you must have two delivery options.
+ `DeliveryOptionTitle` (string) – A short description that helps your buyer to choose between your delivery options.
+ `Details` (object) – The resources used for this delivery option. This is a details field within the details field. You do not need to doubly escape characters in this field.
+ `AddOnName – `A unique add-on name that buyers will see in the Amazon EKS catalog. This name will add a prefix later using `SellerAlias`. For example, where `isv-alias_` is the ISV provided add-on name.
+ `AddOnType – `The type of add-on chosen from a list of supported values from Amazon EKS: Gitops \$1 monitoring \$1 logging \$1 cert-management \$1 policy-management \$1 cost-management \$1 autoscaling \$1 storage \$1 kubernetes-management \$1 service-mesh \$1 etcd-backup \$1 ingress-service-type \$1 load-balancer \$1 local-registry\$1 networking \$1 Security \$1 backup \$1 ingress-controller \$1 observability
+ `AddOnVersion – `A semantic version so that buyer can choose a specific version of AddOn they need to install or upgrade.
+ `CompatibleKubernetesVersions` – The Amazon EKS Kubernetes versions that this software is compatible with.
+ `CompatibleServices` (array of strings) – An array of services that the release is compatible with. Valid options: `ECS`, `EKS`, `ECS-Anywhere`, `EKS-Anywhere`, and `Bedrock-AgentCore`.
+ `ContainerImages` (array of strings) – An array of container image URLs used by this version. The path will be the repository that you have uploaded the image to, with the tag for the image used by this version. The list must include all needed images, even images that have not changed from previous versions. See the next section for information about creating repositories using the Catalog API.
+ `Description` (string) – A longer description of the delivery option to give details to your buyer. You can also include a link to more instructions provided elsewhere.
+ `EcrDeliveryOptionDetails` – `AgenticType` – The type of runtime agent. Valid options: `AGENT`, `MCP_SERVER`, or `A2A_SERVER`.
+ `EcrDeliveryOptionDetails` – `EnvironmentVariables` – List of environment variables that are required by the AgentCore Runtime container and that will be pre-populated for buyers upon deployment. For each variable, provide an object with the *name* as expected by your container, a *description*, and an optional *defaultValue*. For variables such as credentials or API keys that are unique, do not provide a default value. You can use the description to specify details about the variable as well as possible values. All of the provided variables with their default values will be pre-populated when buyers launch your product.
+ `EcrDeliveryOptionDetails – ``DeploymentResources (array of objects)` – An array of other resources needed for the version, such as Helm charts. Each resource includes a `Name` to describe it, and a `URL` that points at the resource.
+ `EnvironmentOverrideParameters – `List of system parameters to be used by the add-on. Some of the ISV provided AddOn (HelmChart) might require configurations with information derived from the Amazon EKS execution environment state (/system information). For example, `EksClusterRegion`, `EKSClusterName`, and others. You can avoid additional actions from Buyer by dynamically substituting these values at Amazon EKS AddOn launch. Amazon EKS System already supports automatic substitutions of system param for add-ons. AWS Marketplace ISV experience can be extended to collect this params which would require substitution.
The generic system information to be substituted can be indicated by providing a AWS Marketplace specified constant following convention similar to Helm substitution. The supported values are `${AWS_REGION}` and `${AWS_EKS_CLUSTER_NAME}`.
```
"EnvironmentOverrideParameters" : [ {
"Key" : "my-field.region"
"Value" : "${AWS_REGION}"
},
{
"Key" : "my-second-field"
"Value" : "${AWS_EKS_CLUSTER_NAME}"
},
```
+ `HelmDeliveryOptionDetails` – `HelmChartUri (string)` – The URL to the Helm chart hosted in Amazon ECR that the buyer will install to launch the software.
+ `HelmDeliveryOptionDetails – ``MarketplaceServiceAccountName (string)` – *Optional * – The name of the Kubernetes service account. The service account will be used to connect to AWS Identity and Access Management (IAM) for permissions to call AWS services.
+ `HelmDeliveryOptionDetails – ``ReleaseName (string)` – *Optional * – The name for the Helm release provided to the `helm install` command that buyers use to launch the software. If not included, Helm will provide an automatically generated release name for you.
+ `HelmDeliveryOptionDetails – ``Namespace (string)` – *Optional * – The Kubernetes namespace where the Helm chart will be installed.
+ `HelmDeliveryOptionDetails – ``OverrideParameters (array of objects)` – Parameters that will be used in the Helm commands that launch the application. Buyers can override the default values.
**Note**
For Amazon EKS Anywhere products, provide at least 1 override parameter for the license secret. Provide `DefaultValue` of `"${AWSMP_LICENSE_SECRET}"`.
For paid products, provide at least 1 override parameter for service account configuration. Provide `DefaultValue` of `"${AWSMP_SERVICE_ACCOUNT}"`.
+ `Key` (string) – The key for the parameter in dot notation (override.example.key).
+ `DefaultValue` (string) – The default value for this override parameter.
+ `Namespace – `The ISV provided namespace for add-on installation.
+ `SupportedArchitectures – `The list of supported architectures, like amd64 and arm64.
+ `UsageInstructions` (string) – Provide instructions about the usage for this delivery option. Can be up to 4,000 characters.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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 container images and other information to ensure that it meets the [AWS Marketplace guidelines for container products](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-policies.html). This process can take a few minutes to hours, depending on the number and size of your containers.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
For more information about change sets, see [Working with change sets](catalog-apis.md#working-with-change-sets). For more information about errors in seller product change sets, see [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors).
**Asynchronous Errors**
The following errors are specific to `AddDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT\$1STATUS | Use an existing limited or public product. |
| INCOMPATIBLE\$1SERVICES | The service list contains incompatible services. [incompatible\$1services] Provide a valid list of compatible services. |
| NO\$1SERVICE\$1SPECIFIED | Provide at least 1 compatible service. |
| DUPLICATE\$1COMPATIBLE\$1AWS\$1SERVICES | The service list contains duplicate entries. Remove them. Each entry must be unique. |
| INVALID\$1VERSION\$1TITLE | Remove spaces before the trademark symbol. |
| INVALID\$1VERSION\$1TITLE | Remove the following unsupported characters: [x, y, z] |
| INVALID\$1VERSION\$1TITLE | Remove spaces from the beginning of the version title. |
| INVALID\$1VERSION\$1TITLE | Provide version title with fewer than [x] characters. |
| DUPLICATE\$1VERSION\$1TITLE | The version title [duplicate\$1version\$1title] is a duplicate. Remove or change the title. |
| INVALID\$1RELEASE\$1NOTES | Remove spaces before the trademark symbol. |
| INVALID\$1RELEASE\$1NOTES | Remove unsupported characters: [x, y, z] |
| INVALID\$1RELEASE\$1NOTES | Remove spaces from the beginning of release notes. |
| INVALID\$1RELEASE\$1NOTES | Provide release notes with fewer than (x) characters. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove spaces before the trademark symbol. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove unsupported characters: [x, y, z] |
| INVALID\$1USAGE\$1INSTRUCTIONS | Provide usage instructions with fewer than (x) characters. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Provide usage instructions. |
| MISSING\$1CONTAINER\$1IMAGES | Provide at least 1 container image. |
| NO\$1LICENSE\$1SECRET\$1KEYS | For Amazon EKS Anywhere products, provide 1 override parameter for license secret. Needs DefaultValue of "\$1\$1AWSMP\$1LICENSE\$1SECRET\$1", see example in section. |
| TOO\$1MANY\$1CONTAINER\$1IMAGES | Provide fewer than 50 container images. |
| DUPLICATE\$1CONTAINER\$1IMAGES | The container image list contains duplicate images: [duplicate\$1images]. Provide a list with unique images. |
| INVALID\$1CONTAINER\$1IMAGES | Provide a valid URI for the container image. |
| INVALID\$1CONTAINER\$1IMAGE\$1URI | The image [invalid\$1image\$1uri] doesn't have access to this product. Upload the image to its corresponding product repository. For information about uploading, see [Getting started with container products](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html). |
| INVALID\$1CONTAINER\$1IMAGE\$1TAG | Avoid using 'latest' tag. |
| DUPLICATE\$1DELIVERY\$1OPTION\$1TITLES | Duplicate delivery option titles: [duplicate\$1titles]. Remove the duplicates |
| INVALID\$1DELIVERY\$1OPTION\$1TITLES | The delivery option titles [existing\$1titles] already exist. Provide a different title. |
| INVALID\$1FULFILLMENT\$1OPTION\$1TITLE | Provide delivery option title with fewer than (x) characters. |
| NO\$1SERVICE\$1ACCOUNT\$1CONFIGURATION | For paid products, provide 1 override parameter for service account configuration. Needs DefaultValue of "\$1\$1AWSMP\$1SERVICE\$1ACCOUNT\$1", see example in section. |
| INVALID\$1DETAILS | Provided Details is not valid. |
| EMPTY\$1RESOURCE\$1NAME | Provide resource name. |
| EMPTY\$1RESOURCE\$1URL | Provide resource URL. |
| INVALID\$1RESOURCE\$1NAME | Provide resource name with fewer than 256 characters. |
| INVALID\$1RESOURCE\$1URL | Provide resource URL with fewer than 256 characters. |
| INVALID\$1SHORT\$1DESCRIPTION | Provide a short description with fewer than 1,000 characters. |
| INVALID\$1SHORT\$1DESCRIPTION | Provide short description. |
| SCAN\$1ERROR | Fix security vulnerability ""[y]"" on Image ""[x]"". |
| IMAGE\$1NOT\$1FOUND | The public image URI [invalid\$1image\$1uri] is invalid. Provide a valid URI. |
| INVALID\$1ARN | Provide a valid ARN for image access. |
| IMAGE\$1INACCESSIBLE | Provide a valid ARN for image access. |
| DUPLICATE\$1ADDON\$1NAME | The AddOn name you provided is already in use by a different product. Provide a different name. |
| DUPLICATE\$1ADDON\$1VERSION | The add-on version title [duplicate\$1version\$1title] is already in use. Provide a different title. |
| INVALID\$1ADDON\$1TYPE | The add-on types [invalid\$1types] are invalid. Provide a type from the supported list: [eks\$1addon\$1do\$1supported\$1types]. |
| INVALID\$1KUBERNETES\$1VERSION | The Kubernetes versions [invalid\$1versions] are invalid. Provide versions from the supported list: [eks\$1addon\$1do\$1supported\$1kubernetes\$1versions]. |
| DUPLICATE\$1KUBERNETES\$1VERSIONS | Duplicate Kubernetes versions: [duplicate\$1versions]. Provide a list with unique versions. |
| INVALID\$1ARCHITECTURE | The architectures [invalid\$1architectures] are invalid. Provide architectures from the Amazon EKS supported architectures : [eks\$1addon\$1do\$1supported\$1architectures]. |
| DUPLICATE\$1SUPPORTED\$1ARCHITECTURES | Duplicate architectures: [duplicate\$1architectures]. Provide a list of unique, supported architectures. |
| INVALID\$1VISIBILITY\$1STATE | The states [invalid\$1states] are invalid for the \$1EKS\$1DO\$1 delivery option. Provide a valid visibility state from the following allowed values: Limited. |
| INVALID\$1ENVIRONMENT\$1OVERRIDE\$1PARAMETER\$1VALUE | The override parameter values [invalid\$1values] are invalid. Provide a valid value from the following list: [eks\$1addon\$1do\$1environment\$1override\$1parameter\$1values]. |
| DUPLICATE\$1ENVIRONMENT\$1OVERRIDE\$1PARAMETER\$1KEY | The environment override parameters contain duplicate keys: [duplicate\$1keys]. Remove them. |
| TOO\$1MANY\$1EKS\$1ADDON\$1DELIVERY\$1OPTIONS | Provide only one Amazon EKS add-on delivery option for the version. |
| INCOMPATIBLE\$1ADDON\$1NAME | The add-on name [provided\$1name] does not match the existing name. Reuse the existing name from the public version, or previous versions, of this add-on. You can only use one add-on name for each product. |
| INCOMPATIBLE\$1ADDON\$1TYPE | The add-on type [provided\$1type] does not match the existing type. Reuse the existing type from the public version, or previous versions, of this add-on. You can only use one add-on type for each product. |
| INCOMPATIBLE\$1ADDON\$1NAMESPACE | The add-on namespace [provided\$1namespace] does not match the existing namespace . Reuse the existing namespace from the public version, or previous versions, of this add-on. You can only use one add-on namespace for each product. |
| INVALID\$1HELM\$1CHART\$1URI | The Helm chart URI [invalid\$1uri] is invalid. Provide a URI in the SemVer 2 format. |
| INCOMPATIBLE\$1HELM\$1OBJECTS(INVALID\$1HELM\$1OBJECTS) | Provide a Helm chart without using the following unsupported Helm Objects: . |
| INVALID\$1DEPENDENT\$1HELM\$1CHARTS | Provide a Helm chart that contains the following dependent charts directly in the parent chart directory and not externally sourced: . |
| INVALID\$1HELM\$1SENSITIVE\$1CONFIG | Provide an advanced configuration schema without sensitive information or secrets. Keywords: |
| INVALID\$1HELM\$1UNDECLARED\$1IMAGES | Provide the following Helm chart images within the delivery option of the request: . |
| INVALID\$1HELM\$1CHART\$1IMAGES | Provide a Helm chart containing images within repositories created via the AddRepositories change type. External images: . |
| INVALID\$1HELM\$1LINT | Provide a Helm chart that successfully passes Helm lint. |
| INVALID\$1HELM\$1TEMPLATE | Provide a Helm chart that successfully passes Helm template. |
| INVALID\$1HELM\$1CHART | Provide a Helm chart that adheres to AWS Marketplace guidance identified in [Helm Charts bulleted list](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-policies.html) in the AWS Marketplace Seller Guide. |
| INVALID\$1ADDON\$1NAME | Provide an AddOn name that follows the following regex pattern: xx |
| INVALID\$1ADDON\$1NAMESPACE | The namespace values [invalid\$1namespaces] are invalid. The namespace must follow the \$1EKS\$1ADD\$1ON\$1NAMESPACE\$1REGEX\$1 regular expression. For example, namespace, namespace-test. |
| INVALID\$1ADDON\$1NAME\$1PATTERN | Provide an add-on name that starts with a letter or digit, and then a combination of letters, digits, and hyphens. For example, test-addon, eksaddon |
| INVALID\$1ADDON\$1VERSION\$1PATTERN | Provide an add-on version using the following pattern: ".." (for example, 1.2.3, 0.1.2, 0.1.1) |
| EMPTY\$1DELIVERY\$1OPTION\$1IDS | Provide a list of delivery option IDs. |
| INVALID\$1DELIVERY\$1OPTIONS\$1INPUT | The list contains one or more invalid delivery options. Provide a valid list, and ensure that each option has a single delivery method. |
| OVERRIDE\$1PARAMETER\$1KEYS\$1CONTAINS\$1SPECIAL\$1CHARS | The override parameter keys [invalid\$1keys] contain invalid characters. You keys must use only letters, numbers, double quotes (“ ”) and plus signs (\$1). |
| INVALID\$1CONTAINER\$1IMAGE\$1REPOSITORY | The repositories [invalid\$1repositories] are invalid. Provide repositories created through the AddRepositories change type. |
| INVALID\$1CONTAINER\$1IMAGE\$1TAG\$1FORMAT | The container image tag [invalid\$1image\$1tag] is invalid. Provide a tag conforming to the \$1CONTAINER\$1IMAGE\$1TAG\$1REGEX\$1 regular expression. |
| DUPLICATE\$1OVERRIDE\$1PARAMETER\$1KEYS | The override parameters contain duplicate keys [duplicate\$1keys]. Remove the duplicates. |
| UNSUPPORTED\$1CONTAINER\$1IMAGE\$1URI | The container image [unsupported\$1image] is unsupported. Provide an image that follows the [Image Manifest V 2, Schema 1](https://docker-docs.uclv.cu/registry/spec/manifest-v2-1/). |
| DUPLICATE\$1REPOSITORY\$1NAMES | Duplicate repository names: [duplicate\$1repo\$1names]. Provide unique names. |
| INVALID\$1NAMESPACE | The namespace values [invalid\$1namespaces] are invalid. Provide values that conform to the \$1HELM\$1RELEASE\$1PARAM\$1REGEX\$1 regular expression. |
| INVALID\$1RELEASE\$1NAME | The releaseName values [invalid\$1release\$1names] are invalid. Provide values that conform to the \$1HELM\$1RELEASE\$1PARAM\$1REGEX\$1 regular expression. |
| OVERRIDE\$1PARAMETER\$1KEYS\$1CONTAINS\$1RESERVED\$1PARAMETER\$1KEYS | The override parameter key for delivery option titles [invalid\$1keys] is reserved. Reserved keys: [reserved\$1param\$1keys]. Provide a different key. |
## Update the visibility for an Amazon EKS add-on
You can use the Catalog API to update visibility for an Amazon EKS add-on delivery option of your product version in AWS Marketplace. Container and Helm delivery options for your container product are automatically created with ‘Public’ visibility status.
**Note**
The ability to update visibility of your product version is supported only for the Amazon EKS add-on delivery option from the listed versions. If your product isn't 'Public' already, submit a request to publish the product with 'Public' visibility status by using the AWS Marketplace Management Portal.
By default, when you create a version with the Amazon EKS add-on delivery option, it's published in ‘Limited’ status. A ‘Limited’ status means the product isn't publicly available across all the Regions for your buyers to use and deploy in an Amazon EKS cluster. You can update the visibility of the delivery option from ‘Limited’ to ‘Public’ by calling the `StartChangeSet` API operation with the `UpdateDeliveryOptionsVisibility` change type. Specify the `DeliveryOptions Id` from your product version that corresponds to the Amazon EKS add-on delivery option.
**Request Syntax**
```
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateDeliveryOptionsVisibility",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "ContainerProduct@1.0"
},
"DetailsDocument":
{
"DeliveryOptions":
[
{
"Id": "do-1234567891234567891234",
"TargetVisibility": "Public"
}
]
}
}
]
}
```
To add the `UpdateDeliveryOptionsVisibility` change type, provide information for the following fields :
+ `Entity` (object) (required) – Your container-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product uses: `ContainerProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request, including the information about the repositories that you want to create. The following fields are all required.
+ `DeliveryOptions` (list of objects) – List of `DeliveryOption` objects, including the details of each:
+ `Id` (string) – Unique identifier for the `DeliveryOption`. (To get the unique identifier for the `DeliveryOption`, call the `DescribeEntity` action on the product that you're updating.
+ `TargetVisibility` – The intended new visibility of the product.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set.
```
{
"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 container images and other information to ensure that it meets the [AWS Marketplace guidelines for container products](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-policies.html). This process can take a few minutes to hours, depending on the number and size of your containers.
You can check the status of the request through the AWS Marketplace Management Portal, or through the AWS Marketplace Catalog API by using the `[https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
For more information about change sets, see [Working with change sets](catalog-apis.md#working-with-change-sets). For more information about errors in seller product change sets, see [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors).
**Asynchronous Errors**
The following table shows errors that are specific to `AddDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| EMPTY\$1DELIVERY\$1OPTION\$1IDS | Provide a list of delivery option IDs. |
| INVALID\$1VISIBILITY\$1STATE | The TargetVisibility option you provided is not supported. Please try again with an allowed option. The allowed option(s) are: Public |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | You provided invalid delivery option details. Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| DUPLICATE\$1DELIVERY\$1OPTION\$1IDS | Duplicate delivery option IDs: [duplicate\$1ids]. Provide unique delivery option IDs. |
| AUDIT\$1ERROR | You haven't completed independent software vendor (ISV) testing for all compatible Amazon EKS cluster versions for your Amazon EKS add-on version(s). You must complete testing before we can release the delivery option(s). |
| INVALID\$1DELIVERY\$1OPTION\$1TYPE | The delivery option type you provided is not valid. Ensure that your delivery option is of type: EksAddOn and try again. |
| INCOMPATIBLE\$1HELM\$1OBJECTS | Provide a Helm chart without unsupported Helm Objects: Unsupported Helm objects are as follows: all Release objects (except .Name and .Namespace), Helm hooks, and lookup functions. |
| INCOMPATIBLE\$1ADDON\$1NAME | The add-on name [provided\$1name] does not match the public version name. Update the public name before releasing. |
| NCOMPATIBLE\$1ADDON\$1TYPE | The add-on types don't match. Reuse the existing add-on type from the public add-on version or previous add-on versions of this product. Only one add-on is supported for each product. |
| INCOMPATIBLE\$1ADDON\$1NAMESPACE | The provided add-on namespace [provided\$1namespace] does not match the public version namespace. Update the add-on namespace before releasing. |
## Create repositories and resources
To create a new version of a container-based product, you must have the resources for the version available in AWS Marketplace repositories. You create the repositories and then push (upload) the Docker (and Helm) resources into the repositories. To learn how to create the repositories through the AWS Marketplace Management Portal, see [ Add a new version of your product](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html#container-add-version) in the *AWS Marketplace Seller Guide*.
To create new repositories, call `StartChangeSet` with the `AddRepositories` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "AddRepositories",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12",
"Type": "ContainerProduct@1.0"
},
"DetailsDocument":
{
"Repositories":
[
{
"RepositoryName": "new-repo-1",
"RepositoryType": "ECR"
},
{
"RepositoryName": "new-repo-2",
"RepositoryType": "ECR"
}
]
}
}
]
}
```
Provide information for the fields to add the `AddRepositories` change type:
For more information about creating repositories, see [ Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-version) in the *AWS Marketplace Seller Guide*.
+ `Entity` (object) (required) – Your container-based product.
+ **Identifier** (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `ContainerProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request. It includes the information about the repositories that you want to create. The included fields are all required.
+ `Repositories` (array of structures) – A list of repository objects. Each repository object includes a name and type.
+ `RepositoryName` (string) – The name of the repository to create.
+ `RepositoryType` (string) – The type of the repository to create. The only allowed value is `ECR`.
**Note**
You can have up to 70 repositories per product, although you can add multiple resources, and versions of resources, to a single repository by giving them different tags when you push them.
After you create one or more repositories, you add your resources to the repositories. For information about how to push resources to repositories, see [ Pushing an image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-push.html) in the *Amazon Elastic Container Registry User Guide*. For information about the specific push commands needed for one of your repositories, see [ Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-version) in the *AWS Marketplace Seller Guide*.
**Asynchronous Errors**
The following errors are specific to `AddRepositories` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1ECR\$1REPOSITORY\$1NAME | Provide repository name in the format: 'nginx-web-app' |
| DUPLICATE\$1ECR\$1REPOSITORY\$1NAME | The repository [duplicate\$1repo\$1names] already exists. Choose a different name. |
| MISSING\$1REPOSITORY\$1INFORMATION | Provide at least 1 repository name. |
| INVALID\$1ECR\$1REPOSITORY\$1NAME | Maximum character length 256 reached. Character length count is inclusive of the seller namespace. |
## Update version information
You can use the Catalog API to update the details of an existing version of your container-based product in AWS Marketplace.
**Note**
When a product is publicly available, you cannot update the version title, container images, delivery option title, or deployment resources for the version. If you need to update these aspects of a product, create a new version instead.
To update an existing version of your container-based product, call the `StartChangeSet` API operation with the `UpdateDeliveryOptions` change type, as shown in the following example. This updates the detail information for the delivery options that you specify, as well as the associated version. You must include at least one delivery option.
**Container Image Delivery Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog":"AWSMarketplace",
"ChangeSet":[
{
"ChangeType":"UpdateDeliveryOptions",
"Entity":{
"Identifier":"example1-abcd-1234-5ef6-7890abcdef12",
"Type":"ContainerProduct@1.0"
},
"DetailsDocument":{
"Version":{
"ReleaseNotes":"New release notes",
"VersionTitle":"Version 1.2"
},
"DeliveryOptions":[
{
"Id":"example4-2222-cccc-2222-cccccccccccc",
"Details":{
"EcrDeliveryOptionDetails":{
"DeliveryOptionTitle":"New Delivery Option Title",
"Description":"New description",
"UsageInstructions":"New usage instructions",
"CompatibleServices":[
"EKS"
]
}
}
}
]
}
}
]
}
```
**Helm Chart Delivery Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog":"AWSMarketplace",
"ChangeSet":[
{
"ChangeType":"UpdateDeliveryOptions",
"Entity":{
"Identifier":"example1-abcd-1234-5ef6-7890abcdef12",
"Type":"ContainerProduct@1.0"
},
"DetailsDocument":{
"Version":{
"ReleaseNotes":"New release notes",
"VersionTitle":"Version 1.2"
},
"DeliveryOptions":[
{
"Id":"example5-2222-cccc-2222-cccccccccccc",
"Details":{
"HelmDeliveryOptionDetails":{
"DeliveryOptionTitle":"New Delivery Option Title",
"ContainerImages":[
"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/imagename:1.0"
],
"HelmChartUri":"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/helmname:1.0",
"CompatibleServices":[
"EKS-Anywhere"
],
"Description":"New description",
"UsageInstructions":"New usage instructions",
"MarketplaceServiceAccountName":"new-service-account-name",
"ReleaseName":"new-release-name",
"Namespace":"new-cluster-namespace",
"OverrideParameters":[
{
"Key":"new.parameter.key",
"DefaultValue":"New parameter default value"
}
]
}
}
}
]
}
}
]
}
```
**Amazon EKS Add-On Delivery Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog":"AWSMarketplace",
"ChangeSet":[
{
"ChangeType":"UpdateDeliveryOptions",
"Entity":{
"Identifier":"example1-abcd-1234-5ef6-7890abcdef12",
"Type":"ContainerProduct@1.0"
},
"DetailsDocument":{
"Version":{
"ReleaseNotes":"New release notes",
"VersionTitle":"Version 1.2"
},
"DeliveryOptions":[
{
"Id":"example4-2222-cccc-2222-cccccccccccc",
"Details":{
"EksAddOnDeliveryOptionDetails":{
"ContainerImages":[
"709825985650.dkr.ecr.us-east-1.amazonaws.com/test-seller/canary-test-repo-product-6:mongo"
],
"Description":"Description for delivery option provided by ISV",
"UsageInstructions":"Usage instructions with launch instructions",
"HelmChartUri":"709825985650.dkr.ecr.us-east-1.amazonaws.com/rocket/rocket-product-helm:1.0",
"AddOnName":"aws-mp-test",
"AddOnVersion":"1.2.1",
"AddOnType":"networking",
"CompatibleKubernetesVersions":[
"1.19",
"1.20"
],
"SupportedArchitectures":[
"amd64",
"arm64"
],
"Namespace":"my-test-namespace",
"EnvironmentOverrideParameters":[
{
"Key":"my-field",
"Value":"${AWS_EKS_CLUSTER_NAME}"
}
]
}
}
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateDeliveryOptions` change type:
For more information about these fields, see [ Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-single-ami-products.html#single-ami-adding-version) in the *AWS Marketplace Seller Guide*.
+ `Entity` (object) (required) – Your container-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `ContainerProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request. It includes any information about the version of your container-based product that you would like to update. The included fields are all optional, but you must include at least one field to update.
+ `Version` (object) – Details about the software version.
+ `VersionTitle` (string) – The title of the version that you are creating. Typically this is a description of the version, such as **Version 1.1** or simply **1.1**. Your buyers will be able to choose the version to deploy from a list of all version titles.
This property can't be updated if the product is already published publicly.
+ `ReleaseNotes` (string) – Notes for buyers to tell them about changes from one version to the next.
+ `DeliveryOptions` (list of objects) – List of `DeliveryOption` objects, including the details of each:
+ `Id` (string) – Unique identifier for the `DeliveryOption` (you can get the unique identifier for the `DeliveryOption` by calling the `DescribeEntity` action on the product you are updating).
+ `Details` (object) – Holds the details of a delivery option. Note that this nested details object does *not* need to be double-escaped.
+ `EcrDeliveryOptionDetails` (object) – The details of the container image delivery option.
+ `DeliveryOptionTitle` (string) – A short description that allows your buyer to choose between your delivery options.
This property can't be updated if the product is already published publicly.
+ `ContainerImages` (array of strings) – An array of container image URLs used by this version. The path will be the repository that you have uploaded the image to, with the tag for the image used by this version. If this field is included, the list must include all needed images, even images that are not changing.
This property can't be updated if the product is already published publicly.
+ `DeploymentResources` (array of objects) – An array of other deployment resources needed for the version, such as links to Helm charts or other documentation. Each resource includes a name to describe it and a URL that points at the resource. On the launch page for your version, this displays as a list of links.
This property can't be updated if the product is already published publicly.
+ `Name` (string) – The text of the hyperlink that is shown to the buyer.
+ `Url` (string) – The URL of the hyperlink shown to the buyer.
+ `CompatibleServices` (array of strings) – An array of services that the release is compatible with. Valid options: `ECS`, `EKS`, `ECS-Anywhere`, `EKS-Anywhere`, and `Bedrock-AgentCore`.
+ `AgenticType` The type of runtime agent. Valid options: `AGENT`, `MCP_SERVER`, or `A2A_SERVER`.
+ `Description` (string) – A longer description of the delivery option to give details to your buyer. You can also include a link to more instructions hosted elsewhere.
+ `UsageInstructions` (string) – Provide instructions on how to deploy and use your product. You can also add a link to usage instructions hosted elsewhere. Can be up to 4,000 characters.
+ `EnvironmentVariables` – List of environment variables that are required by the AgentCore Runtime container and that will be pre-populated for buyers upon deployment. For each variable, provide an object with the *name* as expected by your container, a *description*, and an optional *defaultValue*. For variables such as credentials or API keys that are unique, do not provide a default value. You can use the description to specify details about the variable as well as possible values. All of the provided variables with their default values will be pre-populated when buyers launch your product.
+ `Id` (string) – Unique identifier for the `DeliveryOption` (you can get the unique identifier for the `DeliveryOption` by calling the `DescribeEntity` action on the product you are updating).
+ `Details` (object) – Holds the details of a delivery option. Note that this nested details object does *not* need to be double-escaped.
+ `HelmDeliveryOptionDetails` (object) – The details of the Helm chart delivery option.
+ `DeliveryOptionTitle` (string) – A short description that allows your buyer to choose between your delivery options.
This property can't be updated if the product is already published publicly.
+ `ContainerImages` (array of strings) – An array of container image URLs used by this version. The path will be the repository that you have uploaded the image to, with the tag for the image used by this version. The list must include all needed images, even images that have not changed from previous versions. See the next section for information about creating repositories using the Catalog API.
+ `HelmChartUri` (string) – The URL to the Helm chart hosted in Amazon ECR that the buyer will install to launch the software.
+ `CompatibleServices` (array of strings) – An array of services that the release is compatible with. Valid options are `ECS` and `EKS`.
+ `Description` (string) – A longer description of the delivery option to give details to your buyer. You can also include a link to more instructions provided elsewhere.
+ `UsageInstructions` (string) – Provide instructions about the usage for this delivery option. Can be up to 4,000 characters.
+ `MarketplaceServiceAccountName` (string) – The name of the Kubernetes service account. The service account will be used to connect to AWS Identity and Access Management for permissions to call AWS services.
+ `ReleaseName` (string) – The name for the Helm release provided to the `helm install` command that buyers use to launch the software.
+ `Namespace` (string) – The Kubernetes namespace where the Helm chart will be installed.
+ `OverrideParameters` (array of objects) – Parameters that will be used in the Helm commands that launch the application. Buyers can override the default values.
+ `Key` (string)– The key for the parameter in dot notation (override.example.key).
+ `DefaultValue` (string) – The default value for this override parameter.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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 container images and other information to ensure that it meets the [AWS Marketplace guidelines for container products](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-policies.html). This process can take a few minutes to hours, depending on the number and size of your containers.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
For more information about change sets, see [Working with change sets](catalog-apis.md#working-with-change-sets). For more information about errors in seller product change sets, see [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors).
**Asynchronous Errors**
The following errors are specific to `UpdateDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT\$1STATUS | Use an existing limited or public product. |
| INCOMPATIBLE\$1SERVICES | The service list contains incompatible services. [incompatible\$1services] Provide a valid list of compatible services. |
| NO\$1SERVICE\$1SPECIFIED | Provide at least 1 compatible service. |
| DUPLICATE\$1COMPATIBLE\$1AWS\$1SERVICES | The service list contains duplicate entries. Remove them. Each entry must be unique. |
| INVALID\$1VERSION\$1TITLE | Remove spaces before the trademark symbol. |
| INVALID\$1VERSION\$1TITLE | Remove the following unsupported characters: [x, y, z] |
| INVALID\$1VERSION\$1TITLE | Remove spaces from the beginning of the version title. |
| INVALID\$1VERSION\$1TITLE | Provide version title with fewer than [x] characters. |
| DUPLICATE\$1VERSION\$1TITLE | The version title [duplicate\$1version\$1title] is a duplicate. Remove or change the title. |
| INVALID\$1RELEASE\$1NOTES | Remove spaces before the trademark symbol. |
| INVALID\$1RELEASE\$1NOTES | Remove unsupported characters: [x, y, z] |
| INVALID\$1RELEASE\$1NOTES | Remove spaces from the beginning of release notes. |
| INVALID\$1RELEASE\$1NOTES | Provide release notes with fewer than (x) characters. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove spaces before the trademark symbol. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Remove unsupported characters: [x, y, z] |
| INVALID\$1USAGE\$1INSTRUCTIONS | Provide usage instructions with fewer than (x) characters. |
| INVALID\$1USAGE\$1INSTRUCTIONS | Provide usage instructions. |
| MISSING\$1CONTAINER\$1IMAGES | Provide at least 1 container image. |
| TOO\$1MANY\$1CONTAINER\$1IMAGES | Provide fewer than 50 container images. |
| DUPLICATE\$1CONTAINER\$1IMAGES | The container image list contains duplicate images: [duplicate\$1images]. Provide a list with unique images. |
| INVALID\$1CONTAINER\$1IMAGES | Provide a valid URI for the container image. |
| INVALID\$1CONTAINER\$1IMAGE\$1URI | The image [invalid\$1image\$1uri] doesn't have access to this product. Upload the image to its corresponding product repository. For information about uploading, see [Getting started with container products](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html). |
| INVALID\$1CONTAINER\$1IMAGE\$1TAG | Avoid using 'latest' tag. |
| MISSING\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option from existing list of Ids. |
| EMPTY\$1DELIVERY\$1OPTION\$1IDS | Provide non-empty list of delivery option IDs. |
| DUPLICATE\$1DELIVERY\$1OPTION\$1IDS | Duplicate delivery option IDs: [duplicate\$1ids]. Provide unique delivery option IDs. |
| DUPLICATE\$1DELIVERY\$1OPTION\$1TITLES | Duplicate delivery option titles: [duplicate\$1titles]. Remove the duplicates |
| INVALID\$1DELIVERY\$1OPTION\$1TITLES | The delivery option titles [existing\$1titles] already exist. Provide a different title. |
| INVALID\$1FULFILLMENT\$1OPTION\$1TITLE | Provide delivery option title with fewer than (x) characters. |
| EMPTY\$1RESOURCE\$1NAME | Provide resource name. |
| EMPTY\$1RESOURCE\$1URL | Provide resource URL. |
| INVALID\$1RESOURCE\$1NAME | Provide resource name with fewer than 256 characters. |
| INVALID\$1RESOURCE\$1URL | Provide resource URL with fewer than 256 characters. |
| INVALID\$1SHORT\$1DESCRIPTION | Provide a short description with fewer than 1,000 characters. |
| INVALID\$1SHORT\$1DESCRIPTION | Provide short description. |
| NO\$1LICENSE\$1SECRET\$1KEYS | For Amazon EKS Anywhere products, provide 1 override parameter for license secret. Needs DefaultValue of "\$1\$1AWSMP\$1LICENSE\$1SECRET\$1", see example in section. |
| NO\$1SERVICE\$1ACCOUNT\$1CONFIGURATION | For paid products, provide 1 override parameter for service account configuration. Needs DefaultValue of "\$1\$1AWSMP\$1SERVICE\$1ACCOUNT\$1", see example in section. |
| SCAN\$1ERROR | Fix security vulnerability ""[y]"" on Image ""[x]"". |
| FIELD\$1NOT\$1ALLOWED\$1TO\$1CHANGE | Field [x] cannot be changed. |
| INVALID\$1DELIVERY\$1OPTIONS\$1STATUS | The delivery option IDs [invalid\$1ids] are invalid. Provide delivery options in the limited or public state. |
| NO\$1CHANGE\$1FOUND | Provide at least 1 change. |
| MULTIPLE\$1VERSION\$1UPDATE | Provide delivery option IDs from the same version. |
| OVERRIDE\$1PARAMETER\$1KEYS\$1CONTAINS\$1SPECIAL\$1CHARS | The override parameter keys [invalid\$1keys] contain invalid characters. You keys must use only letters, numbers, double quotes (“ ”) and plus signs (\$1). |
| INVALID\$1CONTAINER\$1IMAGE\$1REPOSITORY | The repositories [invalid\$1repositories] are invalid. Provide repositories created through the AddRepositories change type. |
| INVALID\$1CONTAINER\$1IMAGE\$1TAG\$1FORMAT | The container image tag [invalid\$1image\$1tag] is invalid. Provide a tag conforming to the \$1CONTAINER\$1IMAGE\$1TAG\$1REGEX\$1 regular expression. |
| DUPLICATE\$1OVERRIDE\$1PARAMETER\$1KEYS | The override parameters contain duplicate keys [duplicate\$1keys]. Remove the duplicates. |
| UNSUPPORTED\$1CONTAINER\$1IMAGE\$1URI | The container image [unsupported\$1image] is unsupported. Provide an image that follows the [Image Manifest V 2, Schema 1](https://docker-docs.uclv.cu/registry/spec/manifest-v2-1/). |
| INVALID\$1NAMESPACE | The namespace values [invalid\$1namespaces] are invalid. Provide values that conform to the \$1HELM\$1RELEASE\$1PARAM\$1REGEX\$1 regular expression. |
| INVALID\$1RELEASE\$1NAME | The releaseName values [invalid\$1release\$1names] are invalid. Provide values that conform to the \$1HELM\$1RELEASE\$1PARAM\$1REGEX\$1 regular expression. |
| OVERRIDE\$1PARAMETER\$1KEYS\$1CONTAINS\$1RESERVED\$1PARAMETER\$1KEYS | The override parameter key for delivery option titles [invalid\$1keys] is reserved. Reserved keys: [reserved\$1param\$1keys]. Provide a different key. |
| INCOMPATIBLE\$1ADDON\$1NAME | The add-on name [provided\$1name] does not match the existing name. Reuse the existing name from the public version, or previous versions, of this add-on. You can only use one add-on name for each product. |
| INCOMPATIBLE\$1ADDON\$1NAMESPACE | The add-on namespace [provided\$1namespace] does not match the existing namespace . Reuse the existing namespace from the public version, or previous versions, of this add-on. You can only use one add-on namespace for each product. |
## Restrict a version
You can use the Catalog API to restrict a version of your container-based product in AWS Marketplace. This prevents new buyers from being able to use that version. There must be at least one publicly available version in a product. You cannot restrict the only remaining publicly available version for a product.
To restrict a version, call the `StartChangeSet` API operation with the `RestrictDeliveryOptions` change type, as shown in the following example.
**Note**
Restricting one or more, but not all, delivery options from a version will remove those options from being available to your buyers. Restricting all delivery options for a version will remove that version from the AWS Marketplace catalog.
Restricting an Amazon EKS add-on is currently not supported through the Catalog API.
Restricted versions are still available for existing customers.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "RestrictDeliveryOptions",
"Entity":
{
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12",
"Type": "ContainerProduct@1.0"
},
"DetailsDocument":
{
"DeliveryOptionIds":
[
"example1-2222-cccc-2222-cccccccccccc"
]
}
}
]
}
```
Provide information for the fields to add the `RestrictDeliveryOptions` change type:
+ `Entity` (object) (required) – Your container-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `ContainerProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request. It includes IDs for the delivery options of your container-based product that you would like to restrict.
+ `DeliveryOptionIds` (array of strings) – List of `DeliveryOption` IDs for the versions that you want to restrict. You can get the unique identifier for the `DeliveryOption` by calling the `DescribeEntity` action on the product you are restricting.
**Response Syntax**
A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and 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. This process can take a few minutes to hours.
You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation.
For more information about change sets, see [Working with change sets](catalog-apis.md#working-with-change-sets). For more information about errors in seller product change sets, see [Change set status and errors](work-with-seller-products.md#seller-product-change-set-errors).
**Asynchronous Errors**
The following errors are specific to `RestrictDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT\$1STATUS | Use a public product. |
| MISSING\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option from existing list of IDs. |
| INVALID\$1DELIVERY\$1OPTIONS\$1STATUS | The delivery option IDs [invalid\$1ids] are invalid. Provide delivery options in the public state. |
| EMPTY\$1DELIVERY\$1OPTION\$1IDS | Provide non-empty list of delivery option IDs. |
| INVALID\$1MINIMUM\$1PUBLIC\$1DELIVERY\$1OPTIONS | Cannot restrict all delivery option IDs. |
| DUPLICATE\$1DELIVERY\$1OPTION\$1IDS | Duplicate delivery option IDs: [duplicate\$1ids]. Provide unique delivery option IDs. |
# Work with SaaS products using the AWS Marketplace APIs
You can use the AWS Marketplace Catalog API to automate tasks for working with SaaS-based products. For information about creating SaaS-based products, see [Create a product](work-with-seller-products.md#create-product). The following topics describe how to perform Catalog API actions:
**Topics**
+ [Configure Free pricing model for SaaS products](#saas-free-pricing-model)
+ [SaaS Quick Launch options](#saas-quick-launch-resources)
+ [Add delivery options](#add-delivery-options)
+ [SaaSUrlDeliveryOption](#saas-url-delivery-option)
## Configure Free pricing model for SaaS products
SaaS products can be offered with a Free pricing model, which allows buyers to use your product at no cost. When using the Free pricing model for SaaS products, you must configure pricing dimensions with zero-dollar pricing in either UsageBasedPricingTerm or ConfigurableUpfrontPricingTerm.
**Note**
The Free pricing model requirement for SaaS products is unique. For SaaS products with Free pricing, you must create at least one dimension with either UsageBasedPricingTerm or ConfigurableUpfrontPricingTerm, and all dimensions must be priced at \$10.00. This requirement does not apply to AMI, container, or machine learning products.
To configure Free pricing for a SaaS product:
1. Create pricing dimensions for your product using the `AddDimensions` change type. For more information, see [Add pricing dimensions](work-with-seller-products.md#add-dimensions) in the seller products documentation.
1. Create an offer with the `PricingModel` set to `Free` and include either `UsageBasedPricingTerm` or `ConfigurableUpfrontPricingTerm` with all dimension prices set to \$10.00. For more information about creating offers, see [Work with offers using the AWS Marketplace APIs](work-with-offers.md).
When configuring the offer, ensure that:
+ All rate card prices in `UsageBasedPricingTerm` are set to "0.00" (string format)
+ All charge amounts in `ConfigurableUpfrontPricingTerm` are set to "0.00" (string format)
+ At least one dimension with \$10.00 pricing is included
## SaaS Quick Launch options
For information about Quick Launch options, see the following resources:
+ (Buyers) For Quick Launch options for SaaS products, see [Configuring and launching Saas products using Quick Launch](https://docs.aws.amazon.com/marketplace/latest/buyerguide/saas-quick-launch.html) in the *AWS Marketplace Buyer Guide*.
+ (Sellers) For Quick Launch options for SaaS products, see [Configure Quick Launch](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-settings.html#saas-quick-launch) in the *AWS Marketplace Seller Guide*.
+ For a Quick Launch workshop for SaaS products, see [Lab: Enable SaaS Quick Launch](https://catalog.workshops.aws/mpseller/en-US/saas/quick-launch-integration) in the *AWS Marketplace seller workshop*.
## Add delivery options
You can use the Catalog API to add delivery options for a SaaS product in AWS Marketplace. API delivery options enable sellers to offer API-based services that integrate with AWS services such as Amazon Bedrock for AI agent workflows.
To add API delivery options, call the `StartChangeSet` API operation with the `AddDeliveryOptions` change type to add delivery details, as shown in the following example.
The following topics explain how to add use the `ApiDeliveryOptionDetails` and `SaaSUrlDeliveryOptionDetails` options.
**Topics**
+ [ApiDeliveryOptionDetails](#api-delivery-option-details)
+ [Update delivery options](#update-delivery-options)
+ [Update delivery option visibility](#update-delivery-options-visibility)
### ApiDeliveryOptionDetails
The example in this section supports the `ApiDeliveryOptionDetails` delivery option type, which allows you to specify API endpoints, authentication methods, and integration protocols for your SaaS product.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"ChangeType": "AddDeliveryOptions",
"Entity": {
"Identifier": "prod-1234567890123",
"Type": "SaaSProduct@1.0"
},
"Details": {
"DeliveryOptions": [
{
"Details": {
"ApiDeliveryOptionDetails": {
"ApiType": "AGENT",
"QuickLaunchEnabled": true,
"FulfillmentUrl": "https://example.com/fulfillment",
"UsageInstructions": "# Getting Started\\n\\nTo use this API:\\n1. Register for an API key\\n2. Configure your endpoint\\n3. Start making requests",
"CompatibleServices": ["Bedrock-AgentCore"],
"Endpoints": [
{
"Name": "GenerateContent",
"EndpointUrl": "https://api.example.com/v1/generate",
"Description": "Generate content using AI models",
"AuthorizationTypes": ["API_KEY"],
"Schemas": [{
"Type": "OPEN_API",
"SchemaUrl": "https://example.com/schemas/example-schema.json"
}],
"IntegrationProtocols": [
{
"Type": "MCP",
"UsageInstructions": "Connect using Model Context Protocol for seamless integration"
}
]
}
]
}
}
}
]
}
}
```
Provide information for the fields to add the `AddDeliveryOptions` change type:
+ `Entity` (object) (required) – Your SaaS-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see Identifier.
+ `Type` (string) (required) – The Type is based on the delivery method (product type) that your product will be using: `SaaSProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request.
+ `DeliveryOptions` (array) – Details of the API delivery options being added.
+ `Details` (object) – Contains the `ApiDeliveryOptionDetails` of a delivery option to be added.
+ `ApiDeliveryOptionDetails` (object) – Contains the API delivery option details for a SaaS product.
+ `ApiType` (string) (required) – Type of API offering. Valid values: `MCP_SERVER`, `KNOWLEDGE_BASE`, `AGENT`, `GUARDRAIL`, `OTHER`.
+ `QuickLaunchEnabled` (boolean) (required) – Determines if buyers can use Quick Launch to configure and launch the software.
+ `FulfillmentUrl` (string) (required) – The URL to the seller's software registration landing page.
+ `UsageInstructions` (string) (required) – Instructions for using this API delivery option. Supports markdown formatting. Maximum 30,000 characters.
+ `CompatibleServices` (array) (optional) – Supported AWS services for this delivery option. Currently supports `Bedrock-AgentCore`.
+ `Endpoints` (array) (required) – The API endpoints available for this offering. Must contain exactly one endpoint.
+ `Name` (string) (optional) – The name of the API endpoint. Must match pattern `^[A-Za-z][a-zA-Z0-9-]+$`. Maximum 100 characters.
+ `EndpointUrl` (string) (required) – The URL of the API endpoint. Must be a valid HTTPS URL.
+ `Description` (string) (optional) – A description of the API endpoint and its functionality. Maximum 4,000 characters.
+ `AuthorizationTypes` (array) (required) – The types of authorization required to access the API endpoint. Valid values: `API_KEY`, `OAUTH2`. Must contain 1-2 unique values.
+ `Schemas` (array) (optional) – The schema specifications for the API endpoint. Maximum 1 schema.
+ `Type` (string) (required) – Schema type. Valid value: `OPEN_API`.
+ `SchemaUrl` (string) (required) – The S3 URL of the schema that has been ingested into a Marketplace owned S3 bucket.
+ `IntegrationProtocols` (array) (optional) – Protocol types supported by the endpoint. Maximum 2 protocols.
+ `Type` (string) (required) – Protocol identifier. Valid values: `MCP`, `A2A`.
+ `UsageInstructions` (string) (required) – Additional instructions for utilizing the protocol with the endpoint. Maximum 30,000 characters.
****Response Syntax****
A change set is created for your request. The response to this request gives you the ID for the change set and looks like the following.
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-
1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}
```
**Synchronous Validations**
| Error condition | Message | HTTP code |
| --- | --- | --- |
| Invalid API Type | You provided an invalid API type. Valid values are: MCP\$1SERVER, KNOWLEDGE\$1BASE, AGENT, GUARDRAIL, OTHER. | 422 |
| Invalid Fulfillment Url | Provide a valid fulfillment URL beginning with "https://". | 422 |
| Missing Required Fields | Required parameter is missing. You must provide ApiType, QuickLaunchEnabled, FulfillmentUrl, UsageInstructions, and Endpoints. | 422 |
| Invalid Endpoint URL | Provide a valid endpoint URL beginning with "https://". | 422 |
| Missing Authorization Types | You must provide at least one authorization type. Valid values are: API\$1KEY, OAUTH2. | 422 |
| Invalid Authorization Types | You provided invalid authorization types. Valid values are: API\$1KEY, OAUTH2. | 422 |
| Too Many Endpoints | You cannot provide more than 1 endpoint for API delivery options. | 422 |
| Invalid Compatible Services | You provided invalid compatible services. Valid values are: Bedrock-AgentCore. | 422 |
| Invalid Schema Type | You provided an invalid schema type. Valid value is: OPEN\$1API. | 422 |
| Invalid Schema URL | Provide a valid schema URL that points to a Marketplace owned S3 bucket. | 422 |
| Invalid Integration Protocol | You provided an invalid integration protocol type. Valid values are: MCP, A2A. | 422 |
| Too Many Integration Protocols | You cannot provide more than 2 integration protocols. | 422 |
| Invalid Usage Instructions | Usage instructions exceed the maximum length of 30,000 characters. | 422 |
**Asynchronous Errors**
| Error code | Error message |
| --- | --- |
| DUPLICATE\$1DELIVERY\$1OPTIONS | You provided one or more delivery option types that already exist for this product. Provide a unique delivery option type or use `UpdateDeliveryOptions` if you intended to change an existing delivery option. |
| INVALID\$1FULFILLMENT\$1URL | The URL you provided returned HTTP status code [x]. Provide a fulfillment URL that renders with a 200. |
| INVALID\$1ENDPOINT\$1URL | The URL you provided returned HTTP status code [x]. Provide an endpoint URL that renders with a 200. |
| INVALID\$1SCHEMA\$1URL | The schema URL you provided is invalid or inaccessible. Provide a valid schema URL that points to an Amazon S3 bucket owned by AWS Marketplace. |
### Update delivery options
You can use the Catalog API to update the delivery options for a SaaS product in AWS Marketplace.
To update the delivery options, call the `StartChangeSet` API operation with the `UpdateDeliveryOptions` change type, as shown in the following example.
**Note**
This supports the `ApiDeliveryOptionDetails` delivery option type. You must provide the delivery option ID to identify which option to update.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateDeliveryOptions",
"Entity": {
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1",
"Type": "SaaSProduct@1.0"
},
"DetailsDocument": {
"DeliveryOptions": [
{
"Id": "do-1234567891234567891234",
"Details": {
"ApiDeliveryOptionDetails": {
"ApiType": "AGENT",
"QuickLaunchEnabled": true,
"FulfillmentUrl": "https://example.com/fulfillment-updated",
"UsageInstructions": "# Updated Getting Started\\n\\nTo use this updated API:\\n1. Register for an API key\\n2. Configure your endpoint\\n3. Start making requests",
"CompatibleServices": ["Bedrock-AgentCore"],
"Endpoints": [
{
"Name": "GenerateContent",
"EndpointUrl": "https://api.example.com/v2/generate",
"Description": "Generate content using updated AI models",
"AuthorizationTypes": ["API_KEY", "OAUTH2"],
"Schemas": [{
"Type": "OPEN_API",
"SchemaUrl": "https://example.com/schemas/updated-schema.json"
}],
"IntegrationProtocols": [
{
"Type": "MCP",
"UsageInstructions": "Connect using Model Context Protocol for seamless integration"
}
]
}
]
}
}
}
]
}
}
]
}
```
Provide information for the fields to update the `UpdateDeliveryOptions` change type with API delivery options:
+ `Entity` (object) (required) – Your SaaS-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see Identifier.
+ `Type` (string) (required) – The Type is based on the delivery method (product type) that your product will be using: `SaaSProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request.
+ `DeliveryOptions` (array) – Contains the details of the API delivery options being updated.
+ `Id` (string) (required) – Unique identifier for the DeliveryOption. (Get the unique identifier for the DeliveryOption by calling the `DescribeEntity` action on the product you are updating.)
+ `Details` (object) – Contains the `ApiDeliveryOptionDetails` of the delivery option to be updated.
+ `ApiDeliveryOptionDetails` (object) – Contains the API delivery option details for SaaS product.
+ `ApiType` (string) (required) – Type of API offering. Valid values: `MCP_SERVER`, `KNOWLEDGE_BASE`, `AGENT`, `GUARDRAIL`, `OTHER`.
+ `QuickLaunchEnabled` (boolean) (required) – Determines if buyers can use Quick Launch to configure and launch the software.
+ `FulfillmentUrl` (string) (required) – The URL to be updated for the SaaS product.
+ `UsageInstructions` (string) (required) – Instructions for using this API delivery option. Supports markdown formatting. Maximum 30,000 characters.
+ `CompatibleServices` (array) (optional) – Supported AWS services for this delivery option. Currently supports `Bedrock-AgentCore`.
+ `Endpoints` (array) (required) – The API endpoints available for this offering. Must contain exactly one endpoint.
+ `Name` (string) (optional) – The name of the API endpoint.
+ `EndpointUrl` (string) (required) – The URL of the API endpoint to be updated.
+ `Description` (string) (optional) – A description of the API endpoint and its functionality.
+ `AuthorizationTypes` (array) (required) – The types of authorization required to access the API endpoint. Valid values: `API_KEY`, `OAUTH2`.
+ `Schemas` (array) (optional) – The schema specifications for the API endpoint.
+ `Type` (string) (required) – Schema type. Valid value: `OPEN_API`.
+ `SchemaUrl` (string) (required) – The S3 URL of the updated schema.
+ `IntegrationProtocols` (array) (optional) – Protocol types supported by the endpoint.
+ `Type` (string) (required) – Protocol identifier. Valid values: `MCP`, `A2A`.
+ `UsageInstructions` (string) (required) – Additional instructions for utilizing the protocol with the endpoint.
**Response Syntax**
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-
1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}
```
The change request is added to a queue and processed. This includes validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours. You can check the status of the request through the AWS Marketplace Management Portal, or in the Catalog API with the `DescribeChangeSet` action.
**Synchronous Validations**
| Error condition | Message | HTTP code |
| --- | --- | --- |
| Empty Delivery Option Ids | Provided Details is not valid. String '' at /DeliveryOptions/0/Id does not match required schema regex, '^do-[a-zA-Z0-9]\$1\$1' | 422 |
| Missing Delivery Option Ids | Provided Details is not valid. JSON at /DeliveryOptions/0 is missing required properties: ['Id']. | 422 |
| Duplicate Delivery Option Ids | Provide unique delivery option IDs. | 422 |
| Invalid Fulfillment Url | Provide a valid fulfillment URL beginning with "https://". | 422 |
| Invalid Delivery Option IDs | Provide delivery option IDs that can be found in the product. IDs not found: [x] | 422 |
| Multiple URL Delivery Options | You provided more than one URL delivery option. Provide one URL delivery option. | 422 |
| Missing delivery option ids | The delivery option ID is missing. Provide one or more valid delivery option IDs that you wish to update, or use AddDeliveryOptions if you intended to add a new delivery option. | 422 |
| Invalid Launch URL | Provide a valid launch URL beginning with "https://". | 422 |
| Missing Launch Url | Required parameter LaunchUrl is missing. You must provide a LaunchUrl. | 422 |
| Missing deployment templates | The deployment template is missing. Provide at least one deployment template. | 422 |
| Too many deployment templates | You cannot provide more than 20 deployment templates. | 422 |
| Invalid template URL | Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x] | 422 |
| Invalid deployment template stack name | The deployment template stack name is invalid. Provide a valid stack name using only alphanumeric characters and hyphens. It must start with an alphabetical character and can't be longer than 128 characters. | 422 |
| Duplicate deployment template title | You provided duplicate deployment template titles. Provide unique deployment template titles. | 422 |
| Duplicate deployment template URL | You provided duplicate deployment template urls. Provide unique deployment template urls. | 422 |
| Invalid deployment template type | The deployment template type is invalid. Provide a valid deployment template type. Supported values are ["CloudFormation@1.0"]. | 422 |
| Invalid deployment template IAM policy | The deployment template IAM policy is invalid. Provide a valid IAM policy. | 422 |
| Invalid usage instructions | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-saas-products.html) | 422 |
**Asynchronous Errors**
| Error code | Error message |
| --- | --- |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| AUDIT\$1ERROR | AWS MP Catalog Audits List - CQ team |
| INVALID\$1FULFILLMENT\$1URL | The URL you provided returned HTTP status code [x]. Provide a fulfillment URL that renders with a 200. |
| INVALID\$1LAUNCH\$1URL | The URL you provided returned HTTP status code [x]. Provide a launch URL that renders with a 200. |
| INVALID\$1TEMPLATE\$1URL | Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x] |
### Update delivery option visibility
You can use the Catalog API to configure permissions so that only some users can change the visibility for a SaaS product in AWS Marketplace.
To configure permissions so that only some users can change the visibility for a SaaS product, call the `StartChangeSet` API operation with the `UpdateDeliveryOptionsVisibility` change type, as shown in the following example.
**Note**
This is only supported for one delivery option: `SaaSUrlDeliveryOptionDetails`.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateDeliveryOptionsVisibility",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "SaaSProduct@1.0"
},
"DetailsDocument":
{
"DeliveryOptions":
[
{
"Id": "do-1234567891234567891234",
"TargetVisibility": "Public"
},
{
"Id": "do-43210987654321",
"TargetVisibility": "Limited",
"Targeting":
{
"PositiveTargeting":
{
"BuyerAccounts":
[
"123456789012"
]
}
}
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateDeliveryOptionsVisibility` change type:
+ `Entity` (object) (required) – Your SaaS-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `SaaSProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request.
+ `DeliveryOptions` (array) – List of `DeliveryOptions` to be updated.
+ `TargetVisibility` (string) – The delivery option id to be updated.
+ `TargetVisibility` (string) – The intended new visibility of the delivery option.
Possible values: `Limited`, `Public`, and `Unavailable`.
**Note**
There is always exactly one `Public` delivery option, and a maximum of one `Limited` delivery option.
+ `Targeting` (object) *optional * – Targeting of the delivery option, used in conjunction with the `Limited` visibility status to be able to test the new delivery option before changing the visibility to `Public`.
+ `PositiveTargeting` (object) – Specifying inclusive targeting.
+ `BuyerAccounts` (array of strings) – The list of buyer AWS account ids who will be able to use the new delivery option.
Min size: 0. Max size: 100.
**Response Syntax**
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}
```
The change request is added to a queue and processed. This includes validating information to ensure that it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours. You can check the status of the request through the AWS Marketplace Management Portal, or in the Catalog API with the `DescribeChangeSet` action.
**Synchronous Validations**
| Error condition | Message | HTTP code |
| --- | --- | --- |
| Missing delivery option ids | The delivery option ID is missing. Provide one or more valid delivery option IDs that you wish to update, or use AddDeliveryOptions if you intended to add a new delivery option. | 422 |
| Invalid visibility | You provided invalid option for TargetVisibility. Allowed options are: Limited, Public, Unavailable. | 422 |
| Invalid targeting | You provided invalid option for PositiveTargeting. You must provide a valid parameter for BuyerAccounts. | 422 |
| Missing Visibility and Targeting | You provided invalid delivery option visibility details. You must provide a valid parameter for at least one of TargetVisibility or Targeting. | 422 |
| Too many AWS account ids | You cannot provide more than 100 targeted buyer accounts. | 422 |
**Asynchronous Errors**
| Error code | Error message |
| --- | --- |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | You provided invalid delivery option details. Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| INVALID\$1VISIBILITY | You provided more than one delivery option for the public state. Provide only one public delivery option. |
| INVALID\$1VISIBILITY | You didn't provide a public delivery option. Provide one public delivery option. |
| AUDIT\$1ERROR | Varies based on MCO manual review. |
## SaaSUrlDeliveryOption
The following example shows how to use the `SaaSUrlDeliveryOptionDetails` to update the `FulfillmentUrl`.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateDeliveryOptions",
"Entity": {
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1",
"Type": "SaaSProduct@1.0"
},
"DetailsDocument": {
"DeliveryOptions": [
{
"Id": "do-1234567891234567891234",
"Details": {
"SaaSUrlDeliveryOptionDetails": {
"FulfillmentUrl": "https://www.aws.amazon.com/marketplace/management",
"LaunchUrl": "URL",
"UsageInstructions": "Instructions",
"DeploymentTemplates": [
{
"Title": "CloudFormation Template 123",
"Description": "CloudFormation description",
"IamPolicy": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:Get*\",\"s3:List*\"],\"Resource\":\n[\"arn:aws:s3:::amzn-s3-demo-bucket\",\"arn:aws:s3:::amzn-s3-demo-bucket/*\"]}]}"
}
]
}
}
}
]
}
}
]
}
```
Provide information for the fields to add the `AddDeliveryOptions` change type:
+ `Entity` (object) (required) – Your SaaS-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `SaaSProduct@1.0`.
+ **DetailsDocument** (object) (required) – Details of the request.
+ `DeliveryOptions` (array) – Contains the details of the delivery options being updated.
+ `TargetVisibility` (string) – Unique identifier for the `DeliveryOption`. (Get the unique identifier for the `DeliveryOption` by calling the `DescribeEntity` action on the product you are updating.)
+ `Details` (object) – Contains the `SaaSUrlDeliveryOptionDetails` of the delivery option to be updated.
+ `SaaSUrlDeliveryOptionDetails` (object) – Contains the `FulfillmentUrl` of a delivery option for SaaS product.
+ `FulfillmentUrl` (string) – The URL to be updated for the SaaS product.
+ `LaunchUrl` (string) – The URL to your SaaS product’s landing page. This is required if `QuickLaunchEnabled` is set to `True`.
+ `UsageInstructions` (string) – Instructions for using this delivery option. Include documentation for manual steps for customers who won’t use `DeploymentTemplates`.
+ `DeploymentTemplates` (array) – Deployment templates that customers can use to set up and configure the SaaS product and any related AWS resources.
+ `Title` (string) – The display name of the deployment template.
+ `Description` (string) – A description for what the deployment template contains.
+ `IamPolicy` (string) – An IAM policy describing the permissions needed to deploy the template. Buyers can use this IAM policy to quickly deploy the template.
+ `CloudFormationDetails` (object) – The details of a CloudFormation template.
+ `TemplateUrl` (string) – The URL for the deployment template.
+ `DefaultStackName` (string) – The default name used in CloudFormation when the customer creates the template.
**Response Syntax**
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-
1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}
```
The change request is added to a queue and processed. This includes validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours. You can check the status of the request through the AWS Marketplace Management Portal, or in the Catalog API with the `DescribeChangeSet` action.
**Synchronous Validations**
| Error condition | Message | HTTP code |
| --- | --- | --- |
| Empty Delivery Option Ids | Provided Details is not valid. String '' at /DeliveryOptions/0/Id does not match required schema regex, '^do-[a-zA-Z0-9]\$1\$1' | 422 |
| Missing Delivery Option Ids | Provided Details is not valid. JSON at /DeliveryOptions/0 is missing required properties: ['Id']. | 422 |
| Duplicate Delivery Option Ids | Provide unique delivery option IDs. | 422 |
| Invalid Fulfillment Url | Provide a valid fulfillment URL beginning with "https://". | 422 |
| Invalid Delivery Option IDs | Provide delivery option IDs that can be found in the product. IDs not found: [x] | 422 |
| Multiple URL Delivery Options | You provided more than one URL delivery option. Provide one URL delivery option. | 422 |
| Missing delivery option ids | The delivery option ID is missing. Provide one or more valid delivery option IDs that you wish to update, or use AddDeliveryOptions if you intended to add a new delivery option. | 422 |
| Invalid Launch URL | Provide a valid launch URL beginning with "https://". | 422 |
| Missing Launch Url | Required parameter LaunchUrl is missing. You must provide a LaunchUrl. | 422 |
| Missing deployment templates | The deployment template is missing. Provide at least one deployment template. | 422 |
| Too many deployment templates | You cannot provide more than 20 deployment templates. | 422 |
| Invalid template URL | Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x] | 422 |
| Invalid deployment template stack name | The deployment template stack name is invalid. Provide a valid stack name using only alphanumeric characters and hyphens. It must start with an alphabetical character and can't be longer than 128 characters. | 422 |
| Duplicate deployment template title | You provided duplicate deployment template titles. Provide unique deployment template titles. | 422 |
| Duplicate deployment template URL | You provided duplicate deployment template urls. Provide unique deployment template urls. | 422 |
| Invalid deployment template type | The deployment template type is invalid. Provide a valid deployment template type. Supported values are ["CloudFormation@1.0"]. | 422 |
| Invalid deployment template IAM policy | The deployment template IAM policy is invalid. Provide a valid IAM policy. | 422 |
| Invalid usage instructions | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-saas-products.html) | 422 |
**Asynchronous Errors**
| Error code | Error message |
| --- | --- |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| AUDIT\$1ERROR | AWS MP Catalog Audits List - CQ team |
| INVALID\$1FULFILLMENT\$1URL | The URL you provided returned HTTP status code [x]. Provide a fulfillment URL that renders with a 200. |
| INVALID\$1LAUNCH\$1URL | The URL you provided returned HTTP status code [x]. Provide a launch URL that renders with a 200. |
| INVALID\$1TEMPLATE\$1URL | Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x] |
### Update delivery option visibility
You can use the Catalog API to configure permissions so that only some users can change the visibility for a SaaS product in AWS Marketplace.
To do so, call the `StartChangeSet` API operation with the `UpdateDeliveryOptionsVisibility` change type, as shown in the following example.
**Note**
This is only supported for one delivery option: `SaaSUrlDeliveryOptionDetails`.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateDeliveryOptionsVisibility",
"Entity":
{
"Identifier": "prod-example12345",
"Type": "SaaSProduct@1.0"
},
"DetailsDocument":
{
"DeliveryOptions":
[
{
"Id": "do-1234567891234567891234",
"TargetVisibility": "Public"
},
{
"Id": "do-43210987654321",
"TargetVisibility": "Limited",
"Targeting":
{
"PositiveTargeting":
{
"BuyerAccounts":
[
"123456789012"
]
}
}
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateDeliveryOptionsVisibility` change type:
+ `Entity` (object) (required) – Your SaaS-based product.
+ `Identifier` (string) (required) – Your product ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ `Type` (string) (required) – The `Type` is based on the delivery method (product type) that your product will be using: `SaaSProduct@1.0`.
+ `DetailsDocument` (object) (required) – Details of the request.
+ `DeliveryOptions` (array) – List of `DeliveryOptions` to be updated.
+ `TargetVisibility` (string) – The delivery option id to be updated.
+ `TargetVisibility` (string) – The intended new visibility of the delivery option.
Possible values: `Limited`, `Public`, and `Unavailable`.
**Note**
There is always exactly one `Public` delivery option, and a maximum of one `Limited` delivery option.
+ `Targeting` (object) *optional * – Targeting of the delivery option, used in conjunction with the `Limited` visibility status to be able to test the new delivery option before changing the visibility to `Public`.
+ `PositiveTargeting` (object) – Specifying inclusive targeting.
+ `BuyerAccounts` (array of strings) – The list of buyer AWS account ids who will be able to use the new delivery option.
Min size: 0. Max size: 100.
**Response Syntax**
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}
```
The change request is added to a queue and processed. This includes validating information to ensure that it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours. You can check the status of the request through the AWS Marketplace Management Portal, or in the Catalog API with the `DescribeChangeSet` action.
**Synchronous Validations**
| Error condition | Message | HTTP code |
| --- | --- | --- |
| Missing delivery option ids | The delivery option ID is missing. Provide one or more valid delivery option IDs that you wish to update, or use AddDeliveryOptions if you intended to add a new delivery option. | 422 |
| Invalid visibility | You provided invalid option for TargetVisibility. Allowed options are: Limited, Public, Unavailable. | 422 |
| Invalid targeting | You provided invalid option for PositiveTargeting. You must provide a valid parameter for BuyerAccounts. | 422 |
| Missing Visibility and Targeting | You provided invalid delivery option visibility details. You must provide a valid parameter for at least one of TargetVisibility or Targeting. | 422 |
| Too many AWS account ids | You cannot provide more than 100 targeted buyer accounts. | 422 |
**Asynchronous Errors**
| Error code | Error message |
| --- | --- |
| INVALID\$1DELIVERY\$1OPTION\$1IDS | You provided invalid delivery option details. Provide delivery option IDs that can be found in the product. IDs not found: [x] |
| INVALID\$1VISIBILITY | You provided more than one delivery option for the public state. Provide only one public delivery option. |
| INVALID\$1VISIBILITY | You didn't provide a public delivery option. Provide one public delivery option. |
| AUDIT\$1ERROR | Varies based on MCO manual review. |
# Work with machine learning products using AWS Marketplace APIs
You can use the AWS Marketplace Catalog API to automate tasks for managing machine learning (ML)-based products. This section covers key operations for ML products using the Catalog API.
For information about creating machine learning products using the Catalog API, refer to [ Listing your product in AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-publishing-your-product-in-aws-marketplace.html) in the *AWS Marketplace Seller Guide*.
**Topics**
+ [Prerequisites for publishing ML product listings](cat-ml-prereqs.md)
+ [Add a new version](ml-add-version.md)
+ [Update version information](ml-update-version.md)
+ [Update pricing terms](update-pricing-terms.md)
+ [Restrict a version](ml-restrict-version.md)
# Prerequisites for publishing ML product listings
Ensure that you have the following before getting started with publishing your machine learning product listing:
+ Registration as a seller in AWS Marketplace. For more information, refer to [Register as an AWS Marketplace seller](https://docs.aws.amazon.com/marketplace/latest/userguide/seller-registration-process.html).
+ An IAM user with `AWSMarketplaceSellerFullAccess` permission.
+ A publicly accessible Amazon Simple Storage Service (Amazon S3) bucket to host your company logo and EULA, if you provide one. You enter the URL for the S3 bucket in your `ChangeSet` JSON file.
+ A valid SageMaker AI ARN of the model package or algorithm resource you want to list.
+ A valid IAM role that has a trust relationship with the AWS Marketplace service principal and provides access to your package. For more information about the role, refer to *IAM role for the AWS Marketplace service principal* in the [Prerequisites](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-publishing-prereq.html) page for machine learning products.
# Add a new version
You can use the Catalog API or the AWS Marketplace Management Portal to add a new version to a machine learning product. For more information about using the portal, refer to [Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/machine-learning-products.html) in the *AWS Marketplace Seller Guide*.
**Note**
For ML products, a version consists of a single delivery option, which represents the product you're making available. In the Catalog API, working with delivery options for ML products effectively modifies versions of your product.
When adding new instance types, include an `UpdatePricingTerms` change type in your change set to specify pricing for new instance types. For new products, `UpdatePricingTerms` must cover all supported instance types. `UpdatePricingDimensions` is not required or supported for ML products, because dimensions are automatically generated for all supported instance types. For more information, refer to [Update pricing dimensions](work-with-seller-products.md#update-dimensions).
**Using `StartChangeSet` to add a version**
To add a new version, call the `StartChangeSet` operation with the `AddDeliveryOptions` change type:
1. To validate your API call without creating a version, set `Intent` to `VALIDATE`.
1. For actual version creation, set `Intent` to `APPLY`.
## Request syntax
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [{
"ChangeType": "AddDeliveryOptions",
"Entity": {
"Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1",
"Type": "MachineLearningProduct@1.0"
},
"DetailsDocument": {
"Version": {
"VersionTitle": "version 1.1",
"ReleaseNotes": "Patch update for small bugfix in version 1.0"
},
"DeliveryOptions": [{
"Details": {
"SageMakerAlgorithmDeliveryOptionDetails": {
"SageMakerAlgorithmArn": "arn:aws:sagemaker:us-east-2:605142612156:algorithm/scikit-decision-trees-1552343220",
"AccessRoleArn": "arn:aws:iam::12345678901:role/AwsMarketplaceSageMakerIngestion",
"UsageInstructions":"This is how you use your algorithm",
"SampleNotebookUrl": "https://www.amazon.com",
"RepositoryUrl": "https://www,amazon.com",
"InputProperties": {
"Description": "Input should have all columns in the train/test file except for 'is_fraud' column.",
"Limitations": "Can predict on 1 input in the CSV only at a time",
"SampleInput": {
"RealtimeInferenceText": "{\"prompt\":\"Write summary\",
\"maxTokens\": 1 }",
"BatchTransformUrl": "https://www.sampleData.com",
},
"Parameters": [{
"Name": "prompt",
"Description": "Represents the instruct-style prompt for the model. DataType is String",
"Constraints": "Minimum length should be 1",
"Required": true
},
{
"Name": "maxTokens",
"Description": "Denotes the number of tokens to predict per generation. See BPE Tokens for more details.",
"Constraints": "Minvalue: 1, MaxValue: 30"
}
],
"SageMakerCustomAttributes": [{
"Name": "threshold",
"Description": "Threshold of the confidence score of the detected object",
"Constraints": "Should be an Integer"
}]
},
"OutputProperties": {
"Description": "The output is a JSON object that has the generated text along with likelihoods of tokens, if requested. See example json.",
"SampleOutput": {
"RealtimeInferenceUrl": "https://www.sampledata.com",
"BatchTransformUrl": "https://www.sampleData.com",
},
"Parameters": [{
"Name": "id",
"Description": "An identifier for response"
"AlwaysReturned": true
},
{
"Name": "generations",
"Description": "The generated text along with the likelihoods for tokens requested.",
}
],
},
"RecommendedInstanceTypes": {
"BatchTransform": "ml.m4.large",
"RealtimeInference": "ml.m4.large",
"Training": "ml.m4.large"
}
}
}]
}
}],
"Intent": "APPLY"
}
```
## Required fields
+ `Entity` (object)—required
Contains information about your ML product.
+ `Identifier` (string)—required
Your product ID. For more information, see [Identifier](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#identifier).
+ `Type` (string)—required
Specifies the delivery method (product type). It must be `MachineLearningProduct@1.0`.
+ `DetailsDocument` (object)—required
Contains all details about the new version of your product.
+ `Version` (object)—required
Details about the version being added.
+ `VersionTitle` (string)—required
The title of the version, such as "Version 1.1" or "1.1". Buyers select versions from these titles.
+ `ReleaseNotes` (string)—required
Detailed notes about this version. Must be under 30,000 characters.
+ `DeliveryOptions` (array)—required
Array of delivery methods for your product version. Limited to one delivery option per version.
+ `Details` (object)—required
+ `SagemakerModelPackageDeliveryOptionDetails` or `SageMakerAlgorithmDeliveryOptionDetails` (object)
+ `SageMakerModelPackageArn` or `SageMakerAlgorithmArn` (string)—required
Amazon Resource Name (ARN) of your model package or algorithm.
+ `AccessRoleArn` (string)—required
IAM role ARN for AWS Marketplace to access the SageMaker resource.
+ `SampleNotebookUrl` (string)—required
Link to sample Jupyter notebook with usage code. For more information, refer to a [sample notebook template](https://github.com/aws/amazon-sagemaker-examples/blob/master/aws_marketplace/curating_aws_marketplace_listing_and_sample_notebook/ModelPackage/Sample_Notebook_Template/title_of_your_product-Model.ipynb) on GitHub.
+ `RepositoryUrl` (string)—required
Git repository URL for notebook and sample data access. For more information, see a [sample Git repository](https://github.com/aws/amazon-sagemaker-examples/tree/master/aws_marketplace/curating_aws_marketplace_listing_and_sample_notebook/ModelPackage/Sample_Notebook_Template) on GitHub.
+ `UsageInstructions` (string)—required
Training information for algorithms or usage details for models.
+ `InputProperties` (object)—required
+ `Description` (string)—required
Description of model/algorithm inputs
+ `Limitations` (string)
Input limitations
+ `SampleInput` (object)—required
RealtimeInferenceUrl (string) \$1 RealtimeInferenceText (string) \$1 BatchTransformUrl (string) \$1 BatchTransformText (string)
+ `Parameters` (Array