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.

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

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

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

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.

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

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.

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

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.

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, earlier in this guide.

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.

To restrict a version, call the StartChangeSet API operation with the RestrictDeliveryOptions change type, as shown in the following example.

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:

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.

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.

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:

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.

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.

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.

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

Restrict an AWS Region

You can use the Catalog API to restrict previously supported AWS Regions for your AMI-based product in AWS Marketplace.

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.

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

Add a new instance type

You can use the Catalog API to add new instance types for your AMI-based product in AWS Marketplace.

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.

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:

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.

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.

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.

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.

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.

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.

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.