Working with container-based products - AWS Marketplace Catalog API
Updating product information for a container-based productAdding a new version to a container-based productCreating repositories and resources for a container-based productUpdating version information for a container-based productRestricting a version of a container-based productErrors in the container products API

Working with container-based products

You can use the AWS Marketplace Catalog API to automate tasks for working with container-based products.

With the Catalog API, you can automate updating your existing container-based products. You can perform the following actions through the API:

  • Update product information

  • Add a new version

  • Add repositories for your container images and other resources

  • Update a version

  • Restrict a version

As a prerequisite for updating container-based products, you must have one or more existing container-based products, and you should be familiar with working with the AWS Marketplace Catalog API.

Note

For details about creating a container-based product through the AWS Marketplace Management Portal, see Getting started with container products in the AWS Marketplace Seller Guide.

Updating product information for a container-based product

If you already have a container-based product in AWS Marketplace, you can use the Catalog API to modify the product information.

You update product information by calling StartChangeSet with the UpdateInformation change type and the details that you want to change, as shown in the following example.

POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
"Catalog": "AWSMarketplace",
"ChangeSet": [ 
  { 
    "ChangeType":"UpdateInformation",
    "Entity":{
      "Identifier":"example1-abcd-1234-5ef6-7890abcdef12",
      "Type":"ContainerProduct@1.0"
     },
     "Details": "{
        \"ProductTitle\": \"My Product Title\",
        \"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\"
        ]
      }"
    }
  ]
}
Note

This example has line wraps added for readability and will not work as-is. The Details attribute is a string, and it should be converted from a JSON object to a string in your call to StartChangeSet. In this case, the string is "{ \"ProductTitle\": \"My Product Title\", \"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\" ] }". For more information, see Working with the Details attribute.

The following is information about the input fields you provide for adding the UpdateInformation change type:

  • Entity (object) – The container-based product that you want to update. The Identifier is your product ID, and the type is always ContainerProduct@1.0. For information about using the Identifier, see Identifier.

  • Details (string) – Details of the request. It includes all the information you want to update for your product. Each field is optional, but you must include at least one change to update. This field is a string field. The string is JSON, but it must be formatted properly for a single-line string field, including escaping characters (such as quotation marks) that cannot directly be in a string. For more information, see Working with the Details attribute.

    • ProductTitle (string) – Name of the product to be displayed to buyers.

    • ShortDescription (string) – Description of key aspects of the product to be displayed to buyers. Typically 2–3 sentences.

    • LongDescription (string) – Longer description of your product to be displayed to buyers. Typically 1–3 paragraphs.

    • Sku (string) – A free-form string for you to define as a reference for your own use.

    • LogoUrl (string) – A URL to an image in a publicly accessible Amazon S3 bucket. For more details about image formats, see Company and product logo requirements in the AWS Marketplace Seller Guide.

    • VideoUrls (array of strings) – A list of URLs to publicly available, externally hosted videos to be provided as a reference to buyers in your product information.

    • Highlights (array of strings) – A list of short callouts for key product features.

    • AdditionalResources (array of objects – 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) – A URL to a resource that is helpful for a buyer to understand your product.

    • SupportDescription (string) – Details about your support offerings for your product.

    • Categories (array of strings) – A list of AWS Marketplace defined product categories that describe your product.

    • SearchKeywords (array of strings) – A list of additional keywords for your product for the search experience. Seller name, product name, and product categories are automatically included in search keywords and do not need to be repeated here.

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"
}

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. This process can take a few minutes to hours. 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. For more information about errors in seller product change sets, see Change set status and errors.

Adding a new version to a container-based product

If you already have a container-based product in AWS Marketplace, you can use the 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, see Getting started with container products.

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 in the AWS Marketplace Seller Guide.

If you have not already created new repositories, you can create them using the Catalog API, see Creating repositories and resources for a container-based product.

You add a new version by calling StartChangeSet 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.

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"
  },
    "Details": "{
      \"Version\": {
        \"VersionTitle\": \"1.1\",
        \"ReleaseNotes\": \"Minor bug fix\"
      },
      \"DeliveryOptions\": [{
        \"DeliveryOptionTitle\": \"EKSDelivery\",
        \"Details\": { 
          \"EcrDeliveryOptionDetails\" : {
            \"ContainerImages\": [
              \"709825985650.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],
            \"DeploymentResources\": [{
              \"Name\": \"HelmDeploymentTemplate\",
              \"Url\": \"709825985650.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}],
            \"CompatibleServices\": [\"EKS\"],
            \"Description\": \"Sample Description\",
            \"UsageInstructions\":\"helm pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"
          }
        }
      },
      {
        \"DeliveryOptionTitle\": \"HelmChartDeliveryOption\",
        \"Details\": {
          \"HelmDeliveryOptionDetails\": {
            \"CompatibleServices\": [\"EKS\", \"EKS-Anywhere\"],
            \"ContainerImages\": [
              \"709825985650.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],
            \"HelmChartUri\": \"709825985650.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1\"],\",
            \"Description\": \"Helm chart description\",
            \"UsageInstructions\": \"Usage instructions\",
            \"QuickLaunchEnabled\": true,
            \"MarketplaceServiceAccountName\": \"Service account name\",
            \"ReleaseName\": \"Optional release name\",
            \"Namespace\": \"Optional Kubernetes namespace\",
            \"OverrideParameters\": [{
              \"Key\": \"HelmKeyName1\",
              \"DefaultValue\": \"${AWSMP_LICENSE_SECRET}\",
              \"Metadata\": {
                \"Label\": \"AWS CloudFormation template field label\",
                \"Description\": \"AWS CloudFormation template field description\",
                \"Obfuscate\": false
              }
            },
            {
              \"Key\": \"HelmKeyName2\",
              \"DefaultValue\": \"${AWSMP_SERVICE_ACCOUNT}\",
              \"Metadata\": {
                \"Label\": \"AWS CloudFormation template field label\",
                \"Description\": \"AWS CloudFormation template field description\",
                \"Obfuscate\": false
              }
            }]
          }
        }
      }]
    }"
  }]
}
Note

This example has line wraps added for readability and will not work as-is. The Details attribute is a string, and it should be converted from a JSON object to a string in your call to StartChangeSet. For more information, see Working with the Details attribute.

The following is information about the input fields you must provide for adding the AddDeliveryOptions change type for container-based products:

  • Entity (object) – Your container-based product. The Identifier is your product ID, and the type is always ContainerProduct@1.0. For information about using the Identifier, see Identifier.

  • Details (string) – Details of the request. It includes all the information about the version that you are adding. This field is a string field. The string is itself JSON, but it must be formatted properly for a string field, including escaping characters (such as quotation marks) that cannot directly be in a string. For more information, see Working with the Details attribute.

    • 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 will need to have two delivery options.

      • DeliveryOptionTitle (string) – A short description that helps your buyer to choose between your delivery options.

      • Details (string) – 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.

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

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

        • HelmDeliveryOptionDetails – HelmChartUri (string) – The URL to the Helm chart hosted in Amazon ECR that the buyer will install to launch the software.

        • HelmDeliveryOptionDetails – QuickLaunchEnabled (boolean) – A boolean to determine if buyers can use QuickLaunch to launch the software. For more information about QuickLaunch, see QuickLaunch in AWS Marketplace.

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

          • Metadata (array of objects) – Required if QuickLaunchEnabled is set to true – An array of objects that include details about the override parameter, including AWS CloudFormation template information.

            • Label (string) – The name of the field in the AWS CloudFormation stack creation form that buyers use during QuickLaunch.

            • Description (string) – The description of the field in the AWS CloudFormation stack creation form that buyers use during QuickLaunch.

            • Obfuscate (boolean) – A boolean to determine if sensitive information such as secrets and passwords are masked in AWS CloudFormation consoles, commands, and APIs.

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

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"
}

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. 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 in the Catalog API with the DescribeChangeSet action. For more information about change sets, see Working with change sets. For more information about errors in seller product change sets, see Change set status and errors.

Creating repositories and resources for a container-based product

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 in the AWS Marketplace Seller Guide.

To create new repositories with the Catalog API, call StartChangeSet with the AddRepositories change type, as shown in the following example.

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"
     },
      "Details": "{
        \"Repositories\": [
          {
            \"RepositoryName\": \"new-repo-1\",
            \"RepositoryType\": \"ECR\"
          },
          {
            \"RepositoryName\": \"new-repo-2\",
            \"RepositoryType\": \"ECR\"
          }
        ]
      }"
    }
  ]
}
Note

This example has line wraps added for readability and will not work as-is. The Details attribute is a string, and it should be converted from a JSON object to a string in your call to StartChangeSet. In this case, the string is "{ \"Repositories\": [ { \"RepositoryName\": \"new-repo-1\", \"RepositoryType\": \"ECR\" }, { \"RepositoryName\": \"new-repo-2\", \"RepositoryType\": \"ECR\" } ] }". For more information, see Working with the Details attribute.

The following is information about the input fields you provide for adding the AddRepositories change type. For more information about creating repositories, see Adding a new version in the AWS Marketplace Seller Guide.

  • Entity (structure) – The container-based product you are creating repositories for. The Identifier is your product ID, and the type is always ContainerProduct@1.0. For information about using the Identifier, see Identifier.

  • Details (string) – Details of the request. It includes the information about the repositories that you want to create. This field is a string field. The string is JSON, but it must be formatted properly for a single-line string field, including escaping characters (such as quotation marks) that cannot directly be in a string. For more information, see Working with the Details attribute. 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 only have 50 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 have created one or more repositories for your resources, you add your resources to the repositories. For general information about how to push resources to repositories, see Pushing an image in the Amazon Elastic Container Registry User Guide. For instructions about how to get the specific push commands needed for one of your repositories, see Adding a new version in the AWS Marketplace Seller Guide.

Updating version information for a container-based product

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.

You update an existing version of your container-based product in the Catalog API by calling StartChangeSet 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.

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"
     },
      "Details": "{
        \"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\"
                ]
              }
            }
          },
          {
            \"Id\": \"example5-2222-cccc-2222-cccccccccccc\",
            \"Details\": {
              \"HelmDeliveryOptionDetails\": {
                \"DeliveryOptionTitle\": \"New Delivery Option Title\",
                \"ContainerImages\": [
                  \"709825985650.dkr.ecr.us-east-1.amazonaws.com/sellername/imagename:1.0\"
                ],
                \"HelmChartUri\": \"709825985650.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\",
                \"QuickLaunchEnabled\": true,
                \"OverrideParameters\": [
                  {
                    \"Key\": \"new.parameter.key\",
                    \"DefaultValue\": \"New parameter default value\",
                    \"Metadata\": {
                      \"Label\": \"New metadata label\",
                      \"Description\": \"New metadata description\",
                      \"Obfuscate\": false
                    }
                  }
                ]
              }
            }
          }
        ]
      }"
    }
  ]
}
Note

This example has line wraps added for readability and will not work as-is. The Details attribute is a string, and it should be converted from a JSON object to a string in your call to StartChangeSet. For more information, see Working with the Details attribute.

The following is information about the input fields you provide for adding the UpdateDeliveryOptions change type for container-based products. For more information about these fields, see Adding a new version in the AWS Marketplace Seller Guide.

  • Entity (object) – Your container-based product. The Identifier is your product ID, and the type is always ContainerProduct@1.0. For information about using the Identifier, see Identifier.

  • Details (string) – Details of the request. It includes any information about the version of your container-based product that you would like to update. This field is a string field. The string is JSON, but it must be formatted properly for a single-line string field, including escaping characters (such as quotation marks) that cannot directly be in a string. For more information, see Working with the Details attribute. 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 (string) – 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) – A list 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 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.

      • 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 (string) – 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.

          • QuickLaunchEnabled (boolean) – A boolean to determine if buyers can use QuickLaunch to launch the software. For more information about QuickLaunch, see QuickLaunch in AWS Marketplace.

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

            • Metadata (array of objects) – Only required if QuickLaunchEnabled is set to true – An array of objects that include details about the override parameter, including AWS CloudFormation template information.

              • Label (string) – The name of the field in the AWS CloudFormation stack creation form that buyers use during QuickLaunch.

              • Description (string) – The description of the field in the AWS CloudFormation stack creation form that buyers use during QuickLaunch.

              • Obfuscate (boolean) – A boolean to determine if sensitive information such as secrets and passwords are masked in AWS CloudFormation consoles, commands, and APIs.

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"
}

The change request is added to a queue and processed, including scanning the information to ensure that it meets the AWS Marketplace guidelines for container products. This process can take a few minutes to hours. 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. For more information about errors in seller product change sets, see Change set status and errors.

Restricting a version of a container-based product

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.

You restrict a version in the Catalog API by calling StartChangeSet 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.

Restricted versions are still available for existing customers.

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"
     },
      "Details": "{ \"DeliveryOptionIds\": [ \"example1-2222-cccc-2222-cccccccccccc\" ] }"
    }
  ]
}

The following is information about the input fields you provide for adding the RestrictDeliveryOptions change type:

  • Entity (object) – Your container-based product. The Identifier is your product ID, and the type is always ContainerProduct@1.0. For information about using the Identifier, see Identifier.

  • Details (string) – Details of the request. It includes IDs for the delivery options of your container-based product that you would like to restrict. This field is a string field. The string is JSON, but it must be formatted properly for a single-line string field, including escaping characters (such as quotation marks) that cannot directly be in a string. For more information, see Working with the Details attribute.

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

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"
}

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 in the Catalog API with the DescribeChangeSet action. For more information about change sets, see Working with change sets. For more information about errors in seller product change sets, see Change set status and errors.

Errors in the container products API

The following errors are specific to the container product 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.

Change type Error code Error message

AddDeliveryOptions

INCOMPATIBLE_PRODUCT_STATUS

Use an existing limited or public product.

AddDeliveryOptions

INCOMPATIBLE_SERVICES

Provide a valid list of compatible services.

AddDeliveryOptions

NO_SERVICE_SPECIFIED

Provide at least 1 compatible service.

AddDeliveryOptions

DUPLICATE_COMPATIBLE_AWS_SERVICES

Provide unique list of compatible services.

AddDeliveryOptions

INVALID_VERSION_TITLE

Remove spaces before the trademark symbol.

AddDeliveryOptions

INVALID_VERSION_TITLE

Remove the following unsupported characters: [x, y, z]

AddDeliveryOptions

INVALID_VERSION_TITLE

Remove spaces from the beginning of the version title.

AddDeliveryOptions

INVALID_VERSION_TITLE

Provide version title with fewer than [x] characters.

AddDeliveryOptions

DUPLICATE_VERSION_TITLE

The version title must be different from any other version titles of this product.

AddDeliveryOptions

INVALID_RELEASE_NOTES

Remove spaces before the trademark symbol.

AddDeliveryOptions

INVALID_RELEASE_NOTES

Remove unsupported characters: [x, y, z]

AddDeliveryOptions

INVALID_RELEASE_NOTES

Remove spaces from the beginning of release notes.

AddDeliveryOptions

INVALID_RELEASE_NOTES

Provide release notes with fewer than (x) characters.

AddDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Remove spaces before the trademark symbol.

AddDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Remove unsupported characters: [x, y, z]

AddDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Provide usage instructions with fewer than (x) characters.

AddDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Provide usage instructions.

AddDeliveryOptions

MISSING_CONTAINER_IMAGES

Provide at least 1 container image.

AddDeliveryOptions

NO_LICENSE_SECRET_KEYS

For Amazon EKS Anywhere products, provide 1 override parameter for license secret. Needs DefaultValue of "${AWSMP_LICENSE_SECRET}", see example in section.

AddDeliveryOptions

TOO_MANY_CONTAINER_IMAGES

Provide fewer than 50 container images.

AddDeliveryOptions

DUPLICATE_CONTAINER_IMAGES

Provide a unique list of container images.

AddDeliveryOptions

INVALID_CONTAINER_IMAGES

Provide a valid URI for the container image.

AddDeliveryOptions

INVALID_CONTAINER_IMAGE_URI

Provide a valid URI for the container image.

AddDeliveryOptions

INVALID_CONTAINER_IMAGE_TAG

Avoid using 'latest' tag.

AddDeliveryOptions

DUPLICATE_DELIVERY_OPTION_TITLES

Provide unique delivery option title.

AddDeliveryOptions

INVALID_DELIVERY_OPTION_TITLES

Delivery option title already exists, retry with a different title.

AddDeliveryOptions

INVALID_FULFILLMENT_OPTION_TITLE

Provide delivery option title with fewer than (x) characters.

AddDeliveryOptions

DUPLICATE_DELIVERY_OPTION_TITLES

Provide unique delivery option title.

AddDeliveryOptions

NO_SERVICE_ACCOUNT_CONFIGURATION

For paid products, provide 1 override parameter for service account configuration. Needs DefaultValue of "${AWSMP_SERVICE_ACCOUNT}", see example in section.

AddDeliveryOptions

Provided Details is not valid.

AddDeliveryOptions

EMPTY_RESOURCE_NAME

Provide resource name.

AddDeliveryOptions

EMPTY_RESOURCE_URL

Provide resource URL.

AddDeliveryOptions

INVALID_RESOURCE_NAME

Provide resource name with fewer than 256 characters.

AddDeliveryOptions

INVALID_RESOURCE_URL

Provide resource URL with fewer than 256 characters.

AddDeliveryOptions

INVALID_SHORT_DESCRIPTION

Provide a short description with fewer than 1,000 characters.

AddDeliveryOptions

INVALID_SHORT_DESCRIPTION

Provide short description.

AddDeliveryOptions

SCAN_ERROR

Fix security vulnerability ""[y]"" on Image ""[x]"".

AddDeliveryOptions

IMAGE_NOT_FOUND

Provide a valid public image URI.

AddDeliveryOptions

INVALID_ARN

Provide a valid ARN for image access.

AddDeliveryOptions

IMAGE_INACCESSIBLE

Provide a valid ARN for image access.

RestrictDeliveryOptions

INCOMPATIBLE_PRODUCT_STATUS

Use a public product.

RestrictDeliveryOptions

MISSING_DELIVERY_OPTION_IDS

Provide delivery option from existing list of IDs.

RestrictDeliveryOptions

INVALID_DELIVERY_OPTIONS_STATUS

Provide delivery options in public state.

RestrictDeliveryOptions

EMPTY_DELIVERY_OPTION_IDS

Provide non-empty list of delivery option IDs.

RestrictDeliveryOptions

INVALID_MINIMUM_PUBLIC_DELIVERY_OPTIONS

Cannot restrict all delivery option IDs.

RestrictDeliveryOptions

DUPLICATE_DELIVERY_OPTION_IDS

Provide unique delivery option IDs.

UpdateDeliveryOptions

INCOMPATIBLE_PRODUCT_STATUS

Use an existing limited or public product.

UpdateDeliveryOptions

INCOMPATIBLE_SERVICES

Provide a valid list of compatible services.

UpdateDeliveryOptions

NO_SERVICE_SPECIFIED

Provide at least 1 compatible service.

UpdateDeliveryOptions

DUPLICATE_COMPATIBLE_AWS_SERVICES

Provide unique list of compatible services.

UpdateDeliveryOptions

INVALID_VERSION_TITLE

Remove spaces before the trademark symbol.

UpdateDeliveryOptions

INVALID_VERSION_TITLE

Remove the following unsupported characters: [x, y, z]

UpdateDeliveryOptions

INVALID_VERSION_TITLE

Remove spaces from the beginning of the version title.

UpdateDeliveryOptions

INVALID_VERSION_TITLE

Provide version title with fewer than [x] characters.

UpdateDeliveryOptions

DUPLICATE_VERSION_TITLE

The version title must be different from any other version titles of this product.

UpdateDeliveryOptions

INVALID_RELEASE_NOTES

Remove spaces before the trademark symbol.

UpdateDeliveryOptions

INVALID_RELEASE_NOTES

Remove unsupported characters: [x, y, z]

UpdateDeliveryOptions

INVALID_RELEASE_NOTES

Remove spaces from the beginning of release notes.

UpdateDeliveryOptions

INVALID_RELEASE_NOTES

Provide release notes with fewer than (x) characters.

UpdateDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Remove spaces before the trademark symbol.

UpdateDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Remove unsupported characters: [x, y, z]

UpdateDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Provide usage instructions with fewer than (x) characters.

UpdateDeliveryOptions

INVALID_USAGE_INSTRUCTIONS

Provide usage instructions.

UpdateDeliveryOptions

MISSING_CONTAINER_IMAGES

Provide at least 1 container image.

UpdateDeliveryOptions

TOO_MANY_CONTAINER_IMAGES

Provide fewer than 50 container images.

UpdateDeliveryOptions

DUPLICATE_CONTAINER_IMAGES

Provide a unique list of container images.

UpdateDeliveryOptions

INVALID_CONTAINER_IMAGES

Provide a valid URI for the container image.

UpdateDeliveryOptions

INVALID_CONTAINER_IMAGE_URI

Provide a valid URI for the container image.

UpdateDeliveryOptions

INVALID_CONTAINER_IMAGE_TAG

Avoid using 'latest' tag.

UpdateDeliveryOptions

MISSING_DELIVERY_OPTION_IDS

Provide delivery option from existing list of Ids.

UpdateDeliveryOptions

EMPTY_DELIVERY_OPTION_IDS

Provide non-empty list of delivery option IDs.

UpdateDeliveryOptions

DUPLICATE_DELIVERY_OPTION_IDS

Provide unique delivery option IDs.

UpdateDeliveryOptions

DUPLICATE_DELIVERY_OPTION_TITLES

Provide unique delivery option title.

UpdateDeliveryOptions

INVALID_DELIVERY_OPTION_TITLES

Delivery option title already exists, retry with a different title.

UpdateDeliveryOptions

INVALID_FULFILLMENT_OPTION_TITLE

Provide delivery option title with fewer than (x) characters.

UpdateDeliveryOptions

DUPLICATE_DELIVERY_OPTION_TITLES

Provide unique delivery option title.

UpdateDeliveryOptions

EMPTY_RESOURCE_NAME

Provide resource name.

UpdateDeliveryOptions

EMPTY_RESOURCE_URL

Provide resource URL.

UpdateDeliveryOptions

INVALID_RESOURCE_NAME

Provide resource name with fewer than 256 characters.

UpdateDeliveryOptions

INVALID_RESOURCE_URL

Provide resource URL with fewer than 256 characters.

UpdateDeliveryOptions

INVALID_SHORT_DESCRIPTION

Provide a short description with fewer than 1,000 characters.

UpdateDeliveryOptions

INVALID_SHORT_DESCRIPTION

Provide short description.

UpdateDeliveryOptions

NO_LICENSE_SECRET_KEYS

For Amazon EKS Anywhere products, provide 1 override parameter for license secret. Needs DefaultValue of "${AWSMP_LICENSE_SECRET}", see example in section.

UpdateDeliveryOptions

NO_SERVICE_ACCOUNT_CONFIGURATION

For paid products, provide 1 override parameter for service account configuration. Needs DefaultValue of "${AWSMP_SERVICE_ACCOUNT}", see example in section.

UpdateDeliveryOptions

SCAN_ERROR

Fix security vulnerability ""[y]"" on Image ""[x]"".

UpdateDeliveryOptions

FIELD_NOT_ALLOWED_TO_CHANGE

Field [x] cannot be changed.

UpdateDeliveryOptions

INVALID_DELIVERY_OPTIONS_STATUS

Provide delivery options in public or limited state.

UpdateDeliveryOptions

NO_CHANGE_FOUND

Provide at least 1 change.

UpdateDeliveryOptions

MULTIPLE_VERSION_UPDATE

Provide delivery option IDs from the same version.

AddRepositories

INVALID_ECR_REPOSITORY_NAME

Provide repository name in the format: 'nginx-web-app'

AddRepositories

DUPLICATE_ECR_REPOSITORY_NAME

The repository name must be unique.

AddRepositories

MISSING_REPOSITORY_INFORMATION

Provide at least 1 repository name.

AddRepositories

INVALID_ECR_REPOSITORY_NAME

Maximum character length 256 reached. Character length count is inclusive of the seller namespace.

UpdateInformation

MISSING_UPDATES

Nothing to update. Provide updated information for product.

UpdateInformation

MISSING_LOGO_URL

Provide URL for logo stored in S3.

UpdateInformation

LOGO_COPY_FAILURE

There was an issue copying the logo from S3. Provide a new URL for logo stored in S3.

UpdateInformation

INVALID_CATEGORY_NAMES

Provide valid category names supported by AWS Marketplace.

UpdateInformation

INVALID_PRODUCT_TITLE

Remove spaces before trademark symbol.

UpdateInformation

INVALID_PRODUCT_TITLE

Remove unsupported characters [x, y, z]

UpdateInformation

INVALID_SHORT_DESCRIPTION

Remove spaces before trademark symbol.

UpdateInformation

INVALID_SHORT_DESCRIPTION

Remove unsupported characters [x, y, z]

UpdateInformation

INVALID_LONG_DESCRIPTION

Remove spaces before trademark symbol.

UpdateInformation

INVALID_LONG_DESCRIPTION

Remove unsupported characters [x, y, z].

UpdateInformation

INVALID_SUPPORT_DESCRIPTION

Remove spaces before trademark symbol.

UpdateInformation

INVALID_SUPPORT_DESCRIPTION

Remove unsupported characters [x, y, z].

UpdateInformation

INVALID_HIGHLIGHTS

Remove spaces before trademark symbol.

UpdateInformation

INVALID_HIGHLIGHTS

Remove unsupported characters [x, y, z].

UpdateInformation

INVALID_ADDITIONAL_RESOURCES

Remove spaces before trademark symbol.

UpdateInformation

INVALID_ADDITIONAL_RESOURCES

Remove unsupported characters [x, y, z].

UpdateInformation

INVALID_PRODUCT_CATEGORIES

Provide between 1 and 3 product categories.

UpdateInformation

INVALID_IMAGE_PROPERTIES

Provide an image that meets the product logo requirements. (link)