Price Adjustment Automation Workflows Guide

This guide outlines how to leverage the Product Pricing API and Pricing notifications to build best-in-class workflows that automate pricing management. Pricing automation helps selling partners be more competitive 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.

Terminology

• Featured offer: The featured offer (Buy Box offer) is an offer for a product that Amazon displays on the product detail page with an Add to Cart button. A customer can use the button to add the item to their shopping cart. When a seller's offer appears this way on a product page, it is the featured offer.

• Listings item: Represents an item in a selling partner catalog that is uniquely identified by a selling partner-provided SKU. It also represents the product facts and sales terms for an item sold on or fulfilled by Amazon.

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 react against 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 seller's offer is disqualified to be 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. Prepare the JSON file to submit the offer with updated price attributes that adhere to the JSON schema for the product type.

   To use the JSON schema validation utilities, check that the listing data meet requirements.

   📘

   Note: Check the JSON schema

   To use the JSON schema validation utilities, check that the listing data meet requirements. Refer to Amazon Product Type Definition Meta-Schema (v1) for details on validating data with the product type JSON Schemas. You must ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met.

7. To submit the price, call the patchListingsItem operation.

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)
  ]
}

8. 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.

9. Check for new PRICING_HEALTH notifications in order to react to any new item changes.

Use the ANY_OFFER_CHANGED notification to react 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. For more information refer to Processing Directives.

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. Use JSON code to submit the offer with updated price attributes. Make sure 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 update for the item.

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 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.