AWS Marketplace
Use APIs to manage multiple AWS Private Marketplaces for enterprise software subscriptions
During re:Invent 2020, AWS launched AWS Private Marketplace APIs to enable customers to programmatically manage their Private Marketplace. Private Marketplace, a feature of AWS Marketplace, enables administrators to create list of approved software products for their users to purchase from AWS Marketplace’s catalog. To provide administrators greater control to create distinct list of approved products for their various sets of users, such as team or business unit, we recently announced the launch of multiple Private Marketplace catalogs.
With this launch, administrators can now create multiple Private Marketplace catalogs within their AWS organization. Each Private Marketplace catalog is comprised of an experience and account groups. Private Marketplace experiences include the curated list of approved AWS Marketplace products as well as branding elements, including title, description, color and logo customizations. Each experience can be associated to one or multiple AWS accounts within the administrator’s organization, allowing granular control to govern purchases based on the account’s specific policies and business needs. For example, administrators can create a catalog of approved products for a set of production environment accounts and a different list of approved products for a set of development environment accounts.
Using the APIs enables administrators to connect to their existing ticketing and approval systems to simplify management of their multiple Private Marketplace catalogs. Customers can continue to use their existing systems for product approval, such as vetting a product form AWS Marketplace for the AWS environment.
In this post, Murphy and I will show you how to use APIs to programmatically build an enterprise-level procurement environment with AWS multiple Private Marketplace catalogs. We’ll use two AnyCompany business units in our example: Engineering and Finance departments.
Prerequisites
Before you begin, make sure you have access to the following:
- Primary AWS management account and member accounts
- AWS Identify and Access (IAM) role with Marketplace admin privileges to AWS management account and member accounts. You can leverage the managed policy AWSPrivateMarketplaceAdminFullAccess for this role.
- Postman installed and configured on your computer
Solution overview
A. Creating a Private Marketplace
- Creating a Private Marketplace experience (entity)
- Using the CreateExperience change type
- Finding the experienceID
- Creating a procurement policy
- Using the CreateProcurementPolicy change type
- Finding the ProcurementPolicyID
- Creating branding settings (optional)
- Creating additional Private Marketplaces
- Listing all experience entities
B. Updating Private Marketplace
- Enabling or disabling end user product request function
- Disabling product requests
- Enabling product requests
- Disabling your Private Marketplace
- Disabling your Private Marketplace
- Enabling your Private Marketplace
- Making your Private Marketplace live
- Switching to live mode
- Finding the status of your Private Marketplace
C. Managing your Private Marketplace
- Finding products
- Searching for products
- Selecting products to add
- Adding products
- Removing products
- Viewing approved and declined products
- Listing the procurement policy entities
- Viewing an entity’s approved and denied software
- Listing all available change sets
- Updating other Private Marketplaces
D. Working with multiple Private Marketplace experience entities
- Associating an audience
- Dissociating an audience
E. Working with multiple Private Marketplace entities in AWS Organizations
- Listing experience entities shared with a member account
- Listing the changes made to entities shared with a member account
Solution walkthrough: Use APIs to manage multiple AWS Private Marketplaces for enterprise software subscriptions
For the purposes of this blog post exercise, we use Postman to call the APIs. If you are not familiar with Postman, you can follow this guide here to make API calls. You can also refer to our blog post on AWS Private Marketplace API for specific configurations to make the calls.
A. Creating a Private Marketplace
The first step is to create a Private Marketplace for our AnyCompany organization. A Private Marketplace consists of three entities: Experience, ProcurementPolicy, and BrandingSettings. To create a Private Marketplace, you use these three required actions, called change types: CreateExperience, CreateProcurementPolicy, and UpdateExperience.
An optional change type is CreateBrandingSettings. If you have already been using Private Marketplace in your organization, you can skip to step B Updating your Private Marketplace settings.
1. Creating a Private Marketplace experience (entity)
- Using the CreateExperience change type: CreateExperience is the action that creates a Private Marketplace entity. You must use your AWS management account to create the initial experience for your organization. To create a Private Marketplace for the Engineering Department, send the following API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateExperience",
"Details": "{\"Name\": \"AnyCompany Engineering Department Private Marketplace\"}",
"Entity": {
"Type": "Experience@1.0"
}
}
],
"ChangeSetName": "Create EngDept Private Marketplace"
}
You should get a successful response similar to this one:
{
"ChangeSetId": "4eui3rj0js1wjtlfwcb1vXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/4eui3rj0js1wjtlfwcb1vXXXX"
}
Take note of the ChangeSetID above, as you need it to find out the experienceID, which is used to manage your Private Marketplace.
- Finding the experienceID: To find the experienceID, on the Postman console, send the following API request:
GET Request: https://catalog.marketplace.us-east-1.amazonaws.com/DescribeChangeSet?catalog=AWSMarketplace&changeSetId=4eui3rj0js1wjtlfwcb1vXXXX
A response similar to this one tells you the request is successful:
{
"ChangeSet": [
{
"ChangeType": "CreateExperience",
"Details": "{\"Name\": \" AnyCompany Engineering Department Private Marketplace\"}",
"Entity": {
"Identifier": "exp-asevc3uyvXXXX@1",
"Type": "Experience"
},
"ErrorDetailList": []
}
],
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/4eui3rj0js1wjtlfwcb1vXXXX",
"ChangeSetId": "4eui3rj0js1wjtlfwcb1vXXXX",
"ChangeSetName": "Create EngDept Private Marketplace ",
"EndTime": "2020-10-08T06:16:23Z",
"FailureCode": null,
"FailureDescription": null,
"StartTime": "2020-10-08T06:15:50Z",
"Status": "SUCCEEDED"
}
From that response, take note of the experience identifier experienceID. In the previous code, our experienceID is in between the quotation marks after “Identifier”.
2. Creating a procurement policy
- Using the CreateProcurementPolicy change type: By creating procurement policy, you can put controls around the products that your users can subscribe to within AWS Marketplace When a new Experience is created, it doesn’t have any procurement policy attached to it. It means all products in AWS Marketplace are visible and available to subscribe to in AWS Marketplace for end users. Using the experienceID from step A.1.2, you now create a procurement policy called AnyCompany Procurement Policy using CreateProcurementPolicy change type to allow and deny products in our Private Marketplace. To create a procurement policy on the Postman console, send the following API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateProcurementPolicy",
"Details": "{\"Name\": \"AnyCompany Engineering Department Procurement Policy\"}",
"Entity": {
"Identifier": "exp-asevc3uyvXXXX@1",
"Type": "Experience@1.0"
}
}
],
"ChangeSetName": "Create procurement policy"
}
The revisionID after the @ sign along with the EntityID distinguish one published revision from another. You can learn more about the revisionID in the AWS Documentation here.
A response similar to this one tells you the request is successful:
{
"ChangeSetId": "edp87qihz45sgixj0nz0xXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/ edp87qihz45sgixj0nz0xXXXX"
}
Once your procurement policy is created, you can go into your AWS Management Console and verify the newly created Private Marketplace’s existence.
- Finding the ProcurementPolicyID: The procurement policy is where you allow or deny products from AWS Marketplace. You should always make sure you are managing the intended procurement policy. To find the ProcurementPolicyID using the experienceID above, on the Postman console, send the following API request:
GET Request https://catalog.marketplace.us-east-1.amazonaws.com/DescribeEntity?catalog=AWSMarketplace&entityId=exp-asevc3uyvXXXX
A response similar to this one tells us the request is successful:
{
"Details": "{\"Name\":\"AnyCompany Engineering Department Private Marketplace \",\"Status\":\"Enabled\",\"ProcurementPolicies\":[\"procpolicy-skbxaj5xrXXXX\"],\"DiscoveryPolicies\":[],\"BrandingSettings\":[]}",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-asevc3uyvXXXX",
"EntityIdentifier": "exp-asevc3uyvXXXX@2",
"EntityType": "Experience@1.0",
"LastModifiedDate": "2020-10-08T06:55:58Z"
}
3. Creating branding settings (optional)
Private Marketplace comes with default branding, including a title, description, color scheme, and logo. We highly recommend creating a BrandingSettings entity for your Private Marketplace to help your end users know they are subscribing to products in AWS Marketplace approved for their use from the appropriate Private Marketplace. To create the branding settings, send the following CreateBrandingSettings API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body: This contains the following branding settings for our Private Marketplace: Title (name), Information (a description of the Private Marketplace), LogoURL, and ThemeColor. The following change type gives our Private Marketplace the name AnyCompany Engineering Department Private Marketplace, adds our corporate color of a dark blue, and adds our logo and its URL.
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateBrandingSettings",
"Details": "{ \"Name\": \"AnyCompany Engineering Department Private Marketplace\", \"Description\": \"Private Marketplace for Engineering Department Branding\", \"Configuration\": { \"Title\" : \"AnyCompany Engineering Department\", \"Information\" : \"Welcome to AnyCompany Private Marketplace for Engineer Department.\", \"ThemeColor\" : \"#232f3e\", \"LogoUrl\" : \"https:\/\/trademarks.amazon.com\/media\/images\/available_at_amzn_tile.original.png\" }}",
"Entity": {
"Type": "Experience@1.0",
"Identifier”: "exp-asevc3uyvXXXX@6"
}
}
],
"ChangeSetName": "Create branding EngDept"
}
A response similar to this one tells you the request is successful:
{
"ChangeSetId": "1lkk3l2j39qwb9us2ok6fXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/1lkk3l2j39qwb9us2ok6fXXXX"
}
4. Creating additional Private Marketplace(s)
You also must create a separate Private Marketplace for Finance Department, as their software requirements and restrictions are different from those of the Engineering Department. To do this, repeat step A.1-A.3. This time, provide different name for the new Private Marketplace called AnyCompany Finance Department Private Marketplace.
Here are the details of our Finance Department Private Marketplace:
{
"Details": "{\"Name\":\"AnyCompany Finace Department Private Marketplace\",\"Status\":\"Enabled\",\"ProcurementPolicies\":[\"procpolicy-wudeisyr7XXXX\"],\"DiscoveryPolicies\":[],\"BrandingSettings\":[]}",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-rmcnwk63xXXXX",
"EntityIdentifier": "exp-rmcnwk63xXXXX@3",
"EntityType": "Experience@1.0",
"LastModifiedDate": "2021-01-20T07:56:39Z"
}
5. Listing all experience entities
You must get an up-to-date list of Private Marketplace entities in your organization as you create and manage your enterprise environment. To list all the experience entities in the account, send the following API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/ListEntities
Body:
{
"Catalog": "AWSMarketplace",
"EntityType": "Experience"
}
A response similar to this one shows all your experience entities:{
"EntitySummaryList": [
{
"Name": "AnyCompany Test Private Marketplace",
"EntityType": "Experience",
"EntityId": "exp-stl4rokwnXXX",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-stl4rokwnXXX",
"LastModifiedDate": "2021-01-14T09:37:01Z"
},
{
"Name": "AnyCompany Engineering Department Private Marketplace",
"EntityType": "Experience",
"EntityId": "exp-asevc3uyvXXXX",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-asevc3uyvXXXX",
"LastModifiedDate": "2021-01-14T09:28:29Z"
},
{
"Name": "AnyCompany Finance Department Private Marketplace",
"EntityType": "Experience",
"EntityId": "exp-rmcnwk63xXXXX",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-rmcnwk63xXXXX",
"LastModifiedDate": "2021-01-07T18:32:04Z"
}
],
"NextToken": "
}
B. Updating your AWS Marketplace Private Marketplace
1. Enabling or disabling end user product request function
By default, your end users can look for products in the public AWS Marketplace and request a specific product to be added to the Private Marketplace. You can choose to deny or approve the request in your Private Marketplace administrator console.
- Disabling product requests: To disable product requests, send the following StartChangeSet with the UpdateProcurementPolicy change type API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateProcurementPolicy",
"Details": "{\"Configuration\”: {\"ResourceRequest\”: \"Deny\"}}",
"Entity": {
"Type": "Experience@1.0",
"Identifier”: "exp-asevc3uyvXXXX@3"
}
}
],
"ChangeSetName": "Disable product request function"
}
- Enabling product requests: To enable product requests, send the following StartChangeSet with the UpdateProcurementPolicy change type API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body: Disabling your Private Marketplace
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateProcurementPolicy",
"Details": "{\"Configuration\”: {\"ResourceRequest\”: \"Allow\"}}",
"Entity": {
"Type": "Experience@1.0",
"Identifier”: "exp-asevc3uyvXXXX@4"
}
}
],
"ChangeSetName": "Enable product request function"
}
A response similar to this one tells me our request is successful:
{
"ChangeSetId": "3bygr4jkw74nkedz65gjpXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/3bygr4jkw74nkedz65gjpXXXX"
}
2. Disabling your Private Marketplace
- Disabling your Private Marketplace: If you don’t want your end users to be governed by the set of approved products, you can disable our Private Marketplace. Once disabled, users will be able to procure all software publicly available in AWS Marketplace To disable your Private Marketplace, on the Postman console, send the following API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateExperience",
"Details": "{\"Status\": \"Disabled\"}",
"Entity": {
"Type": "Experience@1.0",
"Identifier": "exp-asevc3uyvXXXX@5"
}
}
],
"ChangeSetName": "Disable product request function"
}
A response similar to this one tells you your request is successful:
{
"ChangeSetId": "4pjt414rai05pitqywiifXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/4pjt414rai05pitqywiifXXXX"
}
Now your Private Marketplace is no longer live.
- Enabling your Private Marketplace: If you want your end users to be governed by the set of approved products again, just switch your Private Marketplace back to live mode by repeating step B.3.1. To find the current status of your Private Marketplace, repeat step A.4.2 with the ChangeSetID from the response in step B.3.1.
3. Making your experience live
- Switching to live mode: Your Private Marketplace is disabled by default. Before your end users can use Private Marketplace, you must switch it to live mode by using the UpdateExperience change type. We recommend you populate your Private Marketplace with the approved list of products before enabling your Private Marketplace. This enables your end users to subscribe to those approved products and request approval for any new products. To enable your Private Marketplace, on the Postman console, send the following API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateExperience",
"Details": "{\"Status\": \"Enabled\"}",
"Entity": {
"Type": "Experience@1.0",
"Identifier": "exp-asevc3uyvXXXX@2"
}
}
],
"ChangeSetName": ”Go live"
}
A response similar to this one tells you the request is successful:
{
"ChangeSetId": "byfcykqkiz4ul9ol31qjjXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/ byfcykqkiz4ul9ol31qjjXXXX"
}
Your Private Marketplace is now live.
- Finding the status of your Private Marketplace: To find the status of your Private Marketplace, on the Postman console, send the following DescribeEntity API request:
GET Request: https://catalog.marketplace.us-east-1.amazonaws.com/DescribeEntity?catalog=AWSMarketplace&entityId=exp-asevc3uyvXXXX
{
"Details": "{\"Name\":\"AnyCompany Engineer Department Private Marketplace \",\"Status\":\"Enabled\",\"ProcurementPolicies\":[\"procpolicy-skbxaj5xrXXXX\"],\"DiscoveryPolicies\":[],\"BrandingSettings\":[]}",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-asevc3uyvXXXX",
"EntityIdentifier": "exp-asevc3uyvXXXX@3",
"EntityType": "Experience@1.0",
"LastModifiedDate": "2020-10-08T06:55:58Z"
}
C. Managing your individual AWS Marketplace Private Marketplace
1. Finding products
- Searching for products: You can use AWS Marketplace Discovery API to search for specific software products in AWS Marketplace using your unique IntegrationID. If you’re not sure of your IntegrationID, contact AWS. For more information on IntegrationID, review the AWS Marketplace Discovery API documentation. Our Engineer department requires Splunk in their Private Marketplace. To search for that product, send the following API request on the Postman console with the product name Splunk as the value of SearchText:
POST Request: https://discovery.marketplace.us-east-1.amazonaws.com
Add the additional headers as part of the request:
| Key | Value |
| X-Amz-Target | com.amazonaws.marketplace.discovery.api.v20200320.AWSMPDiscoveryService.SearchListings |
| Content-Encoding | amz-1.0 |
Body:
{
"RequestContext":
{
"IntegrationId": "INTEGRATION-ID"
},
"SearchText": "Splunk",
"MaxResults": 1,
"Filters":
[
{
"Type": "FULFILLMENT_OPTION_TYPE",
"Values": ["AMAZON_MACHINE_IMAGE"]
}
]
}
A response similar to this one tells you your request is successful:
{
"ListingSummaries": [
{
"Badges": [
{
"DisplayName": "Bring Your Own License",
"Value": "BRING_YOUR_OWN_LICENSE"
},
{
"DisplayName": "Free Tier",
"Value": "FREE_TIER"
}
],
"Categories": [
{
(Truncated for visibility)
"ProductAttributes": {
"BaseProductId": "7b65de6c-5006-4ca2-bd75-fdba95ae5d9d",
"Creator": {
"DisplayName": "Splunk Inc.",
"Value": "6a766d61-5a6a-4c97-83f4-8bfe02b74914"
}
}, (truncated for visibility)
- Selecting products to add: You can select a product ID to add to your Private Marketplace entity. For example, to add Splunk AMI, use product ID 7b65de6c-5006-4ca2-bd75-fdba95ae5d9d from Splunk Inc. You also can repeat step C.1.1 to find the Harness product, a DevOps tool.
2. Adding a software product to Private Marketplace
To add the Splunk AMI from step C.1.1 as a product to our Engineering Department Private Marketplace, send the following API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "AllowProductProcurement",
"Details": "{\"Products\": [{\"Ids\": [\"7b65de6c-5006-4ca2-bd75-fdba95ae5d9d\"]}]}",
"Entity": {
"Identifier": "exp-asevc3uyvXXXX@7",
"Type": "Experience@1.0"
}
}
],
"ChangeSetName": "Adding product to procurement policy"
}
A response similar to this one tells you your request is successful:
{
"ChangeSetId": "7jn9g8ki1pauc2m6ikn0wXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/7jn9g8ki1pauc2m6ikn0wXXXX"
}
To add Harness DevOps SaaS to the Private Marketplace, repeat this step (C.2).
3. Removing a software product from your Private Marketplace
If you no longer want a product approved in your Private Marketplace, you can remove it. When a product is removed from a Private Marketplace, accounts with an active subscription can continue to use the product. New subscriptions cannot occur until the product is approved again in the Private Marketplace. To remove a product from Private Marketplace, send the following API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "DenyProductProcurement",
"Details": "{\"Products\": [{\"Ids\": [\"80ad187b-5f54-4327-9047-fb6fb36e7019\"]}]}",
"Entity": {
"Identifier": "exp-asevc3uyvXXXX@8",
"Type": "Experience@1.0"
}
}
],
"ChangeSetName": "Removing product from procurement policy"
}
A response similar to this one tells you your request is successful:
{
"ChangeSetId": "5sx9pf83zno3oj47iofouXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/5sx9pf83zno3oj47iofouXXXX"
}
4. Viewing approved and declined products in Private Marketplace
- Listing the procurement policy entities: To list all the procurement policy entities, send the following API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/ListEntities
Body:
{
"Catalog": "AWSMarketplace",
"EntityType": "ProcurementPolicy"
}
A response similar to this one tells you your request is successful:
{
"EntitySummaryList": [
{
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ProcurementPolicy/procpolicy-skbxaj5xrXXXX",
"EntityId": "procpolicy-skbxaj5xrXXXX",
"EntityType": "ProcurementPolicy",
"LastModifiedDate": "2020-10-12T07:22:09Z",
"Name": "Our Company's Procurement Policy",
"Visibility": null
}
],
"NextToken": "rO0ABXVyA="
}
- Viewing an entity’s approved and denied software: To look into what the procurement policy contains, including what software is approved or denied in your Private Marketplace, send the following API request on the Postman console:
GET Request: https://catalog.marketplace.us-east-1.amazonaws.com/DescribeEntity?catalog=AWSMarketplace&entityId=procpolicy-skbxaj5xrXXXX
The response gives you the corresponding Product IDs of the entity’s allowed and denied products.
{
"Details": "{\"Name\":\"AnyCompany Engineering Department Procurement Policy \",\"Statements\":[{\"Effect\":\"Allow\",\"Resources\":[{\"Type\":\"Product\",\"Ids\":[\"7b65de6c-5006-4ca2-bd75-fdba95ae5d9d \"]}]},{\"Effect\":\"Deny\",\"Resources\":[{\"Type\":\"Product\",\"Ids\":[\"80ad187b-5f54-4327-9047-fb6fb36e7019\"]}]}],\"Configuration\":{\"PolicyResourceRequests\":\"Allow\"}}",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ProcurementPolicy/procpolicy-skbxaj5xrXXXX",
"EntityIdentifier": "procpolicy-skbxaj5xrXXXX@6",
"EntityType": "ProcurementPolicy@1.0",
"LastModifiedDate": "2020-10-12T07:22:09Z"
}
5. Listing all available change sets
You can view the list of all the available change sets up to 60 days in your Private Marketplace. If you would like to have the option of viewing the full change set history, you can set up AWS Cloudtrail, as Catalog API publishes every single change set to Cloudtrail. To view the details about all the changes done to your Private Marketplace, send the following API request on the Postman console:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/ListChangeSets
Body:
{
"Catalog": "AWSMarketplace"
}
A response similar to this one tells you your request is successful:
{
"ChangeSetSummaryList": [
{
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/4pjt414rai05pitqywiifXXXX",
"ChangeSetId": "4pjt414rai05pitqywiifXXXX",
"ChangeSetName": "Removing product from procurement policy ",
"EndTime": "2020-10-12T07:23:09Z",
"EntityIdList": [
"exp-asevc3uyvXXXX"
],
"FailureCode": null,
"StartTime": "2020-10-12T07:22:01Z",
"Status": "SUCCEEDED"
},
[Truncated for visibility]
"NextToken": "AYADeN3N0=="
}
6. Updating other Private Marketplace(s)
In our example, we must also update the Private Marketplace for the Finance Department. They need to use SAP AMI, which has the product ID 0454efec-e5ad-4b7b-a23f-766e9e910dbc and Tableau Server BYOL, which has the product ID 2479a4be-2b34-43d9-94e3-2af5cccca819. To curate the Private Marketplace for Finance Department, repeat steps C1-5. After that, your Finance Department Private Marketplace is now active and curated.
D. Working with multiple Private Marketplace experience entities
You can now create multiple experience entities as shown in step A.5 and then follow steps B and C to manage additional Private Marketplace catalogs. You can then associate AWS accounts or groups of AWS accounts to the target experiences. Each experience has its own configurations, branding, and procurement policy with a list of approved or denied products. This capability enables organizations to provide tailored experience entities to meet specific business needs for the accounts.
Our examples of AnyCompany Engineering Department Private Marketplace and AnyCompany Finance Department Private Marketplace demonstrate this. Each department has a list of required and approved software. The Engineering Department must use Splunk and Harness, and the Finance Department must have access to SAP and Tableau.
The next step is to assign/associate the Private Marketplace experience to Principals, which are AWS accounts.
- Associating an audience: To associate an Engineering account to the AnyCompany Engineering Department Private Marketplace experience entity, send the following StartChangeSet with the AssociateAudience change type API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "AssociateAudience",
"Entity": {
"Type": "Experience@1.0",
"Identifier": "exp-asevc3uyvXXXX@3"
},
"Details": "{\"Name\": \"Private Marketplace audience\",\"Description\" : \"associate Engineering audience with Engineering Private Marketplace.\",\"Principals\":[\"AWS_Account_Number\"]}"
}
]
}
A response similar to this one tells you your request is successful:
{
"ChangeSetId": "3kiwj4u90gerw74nkedz65gjpXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/33kiwj4u90gerw74nkedz65gjpXXXX"
}
- Dissociating an audience: To remove an account, for example, an Engineering account, from the AnyCompany Engineering Department Private Marketplace experience entity, do the following.
On the Postman console, send the following StartChangeSet with the DisassociateAudience change type API request:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet
Body:
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "DisassociateAudience",
"Entity": {
"Type": "Experience@1.0",
"Identifier": "exp-asevc3uyvXXXX@4"
},
"Details": "{\"Name\": \"Private Marketplace audience\",\"Description\" : \"Disassociate Engineering audience with Engineering Private Marketplace\",\"Principals\":[\"AWS_Account_Number\"]}"
}
]
}
A response similar to this one tells you your request is successful:
{
"ChangeSetId": "4389jfu90gerw74nkedz65gjpXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/4389jfu90gerw74nkedz65gjpXXXX"
}
For more information on working with multiple Private Marketplaces, you can visit the AWS Marketplace Catalog API documentation.
E. Working with multiple AWS Marketplace Private Marketplace entities in AWS Organizations
When a Private Marketplace entity is created, all the changes on it are owned by the account that started the change set. Other accounts in AWS Organization can also access this entity and its change set via resource sharing that is implicitly set for all accounts, current or future, in the AWS Organization.
To show objects in the shared the experience entity from a member account, you must specify SharedWithMe filter with the ListEntities and ListChangeSets API calls.
- Listing experience entities shared with a member account: To list all the experience entities shared with the member account you are logged on to, on Postman console, send the following API call:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/ListEntities
Body:
{
"Catalog": "AWSMarketplace",
"EntityType": "Experience "
“FilterList":
[{
"Name": "Scope",
"ValueList":
["SharedWithMe"]
}]}
You will get a successful response like this with the entities belonging to your AWS Organization returned:
{
"EntitySummaryList": [
{
"Name": "AnyCompany Engineering Department Private Marketplace",
"EntityType": "Experience",
"EntityId": "exp-stl4rokwnXXX",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-stl4rokwnzm6s",
"LastModifiedDate": "2021-01-14T09:37:01Z"
}
],
"NextToken": "
}
You must use the primary payer account to create the first Private Marketplace experience entity. After that, you can manage the experience entity and create additional experiences from any account, provided that you have the right IAM role.
- Listing the changes made to entities shared with a member account: To list all the changes made to entities shared with the member account you are logged on to, do the following. On the Postman console, send the following API call with the FilterList value SharedWithMe:
POST Request: https://catalog.marketplace.us-east-1.amazonaws.com/ListChangeSets
Body:
{
"Catalog": "AWSMarketplace",
“FilterList":
[{
"Name": "Scope",
"ValueList":
["SharedWithMe"]
}]}
Conclusion
We showed you how to programmatically create and manage your multiple Private Marketplace entities for your organization using APIs. Using the example company AnyCompany and departments Engineering and Finance, we showed how to create a new Private Marketplace entity, procurement policy, branding settings, and additional Private Marketplaces.
We also showed you how to use APIs to update your Private Marketplaces, including enabling or disabling user product requests, disabling your Private Marketplace, and making your Private Marketplace live. We also showed how to use APIs to manage your Private Marketplace, including finding, adding, and removing products, and viewing your approved and declined products. Finally, we showed how to work with multiple Private Marketplace experience entities by associating and dissociating audiences and how to work with multiple Private Marketplace entities in AWS Organizations.
The API calls outlined in this post can help you integrate AWS Marketplace with your existing systems or simply streamline management using your preferred API or Command Line Interface (CLI) platform. Learn more about using AWS Marketplace APIs for Private Marketplace in the AWS Documentation.
About the authors
Nam Le, Senior Partner Solutions Architect, AWS Marketplace
Nam Le focuses on security and governance with close to 20 years of experience in consulting, sales, and engineering. He specializes in AWS Control Tower, AWS Service Catalog, AWS Marketplace, and AWS Data Exchange. As an AWS Marketplace solutions architect, he also works with AWS partners to build and deliver best-practices solutions to customers. Outside work, he enjoys biking, car building, travel photography, and spending time with family.
Murphy Tiggelaar, Product Manager, AWS Marketplace
Murphy Tiggelaar focuses on building and managing products and features that help customers purchase within AWS Marketplace. She loves building and launching products that enable customers to govern and customize their experience on AWS Marketplace. Murphy is located in Austin, Texas and enjoys traveling, cooking, and exploring all the great food, music, and nature Austin has to offer.