AWS Marketplace Catalog API - AWS Marketplace Catalog API
Supported AWS RegionsCatalog API entitiesWorking with change setsWorking with the Details attributeUsing DescribeEntity

AWS Marketplace Catalog API

The AWS Marketplace Catalog API service provides an API interface to manage AWS Marketplace for your AWS organization or AWS account. For approved sellers, you can manage your products programmatically, including the self-service publishing capabilities on the AWS Marketplace Management Portal. For private marketplace administrators, you can manage your private marketplace programmatically.

With Catalog API actions, you can view and update your existing product programmatically. You can automate your product update process by integrating the AWS Marketplace Catalog API with your AWS Marketplace product build or deployment pipelines. You can also create your own applications on top of the Catalog API to manage your products on AWS Marketplace. You can manage the products that users in your AWS account or AWS organization can see and purchase through your private marketplace.

The AWS Marketplace Catalog API service provides standard AWS API functionality. You can directly use the REST APIs described here (see Getting Started with AWS to learn more about AWS application development), or you can use one of the AWS SDKs to access an API that's tailored to the programming language or platform that you're using. For more information, see AWS SDKs.

Supported AWS Regions

You can access the AWS Marketplace Catalog API from the US East (N. Virginia) AWS Region with the following endpoint. 

catalog.marketplace.us-east-1.amazonaws.com

Catalog API entities

AWS Marketplace entities are containers of data which serve different business purposes, such as a product or offer. Entities are categorized by types. Each entity type encapsulates data related to a specific business domain (for example, a product or a seller account).

To simplify this paradigm, entities are designed with some level of commonality in their structures. As a result, introducing a new business domain does not require you to learn a completely new structure.

General structure

The general structure of any entity is:

  • A named type with a version.

  • An identifier for the specific instance of the type.

  • One or more facets that include the attributes of the entity.

Type versioning

Every named type has a type and version associated with it, for example, EntityProduct@1.0. The type (EntityProduct) represents the classification of the content. The version (1.0) represents the structure of EntityProduct.

The version gives you details about the structure of the entity. The following describes when a version will be changed.

  • Existing entities won't be restructured without changing the version. Additions of optional new fields will result in a minor version update.

  • Any feature that fundamentally changes the structure of a type leads to a major version update. Examples include:

    • Removing a field

    • Renaming a field (different name for the same semantic)

    • Changing the semantic of an existing field (for example, changing the expected type)

  • A major version update can retain a subset of facets from the previous version.

  • Users are provided notifications and documentation for new versions.

Identifier

Each entity represents a unique thing within a business domain. To identify the unique thing, we use an identifier associating an EntityId with a RevisionId, for example, prod-ad8EXAMPLE651@3. In this example, the EntityId is prod-ad8EXAMPLE651 and the RevisionId is 3. Every successful change request to the entity will update the revision.

The following are important details about the Identifier.

  • Each entity is uniquely identified by its EntityId, which is the key to globally distinguish one entity from another.

  • Each published revision of an entity has a RevisionId. The revisionId, along with the EntityId, distinguish one published revision from another.

  • AWS Marketplace generates EntityIds and RevisionIds.

You can use the DescribeEntity action to find the details and the Identifier with the most recent revisionId.

The RevisionId is an optional part of requests to StartChangeSet (see Working with change sets). If you include a RevisionId, then the request to StartChangeSet will fail with a ValidationException if the RevisionId is not the latest revision of the entity. This allows you to implement optimistic locking in your application.

Note

When you include a RevisionId that is not the latest revision, the ValidationException message includes the latest RevisionId.

If you omit the RevisionId, the request is performed on the latest revision of the entity automatically.

Warning

Two requests to change the same object could result with one request overwriting the changes of the other request, as the second request rewrites data changed by the first request. Using RevisionIds in your requests prevents this issue by not allowing a change to an earlier revision to overwrite the current revision.

Facets

A facet is a logical grouping of attributes. An entity usually includes several facets which represent different aspects of the entity. The attributes within a facet have the following properties:

  • Each attribute has a unique name within the scope of the container it belongs to.

  • Attributes can be of a simple type (string, integer, or floating number).

  • Attributes can be of a complex type (container/structure or array).

Product entity

A software product you own and list on AWS Marketplace is represented by a product entity. Product entities have different types. Regardless of type, product entities have some common facets in addition to product type specific facets. The example below is an example of common facets: Description, PromotionalResources, RegionAvailability, and SupportInformation. Details is an example of a product type specific facet. 

{
  "Details": "{\"Description\":{}, \"PromotionalResources\":{}, \"RegionAvailability\":{}, \"SupportInformation\":{}}",
  "EntityArn": "arn:aws:aws-marketplace:us-east-1:0123456789012:AWSMarketplace/Entity-Type/prod-9EXAMPLE01234,
  "EntityIdentifier": "prod-9EXAMPLE01234@23",
  "EntityType": "Entity-Type@1.0",
  "LastModifiedDate": "2019-07-31T21:59:39Z"
}

The Details facet is a string that includes JSON. For more information, see Working with the Details attribute.

Working with change sets

When using the Catalog API, you perform many actions by creating change requests. You do this by creating and working with change sets. A change set is a list of change entities, each of which represents a request for a change in AWS Marketplace. You can make changes to the products that you provide (as a seller), or to the private marketplace that you maintain (as a buyer).

Note

Although you can request multiple changes in a single change set, you cannot request conflicting changes. You will receive a ResourceInUseException error in this case. This is true even across multiple change sets. If you want to modify the same entity twice, the safest way is to make a request, wait for it to complete, and then request the next change. For information about using RevisionIds in this case, see Identifier).

There are four actions that allow you to work with change sets:

  • StartChangeSet – Requests a set of changes. The changes are added to a queue and processed.

  • DescribeChangeSet – Gets the details of a set of changes, including the status of the request. The statuses include:

    • PREPARING – Getting ready to apply the changes.

    • APPLYING – In the process of making the requested changes.

    • SUCCEEDED – Request was completed successfully.

    • CANCELED – Request was canceled by the user.

    • FAILED – Request was completed unsuccessfully. Further details are available in the response.

  • ListChangeSets – Gets a list of the change sets that are currently in process.

  • CancelChangeSet – Requests a change set be canceled. Changes can only be canceled while in the PREPARING status.

A typical workflow is to request a change with StartChangeSet, and then use the returned ChangeSetId to poll the DescribeChangeSet action until the change is complete.

Note

When polling or working with change sets programmatically, you must adhere to the Service limits.

After your change is complete, you can use ListEntities to find the entity that you created or modified (and its associated EntityID). You can then use DescribeEntity with the EntityID to get details about it.

For more information about working with change requests in the console for sellers, see Creating a change request in the AWS Marketplace Seller Guide.

Working with the Details attribute

The Details attribute of the StartChangeSet operation is a string value. Its contents are JSON objects. To put a JSON object into a string attribute, you must convert the object to a single-line string by escaping all JSON control characters, and removing line breaks.

For example, if you are using the StartChangeSet operation with UpdateProcurementPolicy to disable requests from users in your private marketplace, make a request like the following. 

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

{
   "Catalog": "AWSMarketplace",
   "ChangeSet": [ 
      { 
         "ChangeType": "UpdateProcurementPolicy",
         "Details": "<string>",
         "Entity": {
            "Type": "Experience@1.0",
            "Identifier" : "exp-1234example@5"
         }
      }
   ]
}

In this case, the JSON object that you use for the Details attribute looks like the following (before conversion to a string). 

{
    "Configuration": {
        "PolicyResourceRequests": "Deny"
    }
}

But the Details attribute requires a string, not JSON. After converting this JSON object to a single line string, it looks like the following. 

"{\"Configuration\" : {\"PolicyResourceRequests\" : \"Deny\"}}"

With this string, you can create the full change set request, as follows.

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

{
   "Catalog": "AWSMarketplace",
   "ChangeSet": [ 
      { 
         "ChangeType": "UpdateProcurementPolicy",
         "Details": "{\"Configuration\" : {\"PolicyResourceRequests\" : \"Deny\"}}",
         "Entity": {
            "Type": "Experience@1.0",
            "Identifier" : "exp-1234example@5"
         }
      }
   ]
}

Generally, examples in this API reference show the JSON object already converted to a string. In some cases, more complicated samples with new lines are included to enhance understanding.

Automate converting JSON to a string

Converting a JSON object to a string can be automated using tools such as jq, a lightweight command-line JSON processor. The following example shows using jq to convert a JSON object to a string that can be used in the Details attribute. 

DETAILS_JSON='{
  "ProductTitle": "My Product Title",
  "ShortDescription": "My product short description.",
  "LongDescription": "My product long description."
}';

DETAILS_JSON_STRING="$(echo "${DETAILS_JSON}" | jq 'tostring';)";

If you echo "${DETAILS_JSON_STRING}", the result is the following string with JSON properly escaped: {\"ProductTitle\":\"My Product\",\"ShortDescription\":\"My product short description.\",\"LongDescription\":\"My product long description.\"}

Using DescribeEntity to get information about your entities

You can programmatically get information about your existing entities, including products and private marketplace, through the Catalog API.

The ListEntities action returns a list of entities. Then, you can use the DescribeEntity action to get details about an individual entity. This can be directly useful, for example, to catalog the products you sell. It can also be useful when updating entities, because you can get the current state of the entity before updating just the parts that you want to update.

The following example shows using ListEntities to get a list of container products, and then using DescribeEntity to get information about one of the specific products. 

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

{
  "Catalog": "AWSMarketplace",
  "EntityType": "ContainerProduct"
}

For the entity type, you must use the entity type without the version. It returns all entities of that type (and doesn't filter on version).

Here is a sample of the response to the ListEntities action. 

{
    "EntitySummaryList": [
        {
            "Name": "Container Product 1",
            "EntityType": "ContainerProduct",
            "EntityId": "example1-abcd-1234-5ef6-7890abcdef12",
            "EntityArn": "arn:aws:aws-marketplace:[exampleARN]",
            "LastModifiedDate": "2021-03-01T00:00:00Z",
            "Visibility": "Public"
        },
        {
            "Name": "Container Product 2",
            "EntityType": "ContainerProduct",
            "EntityId": "example2-abcd-1234-5ef6-7890abcdef12",
            "EntityArn": "arn:aws:aws-marketplace:[exampleARN]",
            "LastModifiedDate": "2021-03-02T00:00:00Z",
            "Visibility": "Public"
        }
    ],
    "NextToken": "exampleabcdef12345..."
}

To get the details of one of these products, use the DescribeEntity action. The following example shows how to get details about the first product returned above. 

GET /DescribeEntity?catalog=AWSMarketplace&entityId=example1-abcd-1234-5ef6-7890abcdef12 HTTP/1.1

The following shows the response to DescribeEntity. 

{
  "EntityType": "ContainerProduct@1.0",
  "EntityIdentifier": "example1-abcd-1234-5ef6-7890abcdef12@9",
  "EntityArn": "arn:aws:aws-marketplace:[exampleARN]",
  "LastModifiedDate": "2021-03-02T20:19:14Z",
  "Details": "{\"Versions\":[{\"Id\":\"example2-0000-aaaa-5ef6-7890abcdef12\",\"ReleaseNotes\":\"My release notes\",\"UpgradeInstructions\":\"N/A\",\"VersionTitle\":\"1.0\",\"CreationDate\":\"2021-03-02T00:00:00.000Z\",\"Sources\":[{\"Type\":\"DockerImages\",\"Id\":\"example3-1111-bbbb-5ef6-7890abcdef12\",\"Images\":[\"709825985650.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1:some-tag\"],\"Compatibility\":{\"Platform\":\"Linux\"}}],\"DeliveryOptions\":[{\"Id\":\"example4-2222-cccc-2222-cccccccccccc\",\"Type\":\"ElasticContainerRegistry\",\"SourceId\":\"example3-1111-bbbb-5ef6-7890abcdef12\",\"Title\":\"New delivery option 1\",\"ShortDescription\":\"Delivery option 1\",\"isRecommended\":false,\"Compatibility\":{\"AWSServices\":[\"ECS\",\"EKS\"]},\"Instructions\":{\"Usage\":\"test\"},\"Recommendations\":{\"AdditionalArtifacts\":[]},\"Visibility\":\"Limited\"}]}],\"Description\":{\"Highlights\":[\"Some highlight\"],\"LongDescription\":\"Description of my product\",\"ProductCode\":\"123456789012abcdef1234567\",\"Manufacturer\":null,\"Visibility\":\"Limited\",\"AssociatedProducts\":null,\"Sku\":null,\"SearchKeywords\":[\"some keyword\"],\"ProductTitle\":\"Container Product 1\",\"ShortDescription\":\"Description of my product\",\"Categories\":[\"Operating Systems\"]},\"PromotionalResources\":{\"LogoUrl\":\"https://awsmp-logos.s3.amazonaws.com/PLACEHOLDER_Logo_for_Containers_products.png\",\"AdditionalResources\":[],\"Videos\":[]},\"SupportInformation\":{\"Description\":\"Description of support information.\",\"Resources\":[]},\"RegionAvailability\":{\"Regions\":[\"ap-south-1\",\"eu-west-3\",\"eu-north-1\",\"eu-west-2\",\"eu-west-1\",\"ap-northeast-2\",\"ap-northeast-1\",\"me-south-1\",\"ca-central-1\",\"sa-east-1\",\"ap-east-1\",\"ap-southeast-1\",\"ap-southeast-2\",\"eu-central-1\",\"us-east-1\",\"us-east-2\",\"us-west-1\",\"us-west-2\"],\"FutureRegionSupport\":null},\"Repositories\":[{\"Url\":\"709825985650.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1\",\"Type\":\"ECR\"}]}"
}

The Details attribute returned is a string that contains JSON. For more information about the Details attribute, see Working with the Details attribute. For this example, here is a copy of the Details with newlines added for readability. 

  "Details": "{
    \"Versions\": [
      {
        \"Id\": \"example2-0000-aaaa-5ef6-7890abcdef12\",
        \"ReleaseNotes\": \"My release notes\",
        \"UpgradeInstructions\": \"N/A\",
        \"VersionTitle\": \"1.0\",
        \"CreationDate\": \"2021-03-02T00:00:00.000Z\",
        \"Sources\": [
          {
            \"Type\": \"DockerImages\",
            \"Id\": \"example3-1111-bbbb-5ef6-7890abcdef12\",
            \"Images\": [
              \"709825985650.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1:some-tag\"
            ],
            \"Compatibility\": {
              \"Platform\": \"Linux\"
            }
          }
        ],
        \"DeliveryOptions\": [
          {
            \"Id\": \"example4-2222-cccc-2222-cccccccccccc\",
            \"Type\": \"ElasticContainerRegistry\",
            \"SourceId\": \"example3-1111-bbbb-5ef6-7890abcdef12\",
            \"Title\": \"New delivery option 1\",
            \"ShortDescription\": \"Delivery option 1\",
            \"isRecommended\": false,
            \"Compatibility\": {
              \"AWSServices\": [
                \"ECS\",
                \"EKS\"
              ]
            },
            \"Instructions\": {
              \"Usage\": \"test\"
            },
            \"Recommendations\": {
              \"AdditionalArtifacts\": []
            },
            \"Visibility\": \"Limited\"
          }
        ]
      }
    ],
    \"Description\": {
      \"Highlights\": [
        \"Some highlight\"
      ],
      \"LongDescription\": \"Description of my product\",
      \"ProductCode\": \"123456789012abcdef1234567\",
      \"Manufacturer\": null,
      \"Visibility\": \"Limited\",
      \"AssociatedProducts\": null,
      \"Sku\": null,
      \"SearchKeywords\": [
        \"some keyword\"
      ],
      \"ProductTitle\": \"Container Product 1\",
      \"ShortDescription\": \"Description of my product\",
      \"Categories\": [
        \"Operating Systems\"
      ]
    },
    \"PromotionalResources\": {
      \"LogoUrl\": \"https://awsmp-logos.s3.amazonaws.com/PLACEHOLDER_Logo_for_Containers_products.png\",
      \"AdditionalResources\": [],
      \"Videos\": []
    },
    \"SupportInformation\": {
      \"Description\": \"Description of support information.\",
      \"Resources\": []
    },
    \"RegionAvailability\": {
      \"Regions\": [
        \"ap-south-1\",
        \"eu-west-3\",
        \"eu-north-1\",
        \"eu-west-2\",
        \"eu-west-1\",
        \"ap-northeast-2\",
        \"ap-northeast-1\",
        \"me-south-1\",
        \"ca-central-1\",
        \"sa-east-1\",
        \"ap-east-1\",
        \"ap-southeast-1\",
        \"ap-southeast-2\",
        \"eu-central-1\",
        \"us-east-1\",
        \"us-east-2\",
        \"us-west-1\",
        \"us-west-2\"
      ],
      \"FutureRegionSupport\": null
    },
    \"Repositories\": [
      {
        \"Url\": \"709825985650.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1\",
        \"Type\": \"ECR\"
      }
    ]
  }"