Enhanced search filtering in AWS Marketplace Catalog API

AWS Marketplace is a curated digital catalog for customers to discover, buy, deploy, and manage third-party software, data, and services to build solutions. The AWS Marketplace Catalog API lets sellers manage listings by creating and updating products, offers, and resale authorizations.

The previous versions of ListEntities action let sellers search by “entity ID” and “last modified date” fields. Without additional filters, sellers faced latency and performance challenges when retrieving entities. Sellers have requested additional filtering capabilities such as wild card search and range filters in API. AWS Marketplace launched the feature for an enhanced list and describe API experience.

In this post, we show you how to use the enhanced filtering and sorting capability provided by the ListEntities action in the AWS Marketplace Catalog API. The new filtering and sorting capability lets customers retrieve information with fewer API calls. Enhanced search results can then help elevate the user experience.

Prerequisites

To follow along with the samples in this post, you must complete the following prerequisites:

• Register as an AWS Marketplace seller.
• Submit one or more Amazon Machine Image (AMI), container, or software as a service (SaaS) products using AWS Marketplace Management Portal or API.
• Understanding of JSON and REST API.
• A REST client to test the API.

Solution overview

AWS Marketplace Catalog API provides the ListEntities action to retrieve a list of catalog entities for a given entity type. If the ListEntities action is successful, the response contains a list of catalog entities matching the input criteria of the entity type and search filter.

The ListEntities legacy filter limited the search and sorting to filtering by entity ID only.

"FilterList": [ { "Name": "string", "ValueList": [ "string" ] } ]

Both the ListEntities enhanced search filter and sort functionality support additional API attributes and product types.

"EntityTypeFilter" : {"EntityProductFilters" : {…}, "EntityTypeSort" : {…} }

The existing legacy filter and the new enhanced search filter are mutually exclusive. You cannot use both together in the same API request. Similarly, the existing sorting criteria and the enhanced sorting criteria are mutually exclusive. You cannot combine both filters in a single API request.

The following table contains the catalog entities supported for the enhanced search filter and sorting capability with AWS Marketplace Catalog API ListEntities action.

Solution walkthrough: Enhanced search filtering in AWS Marketplace Catalog API

In this solution walkthrough, we show you how to create a request payload with enhanced filtering and sorting for the ListEntities action. You then run the ListEntities action using a REST client and retrieve the results. The improved search filter now supports the legacy filtering on EntityId and LastModifiedDate fields. Here are examples that illustrate the use of an advanced search filter for new attributes.

A. Search catalog entities by product title

The ListEntities action helps you to search by product title using advanced filtering criteria. If the API action is successful, the response contains a list of catalog entities matching one or more specified product titles.

Applicable entity types: SaaS

1. Create a JSON document for ListEntities action for SaaS product.
2. Set the EntityTypeFilters for SaaS product in the request message to retrieve details of the catalog entities based on the product title.

{
   "Catalog": "AWSMarketplace",
   "EntityType": "SaaSProduct",
   "MaxResults": 25,
   "EntityTypeFilters" : {
       "SaaSProductFilters" : {
           "ProductTitle" : { 
               "ValueList" : [
                   "saas product 101", 
                   "SAAS APP Service", 
                   "SAAS DB Service"
               ]
           }
       }
   },
   "EntityTypeSort": {
       "SaaSProductSort": {
           "SortBy":"ProductTitle",
           "SortOrder":"ASCENDING"
       }
   }
}

3. Optionally, set the EntityTypeSort for SaaS product based on the product title. In this example, the results are sorted by product title in ascending order.

4. Run the ListEntities action with the request message mentioned earlier. If the API action is successful, the response contains a list of catalog entities matching the specified product titles. Results are sorted in ascending order based on the product title.

{
  "EntitySummaryList": [
    {
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/SaaSProduct/11111111-1111-1111-1111-111111111111",
      "EntityId": "11111111-1111-1111-1111-111111111111",
      "EntityType": "SaaSProduct",
      "LastModifiedDate": "2023-03-03T13:20:44Z",
      "Name": null,
      "SaaSProductSummary": {
        "ProductTitle": "SAAS APP Service",
        "Visibility": "Limited"
      },
      "TypeAttributes": null,
      "Visibility": null
    },
    {
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/SaaSProduct/22222222-2222-2222-2222-222222222222",
      "EntityId": "22222222-2222-2222-2222-222222222222",
      "EntityType": "SaaSProduct",
      "LastModifiedDate": "2023-03-02T12:31:28Z",
      "Name": null,
      "SaaSProductSummary": {
        "ProductTitle": "SAAS DB Service",
        "Visibility": "Limited"
      },
      "TypeAttributes": null,
      "Visibility": null
    }
  ],
  "NextToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEF"
} 

B. Search catalog entities by visibility

The ListEntities action allows for filtering results based on the visibility or state of the entity. The following example shows how to use the visibility field to filter the results for an offer.

Applicable entity types: SaaS, Offer, Data product

1. Create an input JSON document for ListEntities action for Offer entity type.

2. Set the EntityTypeFilters in the request message.

3. In this example, set the ValueList for Visibility field to “Private” and “Restricted”.

{
  "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
        "OfferFilters": {
             "Visibility": {
                "ValueList": [
                    "Private",
                    "Restricted"
                ]
            }
        }
    }
}

4. Run the ListEntities action with the preceding request message. If the API action is successful, the response contains a list of offers that have “Private” or “Restricted” visibility.

{
  "EntitySummaryList": [
    {
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/Offer/offer-4uu1111111111",
      "EntityId": "offer-4uu1111111111",
      "EntityType": "Offer",
      "LastModifiedDate": "2023-01-04T21:53:20Z",
      "Name": null,
      "OfferSummary": {
        "AvailabilityEndDate": null,
        "BuyerAccounts": null,
        "Name": null,
        "ProductId": "17783c49-34ea-9b94-111111111111",
        "ReleaseDate": null,
        "State": "Released",
        "Targeting": [
          "None"
        ]
      },
      "TypeAttributes": null,
      "Visibility": "Restricted"
    },

    {
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/Offer/offer-4yl2222222222",
      "EntityId": "offer-4yl2222222222",
      "EntityType": "Offer",
      "LastModifiedDate": "2023-03-07T00:11:49Z",
      "Name": null,
      "OfferSummary": {
        "AvailabilityEndDate": null,
        "BuyerAccounts": null,
        "Name": "Test Offer",
        "ProductId": "17783c49-34ea-4312-9b94-4yl2222222222",
        "ReleaseDate": null,
        "State": "Draft",
        "Targeting": [
          "None"
        ]
      },
      "TypeAttributes": null,
      "Visibility": "Private"
    }
  ],
  "NextToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEF=="
}

C. Search by wild card expression for resale authorization

The ListEntities action allows for a wild card search of the resale authorization entity type. Wild card search lets you specify a substring of the element to search, returning results that match the input substring. Each API request can only have one wildcard filter, and the wildcard search is case sensitive.

1. Create a JSON document for ListEntities action for ResaleAuthorization entity type.
2. Set the EntityTypeFilters with the value of “ResaleAuthorizationFilters.”
3. Set the value for Name field to search. In this example, I use wild card search for the Name field.

{
  "Catalog": "AWSMarketplace",
  "EntityType": "ResaleAuthorization",
  "EntityTypeFilters": {
        "ResaleAuthorizationFilters": {
            "Name" : {
                "WildCardValue" :"Opp"
            }
        }
    }
}

4. Run the ListEntities action with the preceding JSON request message. If the API action is successful, the response contains a list of resale authorizations, filtered based on the specified Name field with wild card search.

{
  "EntitySummaryList": [
    {
      "EntityArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ResaleAuthorization/sample-c259-12345-6789-d00c6ca6ded8",
      "EntityId": "sample-c259-12345-6789-d00c6ca6ded8",
      "EntityType": "ResaleAuthorization",
      "LastModifiedDate": "2023-10-12T22:34:40Z",
      "Name": null,
      "ResaleAuthorizationSummary": {
        "AvailabilityEndDate": "2023-12-31T23:59:59.000Z",
        "CreatedDate": "2023-10-12T22:34:30.000Z",
        "ManufacturerAccountId": "123456789012",
        "ManufacturerLegalName": "APN - Sandbox Test",
        "Name": "ResellerOpportunityA1",
        "OfferExtendedStatus": "Not Started",
        "ProductId": " c259-12345-6789-d00c6ca6ded8",
        "ProductName": "Test Ami Product",
        "ResellerAccountID": "123456789012",
        "ResellerLegalName": "ABC Test",
        "Status": "Active"
      },
      "TypeAttributes": null,
      "Visibility": null
    }
  ],
"NextToken": “sample12345bTGphdmEubGFuZy5PYmplY3Q7kM5YnxBzKWwCAAB4cAAAAAJ0ACQxOTIxNDU3YS1jMjU5LTNjYWItYWZlOS1kMDBjNmNhNmRlZDh0ACQxOTIxNDU3YS1jMjU5LTNjYWItYWZZZZZZZZZZZZRlZDg="
}

Note that the wild card search is a case-sensitive search.

You can also perform wild card searches for resale authorization entities on: ProductId, ManufacturerAccountId, ManufacturerLegalName, ResellerAccountID, and ResellerLegalName.

D. Search by wild card expression for offer

The ListEntities action allows a wild card search for the offer entity. Each API request can only have one wildcard filter, and the wildcard search is case sensitive.

1. Create an input JSON document for ListEntities action, specifying the enhanced search filter EntityTypeFilters for “Offer.”
2. Set the EntityTypeFilters field with the ValueList for offer BuyerAccounts. In this example, the wild card search is used for BuyerAccounts containing “111” as AWS account ID.

{
  "Catalog": "AWSMarketplace",
  "EntityType": "Offer",
  "EntityTypeFilters": {
        "OfferFilters": {
            "BuyerAccounts" : {
                "WildCardValue" :"111"
            }
        }
    }

}

3. Run the ListEntities action using REST client with the JSON request payload. If the API action is successful, the response contains a list of offers, filtered based on the wild card value specified in the BuyerAccounts field.

{
    "EntitySummaryList": null,
    "EntityTypeSummaries": {
        "OfferSummaries": [
            {
                "AvailabilityEndDate": "2023-12-31T23:59:59.999Z",
                "BuyerAccounts": [
                    "222222222222",
                    "111111111111"
                ],
                "EntityArn": "arn:aws:aws-marketplace:us-east-1:111111111111:AWSMarketplace/Offer/offer-sampley62vts",
                "EntityId": "offer-sampley62vts",
                "LastModifiedDate": "2023-09-27T23:30:44Z",
                "Name": null,
                "OfferStatus": "Released",
                "ProductId": "example1-9138-421a-8c45-98699ac46bfd",
                "ReleaseDate": "2023-09-27T23:30:39.696Z",
                "Visibility": "Private"
            },
            {
                "AvailabilityEndDate": "2023-06-30T23:59:59.000Z",
                "BuyerAccounts": [
                    "222222222222",
                    "111111111111"
                ],
                "EntityArn": "arn:aws:aws-marketplace:us-east-1:111111111111:AWSMarketplace/Offer/offer-samplegqiv6",
                "EntityId": "offer-samplegqiv6",
                "LastModifiedDate": "2023-06-05T21:41:57Z",
                "Name": null,
                "OfferStatus": "Released",
                "ProductId": "example2-9138-421a-8c45-98699ac46bfd",
                "ReleaseDate": "2023-06-05T21:41:57.550Z",
                "Visibility": "Private"
            }
    ]}
}

E. List my draft or public products

In this example, SaaS based products are retrieved that are in “Draft” or “Public” state. You may replace the EntityType and ProductFilters in the request payload with product type of your choice.

1. Create a JSON document for ListEntities action.

2. Set the EntityTypeFilters for SaaSProductFilters.

3. Set the Visibility field with ValueList of “Draft” or “Public”.

{
  "Catalog": "AWSMarketplace",
  "EntityType": "SaaSProduct",
  "EntityTypeFilters": {
        "SaaSProductFilters": {
             "Visibility": {
                "ValueList": [
                    "Draft",
                    "Public"
                ]
            }
        }
    }
}

4. Run the ListEntities action using REST client with the payload from the JSON request.

5. After successfully running the ListEntities action, the response contains a list of public or draft SaaS-based products.

F. List my draft, active, or expired offers

To list offers that are in “Draft”, “Active”, or “Expired” offers, use the following request filter.

1. Create a JSON document for ListEntities action for Offer entity type.

2. Set the EntityTypeFilters for OfferFilters.

3. Set the State ValueList field. In this example, the values are set to “Draft” and “Released.” The “Released” state covers active and expired offers.

{
    "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
     	 "OfferFilters": {
         	"State": {
                       	 "ValueList": ["Draft", "Released"]
                         }
      	     }
     }
}

4. Run the ListEntities action using REST client with the JSON request payload.

5. After successfully running the ListEntities action, the response contains a list of active, expired, or draft offers.

G. List my private, public, or geo-targeted offers

In this example, the Targeting field is used to retrieve private, public, or geo-targeted offers.

1. For private offers, create a JSON document for ListEntities action.

2. Set the EntityTypeFilters for “OfferFilters.”

3. Set the Targeting as “BuyerAccounts.”

{
  "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
     	"OfferFilters": {
        		    "Targeting": {
            			"ValueList": ["BuyerAccounts"]
         		     }
      	     }

    }
}

4. Run the ListEntities action using REST client with the JSON request message.

5. After successfully running the ListEntities action, the response contains a list of private offers.

For geo-targeted offers, use the following request search filter with “CountryCodes” for Targeting field.

{
   "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
     	    "OfferFilters": {
        		"Targeting": {
            			"ValueList": ["CountryCodes"]
         		}
      	     }

    }
 }

6. Run the ListEntities action using REST client with the JSON request message.

7. After successfully running the ListEntities action, the response contains a list of geo-targeted offers.

For commercial public offers, use the following search filter for Targeting field.

{
    "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
     	"OfferFilters": {
        	"Targeting": {
            		"ValueList": ["CountryCodes", “None”]
         	}
      	     }
       }
}

8. Run the ListEntities action using REST client with the JSON request message.

9. After successfully running the ListEntities action, the response contains a list of geo-targeted and commercial public offers.

H. List all my private offers expiring in the next 30 days

In this example, the offer AvailabilityEndDate is used to filter for private offers expiring in the next 30 days.

1. Create a JSON document for ListEntities action for Offer entity type.

2. Set the EntityTypeFilters for “OfferFilters.”

3. Set the Targeting field with value of “BuyerAccounts” to retrieve private offers.

4. Set the AvailabilityEndDate field with the date range of 30 days from current date.

{
    "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
       "OfferFilters": {
        	"AvailabilityEndDate": {
                  "DateRange": {
                         "BeforeValue": "2023-12-15T08:04:02Z",
                         "AfterValue": "2023-11-15T08:04:02Z"   
                   }
               }, 
        	"Targeting": {
           	     "ValueList": ["BuyerAccounts"]
        	}
                        }
                    }
}

5. Run the ListEntities action using REST client with the request message.

6. After successfully running the ListEntities action, the response contains a list of private offers expiring in next 30 days.

I. List and describe all Offers (and their prices) associated with a product

In this example, the offer ProductId field is used to filter for offers associated with a product.

1. Create a JSON document for ListEntities action.

2. Set the EntityTypeFilters for “OfferFilters.”

3. Set the ProductId ValueList field with set of associated products.

{
    "Catalog": "AWSMarketplace",
    "EntityType": "Offer",
    "EntityTypeFilters": {
        "OfferFilters": {
        	"ProductId": {
                  "ValueList":  ["test-product-4e47-9938-7843515ccabc"]
      	 }
        }
    }
}

4. Run the ListEntities action using REST client with the request payload.

5. After successfully running the ListEntities action, the response contains a list of all offers associated with a product.

6. For each of the offers obtained from the response, invoke the DescribeEntity action with entity ID set to offer ID value. The DescribeEntity action returns details of the offer and the associated prices.

J. List all Resale Authorizations created by a manufacturer

In this example, the offer ManufacturerLegalName field is used to filter for Resale Authorization created by a manufacturer.

1. Create a JSON document for ListEntities action for “ResaleAuthorization” entity type.

2. Set the EntityTypeFilters for “ResaleAuthorizationFilters.”

3. Set the ManufacturerLegalName field with name of the manufacturer. In this example, wild card search is used for the manufacturer name.

{
  "Catalog": "AWSMarketplace",
  "EntityType": "ResaleAuthorization",
  "EntityTypeFilters": {
        "ResaleAuthorizationFilters": {
            "ManufacturerLegalName" : {
                "WildCardValue" : "ManufactureName1"
            }
        }
    }
}

4. Run the ListEntities action using REST client with the request payload.

5. After successfully running the ListEntities action, the response contains a list of all resale authorizations matching the ManufacturerLegalName value.

K. List of resale authorizations with offer extended status

In this example, the offer OfferExtendedStatus field is used to filter for list of resale authorization. The OfferExtendedStatus can take value of: [Not Started, Completed-Used, Completed-Usable].

1. Create a JSON document for ListEntities action for resale authorization.

2. Set the EntityTypeFilters for “ResaleAuthorizationFilters.”

3. Set the OfferExtendedStatus field with ValueList of supported values. In this example, the “Not Started” value is set.

{
   "Catalog": "AWSMarketplace",
   "EntityType": "ResaleAuthorization",
   "EntityTypeFilters": {
        "ResaleAuthorizationFilters": {
            "OfferExtendedStatus" : {
                "ValueList" :["Not Started"]
            }
        }
    }
}

4. Run the ListEntities action using REST client with the request payload.

5. After successfully running the ListEntities action, the response contains a list of resale authorizations matching the OfferExtendedStatus.

Conclusion

In this blog post, we showed you how to use the enhanced search filter and sort capability in ListEntities action. Apply this improved filtering and sorting solution to generate tailored search results in your custom application.

About the authors

	Chandrashekar Vishweshwara is a Specialist Solutions Architect with AWS Marketplace. In this role, Chandrashekar helps sellers onboard products in AWS Marketplace. Outside of work, he spends time with his family and puppy, goes out for walks, or watches movies.
	Ann Lu is a Senior Partner Solutions Architect at AWS, helping partners and energy customers build innovative solutions on AWS. Before joining AWS, Ann worked with Fluence Energy and Engie North America where she lead technology teams developing and operating applications for power and renewable energy.