Search for promotions

Learn how to search and filter promotions based on status, promotion type, ASINs, SKUs, date ranges, and more.

Prerequisites

To complete this tutorial, you must have:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
• The Pricing or Product Listing roles assigned to your developer profile.
• The Pricing or Product Listing role selected in the app registration page for your application.

Search for promotions

Call the searchPromotions operation to retrieve a list of promotion summaries that match your specified criteria. You must specify the marketplaceIds parameter, and may optionally filter by the following parameters:

• statuses: Filter by promotion status. Valid values are PROCESSING, UPCOMING, RUNNING, EXPIRED, FAILED, CANCELLING, and CANCELLED.
• promotionTypes: Filter by promotion type. Valid values are BASKET_BUILDING, DEAL, PRICE_DISCOUNT, and COUPON.
• asins: Filter by up to 10 ASINs to which the promotions apply.
• skus: Filter by up to 10 SKUs to which the promotions apply.
• startDateBefore / startDateAfter: Filter promotions by their start date range.
• endDateBefore / endDateAfter: Filter promotions by their end date range.
• revision: Specify which promotion revision to query against. Valid values are LATEST, PUBLISHED (default), and ANY.
• includedData: Include additional data in the response. Valid values are ISSUES and CUSTOMER_SEGMENTS.
• limit: Set the maximum number of results per page (1–100, default 20).
• updatedAfter: Filter for promotions updated after a certain time.
• updatedBefore: Filter for promotions updated before a certain time.

The response includes an array of promotion summaries with key details such as promotionId, promotionType, status, schedule, and selection metadata. The selection object in search results contains metadata (selectionId, type, revisionId) without item-level details. If the response contains multiple pages, use the nextToken included in the response to access the next page.