Working with a private marketplace - AWS Marketplace Catalog API

Working with a private marketplace

You can use the AWS Marketplace Catalog API to manage a private marketplace for your AWS account or organization.

For more information about private marketplaces, see Private marketplaces in the AWS Marketplace Buyer Guide.

The following topics describe how to use the Catalog API to perform actions on your private marketplace.

Creating a private marketplace

A private marketplace for an AWS account can be thought of as a list of products that users are allowed to procure in that account, and branding for the marketplace. In an organization with multiple accounts, the accounts can be grouped together and share experiences. For example, you could have one set of products that all accounts in the organization are allowed to procure, or you could have a different list of products for each account in the organization. Each list of approved products and branding is called a procurement experience. In the AWS Marketplace Catalog API, four entities represent an experience. At the highest level is an Experience entity, which contains two child entities. A ProcurementPolicy represents the products that have been allowed and denied in your private marketplace. You can also create a BrandingSettings entity to define how your private marketplace looks to your users. You must also associate one or more Audience entities, which define the set of AWS accounts that the experience applies to.

The steps to create a procurement experience are as follows:

  1. Create the Experience entity.

  2. Create a ProcurementPolicy entity to store the list of products that are allowed or denied for the experience.

  3. (Optional) Create a BrandingSettings entity to customize the look of your marketplace experience.

  4. Associate accounts with your experience. For single AWS accounts, this is just the one account.

  5. Enable the experience.

Note

If your account is part of an organization in AWS Organizations, see Working with private marketplaces for AWS Organizations.

Create the Experience entity

To create the Experience entity, use the StartChangeSet action with the CreateExperience value for the ChangeType parameter to request that the experience be created by AWS Marketplace. See the following code example.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "CreateExperience", "Details": "{\"Name\": \"ExamplePrivateMarketplace\"}", "Entity": { "Type": "Experience@1.0" } } ], "ChangeSetName": "Create Private Marketplace Example" }

In this action, Entity is a template for the entity that you want to create. It is assigned an EntityId when it is created. ChangeSetName identifies the change to help you find it later.

The response looks like the following.

{ "ChangeSetArn": "arn:...:AWSMarketplace/ChangeSet/abcd1234example5678frjzkz", "ChangeSetId": "abcd1234example5678frjzkz" }

The response includes a ChangeSetId that you can use to get the status of your change request as it is processed with DescribeChangeSet. You can also use ListEntities to find your Experience entity without the ChangeSetId. For more information about change sets, see Working with change sets.

A newly created Experience entity doesn't have a procurement policy by default. It is also created with default settings for branding. For more information about branding settings, including how to customize them, see Changing the branding of a private marketplace experience.

Create a ProcurementPolicy entity

You must create a ProcurementPolicy entity. By default, a new Experience entity is disabled, so you can create the procurement policy before enabling it.

Note

An Experience entity with no procurement policy (null) allows all products to be procured in your private marketplace. An Experience entity with an empty procurement policy has no products available to users to procure.

To allow and deny products in your private marketplace, you must create the procurement policy. To do this, you again call StartChangeSet, but this time with the ChangeType of CreateProcurementPolicy. The following code example creates an empty procurement policy.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "CreateProcurementPolicy", "Details": "{\"Name\": \"ExampleProcurementPolicy\"}", "Entity": { "Type": "Experience@1.0", "Identifier" : "exp-1234example@1" } } ] }

The Entity you provide in this action is the Experience entity that you want the procurement policy created within, so you must include the identifier for the entity that you created earlier. Use ListEntities to find the Experience entity. You can also return the identifier by using DescribeChangeSet with the change set identifier from the CreateExperience action

Note

This example shows the identifier with a revision of 1. For more information about revisions for identifiers, see Identifier.

You can again use DescribeChangeSet on the CreateProcurementPolicy change to follow the processing of your request.

Note

The names you give the Experience and ProcurementPolicy objects do not appear in AWS Marketplace. The names are only for your ease of finding the entities in the API.

After you have created the procurement policy, your private marketplace displays in the AWS Management Console. (You can go to the private marketplace page to see it.) After you have completed these steps, your private marketplace will be disabled, have default branding, have an empty procurement policy, and will not be associated with any accounts in your organization. You can update the branding and add any products that you want in it, associate the experience with one or more accounts, and then enable your private marketplace.

The following sections describing managing your private marketplace with the AWS Marketplace Catalog API.

Changing the branding of a private marketplace experience

You can customize the look of your private marketplace for your users. Without customization, your private marketplace will have the default branding settings, which are described below. Aspects of branding that you can change in a private marketplace include the following:

  • Title – The name displayed for your private marketplace. This is the same as the Name field in the private marketplace Profile settings screen. If you set the Title to Example, then the text displayed is Example Private Marketplace. The default is Private Marketplace.

  • Information – The paragraph displayed under the name in your private marketplace. This is the same as the Description field in Profile settings. The default is no information, in which case a general description of private marketplaces is displayed.

  • ThemeColor – The color displayed in the banner of your private marketplace. This is a color in RGB hexadecimal format. This value is the same as the Theme color field in Profile settings. The default value is #232F3E.

  • LogoUrl – The URL that points to an image file to be used as the logo on your private marketplace. The URL must be publicly available (for example, a signed Amazon S3 URL). The file must be either a .png or .svg file and be under 500kb. If necessary, the image file will be resized to a maximum height of 30 pixels and a maximum width of 100 pixels. This is the same value as the Logo Select in Profile Settings. The default is to not show a logo.

To set these values, you must first create a BrandingSettings entity with the CreateBrandingSettings change type. You can then request an UpdateBrandingSettings change to set or change the branding. You only need to create a BrandingSettings object once. To create this object, call StartChangeSet with the CreateBrandingSettings change type, as shown in the following code example.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "CreateBrandingSettings", "Details": "{ \"Name\": \"ExampleBrandingSettingsName\"}", "Entity": { "Type": "Experience@1.0", "Identifier" : "exp-1234example@2" } } ] }

This examples modifies the Experience entity by adding the BrandingSettings object to it. The revision of the entity identifier has incremented to 2. For more information about revisions for identifiers, see Identifier.

Note

You can specify all the details of the branding settings in the call to create the branding settings entity. The details facet is the same for CreateBrandingSettings and UpdateBrandingSettings.

You modify the settings by calling StartChangeSet with the UpdateBrandingSettings change type. The settings are part of the Configuration of the Details object.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "UpdateBrandingSettings", "Details": "{ \"Name\": \"ExampleBrandingSettingsName\", \"Description\": \"Example description\", \"Configuration\": { \"Title\": \"ExampleName\", \"Information\": \"Example description.\", \"ThemeColor\" : \"#0e7f74\", \"LogoUrl\" : \"https://example.com/path/mylogo.png\" } }", "Entity": { "Type": "Experience@1.0", "Identifier" : "exp-1234example@3" } } ] }
Note

This example has line wraps added for readability and will not work as-is. The Details attribute is a string, and it should be converted from a JSON object to a string in your call to StartChangeSet. In this case, the string would be "{\"Name\": \"ExampleBrandingSettingsName\",\"Description\": \"Example description\",\"Configuration\": {\"Title\": \"ExampleName\",\"Information\": \"Example description.\",\"ThemeColor\" : \"#0e7f74\",\"LogoUrl\" : \"https://example.com/path/mylogo.png\"}}". For more information, see Working with the Details attribute.

Note

The URL for the logo is used to make a copy during the update change. After the change is complete, if you remove or change the URL at that path, it will not affect your private marketplace unless you again request UpdateBrandingSettings.

Enabling or disabling a private marketplace experience

When a private marketplace is enabled (and has a procurement policy), users in associated accounts can only purchase products that you have approved. When no private marketplace experience is enabled for an account, users can purchase products across the full AWS Marketplace catalog.

To enable a private marketplace, use the StartChangeRequest action with the UpdateExperience change type.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "UpdateExperience", "Details": "{\"Status\": \"Enabled\"}", "Entity": { "Type": "Experience@1.0", "Identifier": "exp-1234example@4" } } ] }

Similarly, you can use the same action and ChangeType, but change the Status in Details to Disabled to disable a private marketplace.

Note

Disabling a private marketplace keeps your list of both allowed and denied products, as well as customizations, such as branding. When a private marketplace is disabled, users no longer see the private marketplace (although they may still be governed by the management account experience). If there are no private marketplace experiences enabled for an account, then all restrictions are removed, and users are able to procure any products in the public AWS Marketplace.

Enabling or disabling user requests

Users in your organization can view the full public AWS Marketplace, but they can only subscribe to the products that you have allowed. By default, they can request that a product that is not in the private marketplace be added to it. These requests show up in the private marketplace administrator page ( https://aws.amazon.com/marketplace/privatemarketplace/admin/), where you can decide whether to accept or deny the request (and whether to block further requests for the same product). You cannot see or respond to the requests by using the Catalog API.

You can enable or disable the ability for users to create requests for your private marketplace experience. Use StartChangeSet with the UpdateProcurementPolicy change type. The ability to make requests is disabled in the following code example.

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

To enable the change request capability for users, use Allow instead of Deny in PolicyResourceRequests.

To learn how to get the current status of this setting, see the next section, Getting a list of products in a private marketplace experience.

Getting a list of products in a private marketplace experience

The products allowed (and denied) in a private marketplace are part of the procurement policy in the Experience entity. To get the details about the procurement policies in a private marketplace, you first get the procurement policy identifier from the Experience entity, and then call DescribeEntity with that identifier.

To get the procurement policy identifier, use DescribeEntity on the Experience entity that you are interested in, as shown in the following command.

GET /DescribeEntity?catalog=AWSMarketplace&entityId=exp-example01

Following is an example response (new lines added for readability).

{ "Details": "{\"Name\":\"New Private Marketplace\", \"Status\":\"Enabled\", \"ProcurementPolicies\":[\"procpolicy-123example456\"], \"BrandingSettings\":[\"brandsettings-456example123\"]}", "EntityArn": "arn:<...>:AWSMarketplace/Experience/exp-example-01", "EntityIdentifier": "exp-example01@6", "EntityType": "Experience@1.0", "LastModifiedDate": "2021-01-13T20:31:36Z" }

You can use the returned EntityId for the procurement policy to get the details, as shown in the following command.

GET /DescribeEntity?catalog=AWSMarketplace&entityId=procpolicy-123example456

This returns the full details of the policy, including both allowed and denied products. Following is an example response (new lines added for readability).

{ "Details": "{\"Name\":\"ExampleProcurementPolicy\", \"Statements\":[ {\"Effect\":\"Allow\",\"Resources\":[ {\"Type\":\"Product\",\"Ids\":[\"example1-1234-abcd-5678-90abcdef1234\"]}, {\"Type\":\"Product\",\"Ids\":[\"example2-2345-bcde-6789-01bcdea2345\"]}]}, {\"Effect\":\"Deny\",\"Resources\":[ {\"Type\":\"Product\",\"Ids\":[\"example3-3456-cdef-7890-12defabc5678\"]}]}], \"Configuration\":{\"PolicyResourceRequests\":\"Allow\"}}", "EntityArn": "arn:<...>AWSMarketplace/ProcurementPolicy/procpolicy-123example456", "EntityIdentifier": "procpolicy-123example456@4", "EntityType": "ProcurementPolicy@1.0", "LastModifiedDate": "2020-10-01T12:00:00Z" }

In this sample, the procurement policy has two allowed products and one denied product. The policy allows user resource requests.

Adding or removing products from a private marketplace

By default, a private marketplace does not have any approved products in it. Use change requests to add or remove a product. To add a product, use the AllowProductProcurement change type. To remove a product, use the DenyProductProcurement change type.

The following code example shows the AllowProductProcurement change type with the StartChangeSet action to add a product to a private marketplace.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "AllowProductProcurement", "Details": "{\"Products\":[{\"Ids\":[\"example-1234-abcd-5678-90abcded1234\"],\"Notes\":\"Useful product\"}]}", "Entity": { "Identifier": "exp-1234example@6", "Type": "Experience@1.0" } } ] }

You add the product to the Experience entity for a private marketplace by using AllowProductProcurement. The syntax to remove a product from a private marketplace is identical, with the exception that you use the DenyProductProcurement ChangeType instead of AllowProductProcurement. The products are added to the allow (or deny) list of the ProcurementPolicy entity that is contained by your Experience entity.

Note

The list of products in the Details of your change is an array of Ids, so you can add (or remove) multiple products with one call by including a list of product identifiers. The limit is 50 products in a single request.

The Notes field for the list of Ids is not required. However, you can use it to record why a decision to allow or deny a set of products was made.

Finding products

By getting the details of your procurement policy, you can find the product IDs for the products that are already in a private marketplace. However, the AWS Marketplace Catalog API does not provide a way to find the product IDs for other products. There are two ways to get product IDs to use with the Catalog API service:

  • Public marketplace – After you find a product in the public marketplace, choose Continue to Subscribe to see a details page about the product (it will not subscribe you to the product). The URL will include the product ID as a parameter. For example, in the URL https://aws.amazon.com/marketplace/fulfillment?productId=ab1234cd-1234-abcd-5678-90abcdef1234&ref_=dtl_psb_continue, ab1234cd-1234-abcd-5678-90abcdef1234 is the product ID.

  • AWS Marketplace Discovery API – Programmatically, you can access the full list of products in the AWS Marketplace by using the Discovery API. The Discovery API is a private API. You must request access to be able to use it. For more information, see Getting access to the Discovery API.

Working with private marketplaces for AWS Organizations

Whether you are working with a private marketplace for your account or your organization, you use the same API. However, there are differences when working within your organization:

  • You must create the first Experience of your private marketplace from within the management account. This creates the Experience entity and enables the private marketplace feature for your organization.

  • After the first Experience is created, it is automatically shared, allowing you to edit and update it from any account in the organization, as long as you have the correct permissions. You can also create additional Experience entities from any account.

  • When listing objects in a private marketplace from another account (that has been automatically shared across the organization), you must specifically request them with the SharedWithMe filter. This applies to both ListEntities and ListChangeSets actions.

For example, when you call ListEntities from an account that isn't the management account, it only returns entities created by or owned by that account, by default. To list Experience objects in your own account, call ListEntities as shown in the following code example.

POST /ListEntities HTTP/1.1 Content-Type: application/json { "Catalog":"AWSMarketplace", "EntityType":"Experience" }

However, to list the entities that have been shared with you, you must add a FilterList with a Scope of SharedWithMe, as shown in the following code example. As a result, AWS Marketplace searches outside of your own account to find entities that are shared with you.

POST /ListEntities HTTP/1.1 Content-Type: application/json {"Catalog":"AWSMarketplace", "EntityType":"Experience", "FilterList": [{ "Name": "Scope", "ValueList": ["SharedWithMe"] }]}

In this case, only entities outside of your account (the ones for your organization) are returned.

Similarly, to call ListChangeSets, you must set the scope, as shown in the following code example.

POST /ListChangeSets HTTP/1.1 Content-Type: application/json {"Catalog":"AWSMarketplace", "FilterList": [{ "Name": "Scope", "ValueList": ["SharedWithMe"] }]}

This returns change sets that apply to a shared private marketplace for your organization.

Associating accounts to experiences

A private marketplace experience must have one or more accounts associated with it in order to have any effects in your organization. For a single AWS account, you must associate the account with the experience to use the private marketplace. In an organization, you can have multiple experiences apply to different accounts.

Note

The experience that is associated with the management account is the default for all other accounts in the organization. Associating a linked account with a different experience directly sets a different experience for that account.

To associate an account to an experience use the AssociateAudience change type with the StartChangeSet action, as shown in the following code example.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet" : [ { "Entity": { "Type": "Experience@1.0", "Identifier": "exp-example01@1" }, "ChangeType": "AssociateAudience", "Details": "{\"Name\": \"AudienceName\",\"Description\" : \"Audience example.\",\"Principals\" : [\"012345678901\"]}" } ], "ChangeSetName": "Set Audience for experience 01" }

The audience is the list of principals that are associated with the Experience. A principal is an AWS account, defined by its ID. Principals is a list, so you can include multiple accounts to be associated with the experience. After the first call, subsequent calls to the AssociateAudience change type will add principals to the association for the experience.

You can also remove accounts from an experience. Use the DisassociateAudience change type to do this, as shown in the following code example.

POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet" : [ { "Entity": { "Type": "Experience@1.0", "Identifier": "exp-example01@02" }, "ChangeType": "DisassociateAudience", "Details": "{\"Principals\" : [\"012345678901\"]}" } ], "ChangeSetName": "Disassociate audience example" }
Note

An account can only be directly associated with one experience. To move an account from being directly associated with one experience to another experience, you must disassociate it from the initial experience, then associate it with the second.

Errors in the private marketplace API

The following errors are specific to the private marketplace actions in the AWS Marketplace Catalog API.

Change type Error code Error message Description
Errors returned directly by the StartChangeSet action

All

422

Document not valid JSON format

Invalid JSON input used, check your syntax.

AllowProductProcurement, DenyProductProcurement

422

Values in Ids array must be unique

You can't include the same product multiple times in a single change request.

AllowProductProcurement, DenyProductProcurement

422

Cumulative number of values in Ids array must be less than or equal to 50

You can allow or deny up to 50 products in a single change request.
Errors found by calling the DescribeChangeSet action

CreateBrandingSettings, UpdateBrandingSettings

INVALID_URL

Image could not be fetched from the input URL

You must specify a valid, reachable URL for the logo field in BrandingSettings.

CreateBrandingSettings, UpdateBrandingSettings

INVALID_IMAGE

Image verification for type, content, or file size failed. Only .png and .svg file types with sizes less than or equal to 500KB are supported.

Your image file must match the logo requirements for branding settings.

AllowProductProcurement, DenyProductProcurement

ENTITY_NOT_FOUND

Procurement policy missing from Experience

You must create a ProcurementPolicy before allowing or denying products.

CreateProcurementPolicy

ENTITY_ALREADY_EXISTS

Procurement policy exists for Experience

You can only have a single procurement policy for a private marketplace.

UpdateProcurementPolicy

ENTITY_NOT_FOUND

Procurement policy missing from Experience

You must create a ProcurementPolicy before updating the procurement policy.

CreateBrandingSettings

ENTITY_ALREADY_EXISTS

Branding settings exists for Experience

You can only have a single branding settings for a private marketplace.

UpdateBrandingSettings

ENTITY_NOT_FOUND

Branding settings missing from Experience

You must create a BrandingSettings entity before updating the branding settings.

AssociateAudience

CALLER_NOT_AUTHORIZED

Caller not authorized to execute the action

You must have permissions to call the action. The accounts being added must be in the same organization.

CreateExperience

CALLER_NOT_AUTHORIZED

Caller not authorized to create experience. Initial experience must be created from management account, if AWS Orgs is enabled.

You must have permissions to create an experience, and the initial experience for an organization must be created in the management account.

AssociateAudience

ENTITY_ALREADY_EXISTS

An experience is already associated with the account {accountId}. Disassociate previous experience before updating

You can only associate a single experience with an account. Disassociate the current experience before associating a new one.

AssociateAudience, DisassociateAudience

ENTITY_IN_USE

There is already a conflicting changing in progress for the selected account(s). Try again later

You can't change the association with an account while another change request to change the association is already in progress.