Price Adjustment Automation Workflows Guide

This guide describes how to use the Product Pricing API and Pricing notifications to build best-in-class workflows that automate pricing management. Pricing automation helps selling partners compete more effectively by submitting price changes programmatically, and defining pricing rules.

API versions

This guide references operations in the following Selling Partner API sections. For more detailed information about the individual API operations listed, follow the referenced links.

To learn more about the terms that are used on this page, refer to Terminology.

Subscribe to pricing notifications

The workflows in this guide describe actions against pricing changes from competitors or Featured Offer disqualification. By subscribing to and monitoring the ANY_OFFER_CHANGED and PRICING_HEALTH notifications, you can build event-driven workflows that respond in real-time to these changes. To learn how to set up and create a destination and creating subscriptions, refer to Tutorial: Set up notifications (Amazon Simple Queue Service workflow).

Use PRICING_HEALTH to update the price against a featured offer disqualification event

The following diagram provides an overview of the workflow steps to update the price against a featured offer disqualification event.

Follow these steps to respond to a featured offer disqualification and update price in near real-time.

1. Subscribe the selling partner to the PRICING_HEALTH notification. Refer to Tutorial: Set up notifications (Amazon Simple Queue Service workflow) for more information.

2. If an offer is disqualified to be the Featured Offer, a PRICING_HEALTH notification is sent and posted to your SQS queue.

3. Poll the SQS Queue to retrieve the message. Observe in the payload that the issueType is BuyBoxDisqualification, which means the selling partner's offer is disqualified from being the Featured Offer.

4. Process the item affected by retrieving the ASIN information in the notification payload. The notification can provide different price points. You can create rules (which your sellers have the option to enroll in) to adjust the offer's LandedPrice (ListingPrice + Shipping - Points) so it matches or becomes lower than the competitive price, or is in line with the reference prices.

   📘

   Note: Reference prices

   The Pricing Health notification might include the Featured Offer price buyBoxPrices, competitivePriceThreshold from external competitors, 60-day averageSellingPrice, the highest 14-day (shipped and sold by Amazon) retailOfferPrice, and the listingPrice. For more information regarding reference prices, refer to referencePrice.

   To be Featured Offer eligible, you must provide great prices, availability, and delivery speed. The Featured Offer is the offer selected when the customer chooses Add to Cart on the product detail page.

5. Set the price for the item and update it locally. Use the enrolled rules to confirm the price change with the seller (for example, use competitivePriceThreshold if available in the notification.)

6. (Optional) Before submitting the price change, call the patchListingsItem operation with mode=VALIDATION_PREVIEW to preview pricing issues such as Featured Offer disqualification or pricing policy violations. For more information, refer to Preview errors before creating or fully updating a listing and Pricing validation issues.

7. Use JSON code to submit the offer with updated price attributes. Ensure that you adhere to the JSON Schema for the product type.

   📘

   Note: Validate your JSON schema

   Check that the listing data meets requirements prior to submission by using JSON Schema validation utilities. Refer to Amazon Product Type Definition Meta-Schema (v1) for details on validating data with the product type JSON Schemas. Ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met.

8. Call the patchListingsItem operation, to submit the price.

Request example

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123?marketplaceIds=ATVPDKIKX0DER&issueLocale=en_US

{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/purchasable_offer",
      "value": [
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 90.00
                }
              ]
            }
          ]
        }
      ]
    }
    ... (more attribute patches, if applicable)
  ]
}

9. Inspect the response to identify that the submission is ACCEPTED. If accepted, initial validations have passed and the price data is submitted for further processing with the Amazon catalog. If not accepted, one or more validation issues prevented acceptance; refer to Handling listings item issues for more information. Correct the validation issues and resubmit.

10. Check for new PRICING_HEALTH notifications in order to respond to any new item changes.

Use the ANY_OFFER_CHANGED notification to respond to price updates

The following diagram provides an overview of the workflow steps to update pricing against the top 20 competitors' offer changes.

1. Subscribe the selling partner to the ANY_OFFER_CHANGED notification. With this notification, you can use eventFilters to filter for an aggregate time of five or ten minutes, or a Marketplace Id.

2. The ANY_OFFER_CHANGED notification is sent and posted to your SQS queue when:

   • The seller's item receives a change to any of the top 20 offers, by condition (new or used)
   • The external price (the price from other retailers) changes for an item
   • There's a change to which offer wins the Featured Offer
   • There's a change to the Featured Offer price

3. Poll the SQS Queue to retrieve the message to receive the ANY_OFFER_CHANGED notification. To detect which type of change occurred, you must interpret the OfferChangeTrigger value in the notification body.

4. Process the item affected and identify if a price update is needed. To do this, retrieve the ASIN, confirm the item condition, and confirm the Fulfillment Type in order to reprice the correct item for your seller. To update the price, confirm that the seller wants to update it using automatic pricing rules (for example, decrease the item price until a certain percentage or monetary value threshold occurs).

5. Set the appropriate price for the item and update it locally. You can use the enrolled rules to confirm the price change with the seller.

6. (Optional) Before submitting the price change, call the patchListingsItem operation with mode=VALIDATION_PREVIEW to preview pricing issues such as Featured Offer disqualification or pricing policy violations. For more information, refer to Preview errors before creating or fully updating a listing and Pricing validation issues.

7. Use JSON code to submit the offer with updated price attributes. Ensure that you adhere to the JSON Schema for the product type.

   📘

   Note: Validate your JSON schema

   Check that the listing data meets requirements prior to submission by using JSON Schema validation utilities. For more information on how to validate data with the product type JSON Schemas, refer to Amazon Product Type Definition Meta-Schema (v1). Ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met.

8. Call the patchListingsItem operation to submit the price update for the item.

   Request example

   PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123?marketplaceIds=ATVPDKIKX0DER&issueLocale=en_US

   JSON

   {
   "productType": "PRODUCT",
   "patches": [
       {
       "op": "replace",
       "path": "/attributes/purchasable_offer",
       "value": [
           {
           "marketplace_id": "ATVPDKIKX0DER",
           "currency": "USD",
           "our_price": [
               {
               "schedule": [
                   {
                   "value_with_tax": 90.00
                   }
               ]
               }
           ]
           }
       ]
       }
       ... (more attribute patches, if applicable)
   ]
   }
   

9. Inspect the response to identify that the submission is ACCEPTED or INVALID. If accepted, initial validations have passed and the data is submitted for further processing with the Amazon catalog. If not accepted, one or more validation issues prevented acceptance; refer to Handling listings item issues for more information. Correct the validation issues and resubmit.

10. Check for new ANY_OFFER_CHANGED notifications in order to react to any new item changes.