Working with single AMI products - AWS Marketplace Catalog API
Add a new versionUpdate version informationRestrict a versionUpdate future AWS Region support Add a supported AWS RegionRestrict an AWS RegionAdd a new instance typeRestrict an instance type

Working with single AMI products

You can use the AWS Marketplace Catalog API to automate tasks for working with single Amazon Machine Image (AMI)-based products.

For information about creating a single AMI-based product using the Catalog API, see Create a product.

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

Note

You can also create a single AMI-based product using the AWS Marketplace Management Portal. For more information, see Single-AMI products 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 (5:08).

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

To add a new version, call the StartChangeSet API operation with the AddDeliveryOptions change type for single-AMI 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.

Note

For single-AMI products, a version is made up of a single delivery option, which is the AMI that you are making available. In the Catalog API, working with delivery options for single-AMI products modifies versions of your product.

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": "AmiProduct@1.0"
      },
      "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"
                },
                "UsageInstructions": "Easy to use AMI",
                "RecommendedInstanceType": "m4.xlarge",
                "SecurityGroups":
                [
                  {
                    "IpProtocol": "tcp",
                    "FromPort": 443,
                    "ToPort": 443,
                    "IpRanges":
                    [
                      "0.0.0.0/0"
                    ]
                  }
                ]
              }
            }
          }
        ]
      }
    }
  ],
  "Intent": "APPLY"
}

The following is information about the input fields you provide for adding the AddDeliveryOptions change type. For more information about these fields, see Adding a new 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.

    • 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 all the information about the new version of your AMI-based product.

    • Version (object) – Details about the software version you are adding. Made up of a title and release notes.

      • VersionTitle (string) – Unique name of the version. Displayed to end users in product details page and configuration pages for the product in AWS Marketplace.

      • ReleaseNotes (string) – Notes for buyers to tell them about changes from one version to the next.

    • DeliveryOptions (array) – List of DeliveryOption objects, including the details of each:

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

          • 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 (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 Marketplace to access the provided AMI. For details about creating and using this ARN, see Giving AWS Marketplace access to your AMI 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.

          • 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. For a list of instance types, see Instance types 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.

            • FromPort (integer) – The source port.

            • IpProtocol (string) – The protocol to use (tcp or udp).

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

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 API operation.

For more information about errors in seller product change sets, see Change set status and 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 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.

Error code Error message

INVALID_PRODUCT

 Use an existing limited or public product.

DUPLICATE_VERSION_TITLE

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

INVALID_VERSION_TITLE

 Remove spaces before the trademark symbol.

INVALID_VERSION_TITLE

 Remove unsupported characters: [x, y, z]

INVALID_VERSION_TITLE

 Remove spaces from the beginning of the version title.

INVALID_VERSION_TITLE

 Provide version title with fewer than [x] characters.

INVALID_RELEASE_NOTES

 Remove spaces before the trademark symbol.

INVALID_RELEASE_NOTES

 Remove unsupported characters: [x, y, z]

INVALID_RELEASE_NOTES

 Remove spaces from the beginning of release notes.

INVALID_RELEASE_NOTES

 Provide release notes with fewer than (x) characters.

INVALID_USAGE_INSTRUCTIONS

 Remove spaces before the trademark symbol.

INVALID_USAGE_INSTRUCTIONS

 Remove unsupported characters: [x, y, z]

INVALID_USAGE_INSTRUCTIONS

 Remove spaces from the beginning of release notes.

INVALID_USAGE_INSTRUCTIONS

 Provide usage instructions with fewer than (x) characters.

RECOMMENDED_INSTANCE_TYPE_NOT_AVAILABLE

 Provide an existing, available instance type.

INVALID_RECOMMENDED_INSTANCE_TYPE

 Provide a valid instance type.

INVALID_SECURITY_GROUP

 Security group ports must be between 1 and [max].

INVALID_SECURITY_GROUP

 Provide a value for CIDR IP ranges.

INVALID_SECURITY_GROUP

 Provide security group start port that is not greater than end port.

INVALID_SECURITY_GROUP_PROTOCOL

 Security group protocol must either be ‘tcp’ or ‘udp’.

INVALID_CIDR_IP

 Provide standard CIDR IP range in form '0.0.0.0/0'.

INVALID_ACCESS_ENDPOINT_PORT

 Provide endpoint port less than [x].

INVALID_ACCESS_ENDPOINT_PORT

 Provide endpoint port between 1 and [max].

INVALID_ACCESS_ENDPOINT_PORT

 Provide endpoint port.

INVALID_ACCESS_ENDPOINT_RELATIVE_PATH

 Remove spaces in the relative path.

INVALID_ACCESS_ENDPOINT_RELATIVE_PATH

 Remove preceding '/' from relative path.

INCOMPATIBLE_OPERATING_SYSTEM

 Provide operating system name and version that is compatible with instance types: [x]

INCOMPATIBLE_OPERATING_SYSTEM_NAME

 Provide name with fewer than (x) characters.

INCOMPATIBLE_OPERATING_SYSTEM_NAME

 Provide operating system name that is supported.

INCOMPATIBLE_OPERATING_SYSTEM_VERSION

 Provide version with fewer than (x) characters.

INVALID_SCANNING_PORT

 Provide scanning port between 1 and [max].

INVALID_AMI_ID

 Provide valid AMI ID.

EXISTING_AMI_PRODUCT_CODE

 Remove product code attached to image X.

INVALID_AMI_ARCHITECTURE

 Provide new AMI with architecture [x].

INVALID_AMI_VIRTUALIZATION_TYPE

 Provide new AMI with virtualization type [x].

INVALID_AMI_VIRTUALIZATION_TYPE

 Provide expected [z] volume on image [x].

INCOMPATIBLE_AMI

 Provide new AMI as architecture [x] on [y] is not supported by following instance types: [z]

INCOMPATIBLE_AMI

 Provide new AMI as virtualization type [x] on [y] is not supported by following instance types: [z]

INCOMPATIBLE_AMI

 Enable ENA support for image x because following instance types require ENA support: [y]

ASSET_NOT_FOUND

 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_ACCESS_EXCEPTION

 Unable to copy AMI [x] into AWS Marketplace account.

SCAN_ERROR

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

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

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

  • Entity (object) (required) – Your AMI-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: 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 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 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.

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 API operation.

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.

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.

Error code Error message
INVALID_PRODUCT Use an existing limited or public product.
MISSING_DELIVERY_OPTION_IDS Provide at least one delivery option ID.
INVALID_DELIVERY_OPTION_IDS Provide delivery option IDs that can be found in the product. IDs not found: [x]
INVALID_DELIVERY_OPTIONS 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 in AWS Marketplace. This prevents new buyers from being able to use that version. There must always be at least one unrestricted version of a product available, so you cannot restrict the last publicly available version for a product.

Note

For more information about restricting AMI versions in AWS Marketplace via the AWS Marketplace Management Portal, see Restricting a 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 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.

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

Error code Error message

INVALID_PRODUCT

 Use an existing public product.

MISSING_DELIVERY_OPTION_IDS

 Provide at least one delivery option ID.

INVALID_DELIVERY_OPTION_IDS

 Provide delivery option IDs that can be found in the product. IDs not found: [x]

INVALID_DELIVERY_OPTION

 Provide delivery option IDs that are in a public state. IDs not in public state: [x]

ALL_DELIVERY_OPTIONS_RESTRICTED

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

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

Error code Error message
TOO_MANY_REGIONS Currently, only 1 value is supported for FutureRegionSupport: All, US, or None
INVALID_REGIONS Requested Regions [a, b, c] are invalid or unavailable. Only supported values are [x, y, z].
INVALID_INPUT 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 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.

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

      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 API operation.

  • If the change set execution status is SUCCEEDED: A new Entity Identifier (or EntityId) is generated. You can use the DescribeEntity 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.

Error code Error message
INVALID_REGIONS Requested regions [a, b, c] are invalid or unavailable. Only supported values are [x, y, z].
INVALID_INPUT 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 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.

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

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

Error code Error message
INVALID_REGIONS Requested regions [a, b, c] are invalid or unavailable. Only supported values are [x, y, z].
INVALID_INPUT 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 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.

    • 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 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_.-]+$ 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.

Error code Error message
INVALID_INSTANCE_TYPES The following instance types are not valid: [x]
INVALID_INSTANCE_VIRTUALIZATION Virtualization of the product is [x]. It is not supported by the following instance types: [x]
INVALID_AMI_ARCHITECTURE CPU architecture of the product is '%s'." + "It is not supported by the following instance types: [x]
INCOMPATIBLE_OPERATING_SYSTEM 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_PRODUCT_TYPE Use an existing single AMI product.
INVALID_ENA_SETTING The product does not support ENA. ENA support is required by the following instance types: [x]
INVALID_DIMENSIONS No internally metered dimensions found for instance types: [x]
UPDATE_PRICING_REQUIRED 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 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.

    • 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 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_.-]+$ 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.

Error code Error message
INVALID_ INSTANCE_TYPES The following instance types are not valid: [x]
INVALID_ PRODUCT_TYPE Use an existing single AMI product.
DUPLICATE_INSTANCE_TYPE Provide instance types with no duplicates.
UNAVAILABLE_INSTANCE_TYPE Provide an available instance type.
RECOMMENDED_INSTANCE_TYPE_RESTRICTED 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_NOT_RESTICTED Restrict dimensions before restricting internally metered instance types: [x]
REGION_NO_INSTANCES Your restricted instance types would cause product launch failure in region: X. Consider restricting fewer instances.