AWS Marketplace Catalog API

The AWS Marketplace Catalog API service provides an API interface for approved sellers to programmatically manage their products. This includes the self-service publishing capabilities on the AWS Marketplace Management Portal. If you'd like to be approved for this service, complete the Contact Us form on the AWS Marketplace Management Portal.

Catalog API actions allow you to 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.

After a change request is successfully completed, it might take a few hours for the change to be reflected on the buyer website.

Catalog API Entities

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

In order to simplify this paradigm, entities are designed with some level of commonality in their structures. In this way introducing a new business domain does not require you to learn a completely new structure from scratch.

General Structure

The general structure of any entity is:

• A named type

• An identifier

• A facet

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.

• 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. In order to identify the unique thing, we use an identifier associating an EntityId with a RevisionId, for example, prod-ad8EXAMPLE651@12345. In this example, the EntityId is prod-ad85a57547651 and the RevisionId is 12345. Every successful change request to the entity will update the revision.

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

• Each published revision of an Entity will have a revisionId. The revisionId along with the EntityId distinguish a published revision from one another.

• EntityIds and RevisionIds are generated by AWS Marketplace.

Facets

A facet is a logical grouping of attributes, an entity usually includes several facets which represent different aspects of the entity.

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

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

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

• Attribute name is self describing the expected content.

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 they will 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 an product type specific facet.

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

Supported AWS Regions

The AWS Marketplace Catalog API can be accessed from the US East (N. Virginia) AWS Region with the following endpoint:

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