Get promotion details

Learn how to retrieve comprehensive details for a specific promotion, including its configuration, benefit structure, item selection, validation issues, and customer segment targeting.

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.
• A promotionId obtained from the searchPromotions operation.

Step 1. Get the promotion details

Call the getPromotion operation with the promotionId of the promotion you want to retrieve. You can optionally include additional data using the following parameters:

• includedData: A comma-delimited list of additional datasets to include. Valid values are:
  • ISSUES: Include promotion-level validation issues and warnings. If you do not specify SELECTION along with ISSUES, item-level issues are not returned.
  • SELECTION: Include the selectionDetails field within the selection object, containing item-level information such as benefits, budgets, and item details. Without this parameter, only minimal selection metadata (selectionId, type, revisionId) is returned.
  • CUSTOMER_SEGMENTS: Include customer segment targeting information such as brand-tailored audiences or program-based audiences (for example, Prime Exclusive).
• locale: The locale for the response, formatted as an ISO 639 language code, followed by an underscore, followed by an ISO 3166-1 alpha-2 country code (for example, en_US). Defaults to en_US.

The response includes the full promotion configuration, which varies by promotion type:

• DEAL and PRICE_DISCOUNT: Benefits and budgets are configured at the item level within the selection.
• COUPON and BASKET_BUILDING: Benefits and budgets are configured at the promotion level. The response includes couponType to indicate the type of coupon.
• BASKET_BUILDING: Also includes purchaseRequirements (conditions customers must meet to qualify) and optional merchandising configuration.

When the published promotion differs from the latest revision, which occurs when an edit has revisionStatus of PROCESSING or FAILED, the response includes latestRevision.

Step 2. Review validation issues (optional)

If you specified ISSUES in includedData, check the issues array for any promotion-level validation issues. Each issue includes the following:

• code: The issue code identifier (for example, HAS_OVERLAPPING_PROMOTIONS).
• message: A description of the issue.
• severity: Either ERROR (must be resolved) or WARNING (should be reviewed).

If you also specified SELECTION in includedData, the selection.selectionDetails.issues array contains item-level issues with an additional identifier field indicating the affected ASIN or SKU.

📘

Note

To retrieve the complete set of item-level issues for promotions with many items, use the getSelection operation with pagination.