Work with seller products

You can use the AWS Marketplace Catalog API to automate tasks for working with seller products. This includes the ability to create, update, view, list, and sort products. This enables you to automate the management of your products including self-service publishing capabilities on the AWS Marketplace Management Portal.

A product is a unit or resource that sellers intend to sell in AWS Marketplace, often referred to as a base product. A base product is not complete for buyer consumption until product information, deployment attributes, and billing information are added.

A product describes the product information, software deployment attributes, and billing mechanism of the listing that a seller intends to sell. The product must be paired with an offer to become a transactable unit that can be sold and be used by buyers in AWS Marketplace.

You can also use the AWS Marketplace Catalog API to Work with private offers using the AWS Marketplace APIs, Work with resale authorizations using the AWS Marketplace APIs, or Work with channel partner private offers using the AWS Marketplace APIs.

Each product type has a different product entity. The following product types and entities are supported:

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

See the following resources:

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

Create a product

You can use the Catalog API to create an AMI, container, or SaaS product document with identifiers (product code and product ID) in AWS Marketplace.

You create a product in Draft state by calling the StartChangeSet API operation with the CreateProduct change type.

If your request is processed successfully, then AWS Marketplace Catalog API generates a product in Draft state for you. This is an incomplete product and isn’t visible to buyers in AWS Marketplace.

You then use Update change types to complete the create product process: UpdateInformation, UpdateDimensions, UpdateTargeting, and UpdateVisibility.

After the product is completed, you can use the ReleaseProduct change type to complete the product creation process, and then release the offer. This process validates the entire product and moves the product to the Limited state.

To create a product in Draft state, call the StartChangeSet API operation with the CreateProduct change type, as shown in the following example.

Request Syntax

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

{
"Catalog": "AWSMarketplace",
"ChangeSet": [ 
  { 
    "ChangeType":"CreateProduct",
    "Entity":{
      "Type": "SaaSProduct@1.0" // choose from ["AmiProduct@1.0", "ContainerProduct@1.0", "SaaSProduct@1.0"]
     },
     "DetailsDocument": {
        "ProductTitle": "Test product title set in CreateProduct"
     }
  }
]
}

Provide information for the fields to add the CreateProduct change type. This change type can take in ProductTitle attribute, subject to the same restrictions as that sent into UpdateInformation change type.

Response Syntax

A change set is created for your request. The response to this request gives you the ChangeSetId and ChangeSetArn for the change set and looks like the following.

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

The change request is added to a queue and processed.

You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the DescribeChangeSet API operation.

When the request is complete (if the Status is SUCCEEDED), a new ProductId is generated.

Synchronous Validations

The following schema validations are specific to CreateProduct actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

Asynchronous Errors

The following errors are specific to CreateProduct actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more details about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Update product details

If you already have a product in AWS Marketplace, you can use the Catalog API to update the product details for an AMI, container, or SaaS product.

To update product details, call the StartChangeSet API operation with the UpdateInformation change type and the details that you want to change, as shown in the following example.

Request Syntax

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateInformation",
      "Entity":
      {
        "Identifier": "prod-example12345",
        "Type": "AmiProduct@1.0"
      },
      "DetailsDocument":
      {
        "ProductTitle": "My Product Title",
        "ShortDescription": "My product short description.",
        "LongDescription": "My product longer description.",
        "Sku": "123example456",
        "LogoUrl": "https://awsmp-logos.s3.amazonaws.com/ca60b754fe05a24257176cdbf31c4e0d",
        "VideoUrls":
        [
          "https://example.com/my-video"
        ],
        "Highlights":
        [
          "123example45"
        ],
        "AdditionalResources":
        [
          {
            "Text": "123example456",
            "Url": "https://example.com/some-link"
          }
        ],
        "SupportDescription": "Need help? Contact our experts at support@example.com \n\nYour purchase includes 24x7 support.",
        "Categories":
        [
          "Operating Systems",
          "Network Infrastructure",
          "Application Development"
        ],
        "SearchKeywords":
        [
          "123example456"
        ]
      }
    }
  ]
}

Provide information for the fields to add the UpdateInformation change type:

Response Syntax

A change set is created for your request. The response to this request gives you the ChangeSetId and ChangeSetArn for the change set and looks like the following.

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

The change request is added to a queue and processed.

You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the DescribeChangeSet API operation.

Synchronous Validations

The following schema validations are specific to UpdateInformation actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

Asynchronous Errors

The following errors are specific to UpdateInformation actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Add pricing dimensions

You can use the Catalog API to add billable dimensions in order to charge users for an AMI, container, or SaaS product in AWS Marketplace.

A pricing dimension is a unit of measure that sellers define for charging buyers. Sellers must set up this information to bill buyers for using the product, whether it’s a usage-based or contract- based pricing model. The type of dimension is dependent on the intended product’s pricing model. For more information about product pricing, see AMI product pricing, Container products pricing, and SaaS product pricing in the AWS Marketplace Seller Guide.

To add pricing dimensions, call the StartChangeSet API operation with the AddDimensions change type, as shown in the following example.

Request Syntax

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "AddDimensions",
      "DetailsDocument":
      [
        {
          "Description": "Description of the dimension",
          "Key": "uniqueapikey",
          "Unit": "HostHrs",
          "Name": "First Dimension",
          "Types":
          [
            "ExternallyMetered"
          ]
        }
      ],
      "Entity":
      {
        "Identifier": "prod-example12345",
        "Type": "SaaSProduct@1.0"
      }
    }
  ]
}

Provide information for the fields to add the AddDimensions 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 includes validating information to ensure it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours.

You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the DescribeChangeSet API operation.

Synchronous Validations

The following schema validations are specific to AddDimensions actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

Asynchronous Errors

The following errors are specific to AddDimensions actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Update pricing dimensions

You can use the Catalog API to update existing pricing dimensions of an AMI, container, or SaaS product in AWS Marketplace.

Each dimension is uniquely identified by the dimension key and dimension types to perform the update. Updating a dimension doesn’t affect any active offer or customers that the original dimension had created.

To update pricing dimensions, call the StartChangeSet API operation with the UpdateDimensions change type, as shown in the following example.

Request Syntax

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateDimensions",
      "DetailsDocument":
      [
        {
          "Key": "uniqueapikey",
          "Types":
          [
            "ExternallyMetered"
          ],
          "Name": "First Dimension",
          "Description": "Description of the dimension"
        }
      ],
      "Entity":
      {
        "Identifier": "prod-example12345",
        "Type": "SaaSProduct@1.0"
      }
    }
  ]
}

Provide information for the fields to add the UpdateDimensions 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 UpdateDimensions actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

Asynchronous Errors

The following errors are specific to UpdateDimensions actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Restrict pricing dimensions

You can use the Catalog API to restrict existing pricing dimensions of an AMI or SaaS product in AWS Marketplace.

Each dimension is uniquely identified by the dimension key and dimension types to perform the update. Restricting a dimension doesn’t affect any active offer or customers that the original dimension had created.

To restrict pricing dimensions, call the StartChangeSet API operation with the RestrictDimensions change type, as shown in the following example.

Request Syntax

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "RestrictDimensions",
      "DetailsDocument":
      [
        {
          "Key": "uniqueapikey",
          "Types": "First Dimension"
        }
      ],
      "Entity":
      {
        "Identifier": "prod-example12345",
        "Type": "SaaSProduct@1.0"
      }
    }
  ]
}

Provide information for the fields to add the RestrictDimensions 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 RestrictDimensions actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

Asynchronous Errors

The following errors are specific to RestrictDimensions 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 targeting configuration

You can use the Catalog API to add AWS account IDs that are allowed to view the AMI, container, or SaaS product in AWS Marketplace before it’s moved to a Public state by calling the UpdateVisibility change type.

To add AWS account IDs that are allowed to view the AMI, container, or SaaS product, call the StartChangeSet API operation with the UpdateTargeting change type, as shown in the following example.

Request Syntax

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateTargeting",
      "Entity":
      {
        "Type": "SaaSProduct@1.0",
        "Identifier": "prod-example12345"
      },
      "DetailsDocument":
      {
        "PositiveTargeting":
        {
          "BuyerAccounts":
          [
            "1112223334444"
          ]
        }
      }
    }
  ]
}

Provide information for the fields to add the UpdateTargeting 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.

When the request is complete (if the Status is SUCCEEDED), a new ProductId is generated.

Synchronous Validations

The following schema validations are specific to UpdateTargeting actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

Asynchronous Errors

The following errors are specific to DescribeChangeSet actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Update product visibility

You can use the Catalog API to update the visibility (also known as lifecycle state) of an AMI, container, or SaaS product in AWS Marketplace.

Allowed target lifecycle states are Limited, Public, or Restricted.

To update the visibility of your product, call the StartChangeSet API operation with the UpdateVisibility change type, as shown in the following example.

Request Syntax

For when TargetVisibility is Public or Limited.

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateVisibility",
      "Entity":
      {
        "Type": "SaaSProduct@1.0",
        "Identifier": "prod-example12345"
      },
      "DetailsDocument":
      {
        "TargetVisibility": "Public"
      }
    }
  ]
}

For when TargetVisibility is Restricted.

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateVisibility",
      "Entity":
      {
        "Type": "SaaSProduct@1.0",
        "Identifier": "prod-example12345"
      },
      "DetailsDocument":
      {
        "TargetVisibility": "Restricted",
        "ReplacementProductId": "prod-example54321"
      }
    }
  ]
}

Provide information for the fields to add the UpdateVisibility change type.

Synchronous Validations

The following schema validations are specific to UpdateVisibility actions in the AWS Marketplace Catalog API. These validations are performed when you call StartChangeSet. If the request doesn’t meet the following requirements, it will fail with an HTTP response.

After triggering this change type, it can take up to 37 days to complete. This includes the time the AWS Marketplace Seller Operations Team needs to review, audit, and approve. When restricting a product, you have 24 hours to change your mind, by calling CancelChangeSet, before the AWS Marketplace Seller Operations Team begins auditing. For more information, see CancelChangeSet.

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.

When the request is complete (if the Status is SUCCEEDED), a new ProductId is generated.

Asynchronous Errors

The following errors are specific to UpdateVisibility actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Publish a product

You can use the Catalog API to publish a Draft AMI, container, or SaaS product into Limited state in AWS Marketplace.

To publish a product, call the StartChangeSet API operation with the ReleaseProduct change type, as shown in the following example.

Request Syntax

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "ReleaseProduct",
      "Entity":
      {
        "Type": "SaaSProduct@1.0",
        "Identifier": "prod-example12345"
      },
      "DetailsDocument": {}
    }
  ]
}

Provide information for the fields to add to the ReleaseProduct change type. This change type does not take any parameter payload.

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.

When the request is complete (if the Status is SUCCEEDED), a new ProductId is generated.

Asynchronous Errors

The following errors are specific to ReleaseProduct actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Find your product ID

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

The following topics explain how to find a product by filtering on entity id, product title, last modified date, or visibility.

Find a product based on product title

Request

POST /ListEntities HTTP/1.1
Content-Type: application/json
      
{
    "Catalog": "AWSMarketplace",
    "EntityType": "AmiProduct",
    "MaxResults": 10,
    "EntityTypeFilters": {
        "AmiProductFilters": {
            "ProductTitle": {
                "WildCardValue": "XYZ"
            }
        }
    }
}

Response

HTTP/1.1 200
Content-type: application/json

{ 
  "EntitySummaryList": [ 
    { 
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
      "EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
      "EntityType": "AmiProduct",
      "LastModifiedDate": "2018-02-27T13:45:22Z",
       "AmiProductSummary": {
            "ProductTitle": "ABC-XYZ-123",
            "Visibility": "Public"
       }
    } 
  ],
  "NextToken": "" 
}

Find a product based on last modified date

Request

POST /ListEntities HTTP/1.1
Content-Type: application/json
      
{
    "Catalog": "AWSMarketplace",
    "EntityType": "AmiProduct",
    "MaxResults": 10,
    "EntityTypeFilters": {
        "AmiProductFilters": {
            "LastModifiedDate": {
                "DateRange": {
                    "BeforeValue": "2018-03-27T13:45:22Z",
                    "AfterValue": "2018-01-27T13:45:22Z"
                }
            }
        }
    }
}

Response

HTTP/1.1 200
Content-type: application/json

{ 
  "EntitySummaryList": [ 
    { 
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
      "EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
      "EntityType": "AmiProduct",
      "LastModifiedDate": "2018-02-27T13:45:22Z",
       "AmiProductSummary": {
            "ProductTitle": "ABC-XYZ-123",
            "Visibility": "Public"
       }
    } 
  ],
  "NextToken": "" 
}

Find a product based on product visibility

Request

POST /ListEntities HTTP/1.1
Content-Type: application/json
      
{
    "Catalog": "AWSMarketplace",
    "EntityType": "AmiProduct",
    "MaxResults": 10,
    "EntityTypeFilters": {
        "AmiProductFilters": {
            "Visibility": {
                "ValueList": [
                    "Public"
                ]
            }
        }
    }
}

Response

HTTP/1.1 200
Content-type: application/json

{ 
  "EntitySummaryList": [ 
    { 
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
      "EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
      "EntityType": "AmiProduct",
      "LastModifiedDate": "2018-02-27T13:45:22Z",
       "AmiProductSummary": {
            "ProductTitle": "ABC-XYZ-123",
            "Visibility": "Public"
       }
    } 
  ],
  "NextToken": "" 
}

Find a product based on product title, last modified date, and product visibility

Request

POST /ListEntities HTTP/1.1
Content-Type: application/json
      
{
    "Catalog": "AWSMarketplace",
    "EntityType": "AmiProduct",
    "MaxResults": 10,
    "EntityTypeFilters": {
        "AmiProductFilters": {
            "LastModifiedDate": {
                "DateRange": {
                    "BeforeValue": "2018-03-27T13:45:22Z",
                    "AfterValue": "2018-01-27T13:45:22Z"
                }
            },
            "Visibility": {
                "ValueList": [
                    "Public"
                ]
            },
            "ProductTitle": {
                "ValueList": [
                    "ABC-XYZ-123"
                ]
            }
        }
    }
}

Response

HTTP/1.1 200
Content-type: application/json

{ 
  "EntitySummaryList": [ 
    { 
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
      "EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
      "EntityType": "AmiProduct",
      "LastModifiedDate": "2018-02-27T13:45:22Z",
       "AmiProductSummary": {
            "ProductTitle": "ABC-XYZ-123",
            "Visibility": "Public"
       }
    } 
  ],
  "NextToken": "" 
}

Get additional details about a product

You can get additional details about the product using the entity id with the DescribeEntity action.

Request

GET /DescribeEntity?catalog=AWSMarketplace&entityId=example-abcd-1234 HTTP/1.1

Response

HTTP/1.1 200
Content-type: application/json

{
   "DetailsDocument": {
        "ProductTitle": "ABC-XYZ-123",
        "ShortDescription": "My product short description.", 
        "LongDescription": "My product longer description.", 
        "Sku": "123example456", 
        "SupportDescription": "Need help? Contact our experts at support@example.com \n\nYour purchase includes 24x7 support.", 
        "Categories": [ 
            "Operating Systems", 
            "Network Infrastructure", 
            "Application Development" 
            ] 
   }
    "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example-abcd-1234",
    "EntityId": "example1-abcd-1234-5ef6-7890abcdef12@1",
    "EntityType": "AmiProduct",
    "LastModifiedDate": "2018-02-27T13:45:22Z",
}

Change set status and errors

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

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

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

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

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

{
   "Catalog": "AWSMarketplace",
   "ChangeSetID": "example123456789012abcdef"
}

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

{
  "ChangeSetId": "example123456789012abcdef",
  "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef",
  "ChangeSetName": "Submitted by 123456789012",
  "StartTime": "2020-10-27T22:21:26Z",
  "EndTime": "2020-10-27T22:32:19Z",
  "Status": "SUCCEEDED",
  "ChangeSet":
  [
    {
      "ChangeType": "AddDeliveryOptions",
      "Entity":
      {
        "Type": "ContainerProduct@1.0",
        "Identifier": "example-1234-abcd-56ef-abcdef12345678@4"
      },
      "Details": "{\"Version\": {\"VersionTitle\": \"1.1\",\"ReleaseNotes\": \"Minor bug fix\"},\"DeliveryOptions\": [{\"DeliveryOptionTitle\": \"EKSDelivery\",\"Details\": {\"EcrDeliveryOptionDetails\" : {\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"DeploymentResources\": [{\"Name\": \"HelmDeploymentTemplate\",\"Url\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}],\"CompatibleServices\": [\"EKS\"],\"Description\": \"Sample Description\",\"UsageInstructions\":\"helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}}},{\"DeliveryOptionTitle\": \"HelmChartDeliveryOption\",\"Details\": {\"HelmDeliveryOptionDetails\": {\"CompatibleServices\": [\"EKS\", \"EKS-Anywhere\"],\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"HelmChartUri\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1\",\"Description\": \"Helm chart description\",\"UsageInstructions\": \"Usage instructions\",\"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}}]}}}]}",
      "DetailsDocument":
      {
        "Version":
        {
          "VersionTitle": "1.1",
          "ReleaseNotes": "Minor bug fix"
        },
        "DeliveryOptions":
        [
          {
            "DeliveryOptionTitle": "EKSDelivery",
            "Details":
            {
              "EcrDeliveryOptionDetails":
              {
                "ContainerImages":
                [
                  "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
                ],
                "DeploymentResources":
                [
                  {
                    "Name": "HelmDeploymentTemplate",
                    "Url": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
                  }
                ],
                "CompatibleServices":
                [
                  "EKS"
                ],
                "Description": "Sample Description",
                "UsageInstructions": "helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
              }
            }
          },
          {
            "DeliveryOptionTitle": "HelmChartDeliveryOption",
            "Details":
            {
              "HelmDeliveryOptionDetails":
              {
                "CompatibleServices":
                [
                  "EKS",
                  "EKS-Anywhere"
                ],
                "ContainerImages":
                [
                  "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
                ],
                "HelmChartUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1",
                "Description": "Helm chart description",
                "UsageInstructions": "Usage instructions",
                "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
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "ErrorDetailList":
      []
    }
  ]
}

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

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

{
  "ChangeSetId": "example123456789012abcdef",
  "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef",
  "ChangeSetName": "Submitted by 123456789012",
  "StartTime": "2020-10-27T22:21:26Z",
  "EndTime": "2020-10-27T22:32:19Z",
  "Status": "FAILED",
  "FailureDescription": "Change set preparation has failed. For details see 'ErrorDetailList'.",
  "ChangeSet":
  [
    {
      "ChangeType": "AddDeliveryOptions",
      "Entity":
      {
        "Type": "ContainerProduct@1.0",
        "Identifier": "example-1234-abcd-56ef-abcdef12345678@4"
      },
      "Details": "{\"Version\": {\"VersionTitle\": \"1.1\",\"ReleaseNotes\": \"Minor bug fix\"},\"DeliveryOptions\": [{\"DeliveryOptionTitle\": \"EKSDelivery\",\"Details\": {\"EcrDeliveryOptionDetails\" : {\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"DeploymentResources\": [{\"Name\": \"HelmDeploymentTemplate\",\"Url\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}],\"CompatibleServices\": [\"EKS\"],\"Description\": \"Sample Description\",\"UsageInstructions\":\"helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1\"}}},{\"DeliveryOptionTitle\": \"HelmChartDeliveryOption\",\"Details\": {\"HelmDeliveryOptionDetails\": {\"CompatibleServices\": [\"EKS\", \"EKS-Anywhere\"],\"ContainerImages\": [\"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1\"],\"HelmChartUri\": \"111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1\",\"Description\": \"Helm chart description\",\"UsageInstructions\": \"Usage instructions\",\"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}}]}}}]}",
      "DetailsDocument":
      {
        "Version":
        {
          "VersionTitle": "1.1",
          "ReleaseNotes": "Minor bug fix"
        },
        "DeliveryOptions":
        [
          {
            "DeliveryOptionTitle": "EKSDelivery",
            "Details":
            {
              "EcrDeliveryOptionDetails":
              {
                "ContainerImages":
                [
                  "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
                ],
                "DeploymentResources":
                [
                  {
                    "Name": "HelmDeploymentTemplate",
                    "Url": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
                  }
                ],
                "CompatibleServices":
                [
                  "EKS"
                ],
                "Description": "Sample Description",
                "UsageInstructions": "helm pull 111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame2:mychart1.1"
              }
            }
          },
          {
            "DeliveryOptionTitle": "HelmChartDeliveryOption",
            "Details":
            {
              "HelmDeliveryOptionDetails":
              {
                "CompatibleServices":
                [
                  "EKS",
                  "EKS-Anywhere"
                ],
                "ContainerImages":
                [
                  "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:1.1"
                ],
                "HelmChartUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/sellername/reponame1:helmchart1.1",
                "Description": "Helm chart description",
                "UsageInstructions": "Usage instructions",
                "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
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "ErrorDetailList":
      [
        {
          "ErrorCode": "DUPLICATE_VERSION_TITLE",
          "ErrorMessage": "The version title must be different from any other version titles of this product."
        },
        {
          "ErrorCode": "SCAN_ERROR",
          "ErrorMessage": "https://123sample456.cloudfront.net/example-1234-abcd-5678-abcdef12345678/1234abcdef567890"
        }
      ]
    }
  ]
}

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