HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Product Pricing API v2022-05-01 Use Case Guide

How to use the Product Pricing API.

API Version: 2022-05-01

What is the Product Pricing API?

The Product Pricing API is designed to help you develop automated solutions that sellers can use to update and manage their prices. Building in automation for your sellers allows them to react faster to keep their prices competitive and attractive to customers.

Tip

The Product Pricing API supports the development of repricers. Repricers are automated pricing tools that can continuously monitor price points, competitor prices, and other relevant factors in order to adjust a seller's prices in real-time. Repricers use data and insights from Product Pricing and Notifications APIs to help sellers maintain a competitive price advantage.

Key features

  • Retrieve featured offer expected price (FOEP) response data: The getFeaturedOfferExpectedPriceBatch operation retrieves FOEP data for up to 40 SKUs, provided that the items are in new condition, ship nationwide, and are eligible to become the featured offer.
  • Retrieve all featured offers for an ASIN: The getCompetitiveSummary API returns every offer that is being featured to Amazon customers, along with the glance view weight percentage for each offer.

Terminology

  • Featured offer: The featured offer is an offer for a product that Amazon displays on the product detail page with an Add to cart button. When a customer selects this button, the item is added directly into their shopping cart.

  • FOEP: A computed listing price at or below which a seller can expect to become the featured offer (before applicable promotions).

  • Competing featured offer: An offer that can become featured if the target offer is more expensive than the FOEP.

  • Current featured offer: An offer that is selected as the featured offer.

Tutorial: Return a batch of FOEP data for a set of SKUs

Learn how to return a set of responses for up to 40 requests for featured offer extended price data.

To help a seller compete for featured offer placement on the product detail page (for items listed in new condition that ship nationwide), use the getFeaturedOfferExpectedPriceBatch. To compete for selection as the featured offer, the seller and their listed items must be eligible.

You can help the seller compete by returning the FOEP for a SKU. Because competing offers can change, featured offer status isn't guaranteed. Different offers can be featured based on other factors, including fulfillment capabilities to a specific customer. The getFeaturedOfferExpectedPriceBatch operation returns batch responses that contain up to 40 FOEP requests. If there are no other competing offers that ship nationwide, Amazon might not return an FOEP value.

Warning

FOEP values are automatically generated, so be sure to carefully verify the calculated values. All sellers using the API are responsible, as the retailer of record for their offers, for setting their prices independently and in compliance with applicable laws and pricing regulations.

The getFeaturedOfferExpectedPriceBatch operation is available in all marketplaces. For more information about Product Pricing API operations, associated data types, and schemas, refer to the Product Pricing v2022-05-01 API Reference.

Prerequisites

To complete this tutorial, you must have:

  • Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
  • The Pricing role assigned to your developer profile.
  • The Pricing role selected on the app registration page for your application.

Step 1: Get the FOEP data for a set of SKUs

The getFeaturedOfferExpectedPriceBatch operation is a batch API. The batch request must use an HTTP POST method with a body parameter that contains a list or set of individual requests. The response is a batch response that contains the list of individual HTTP responses, where each response maps to one of the original requested SKUs in the batch.

To return FOEP data, call the getFeaturedOfferExpectedPriceBatch operation and pass the following parameters:

Request parameters

Body parameter

ParameterDescriptionRequired
requestsA batched list of featured offer expected price requests.
Type : < FeaturedOfferExpectedPriceRequest > array
Yes

Request example

POST https://sellingpartnerapi-eu.amazon.com/batches/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice
{
  "requests": [
    {
      "marketplaceId": "A1PA6795UKMFR9",
      "sku": "MY_SKU",
      "method": "GET",
      "uri": "/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice"
    },
    {
      "marketplaceId": "A1PA6795UKMFR9",
      "sku": "MY_UNIQUE_SKU",
      "method": "GET",
      "uri": "/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice"
    },
    {
      "marketplaceId": "A1PA6795UKMFR9",
      "sku": "INVALID_SKU",
      "method": "GET",
      "uri": "/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice"
    }
  ]
}

Response properties

Body parameter

ParameterDescriptionRequired
responsesA batched list of featured offer expected price responses.
Type : < FeaturedOfferExpectedPriceResponse > array
Yes

Response example

{
  "responses": [
    {
      "request": {
        "marketplaceId": "MARKETPLACE_ID",
        "sku": "MY_SKU"
      },
      "status": {
        "statusCode": 200,
        "reasonPhrase": "Success"
      },
      "headers": {},
      "body": {
        "offerIdentifier": {
          "asin": "ASIN",
          "sku": "MY_SKU",
          "marketplaceId": "MARKETPLACE_ID",
          "fulfillmentType": "AFN",
          "sellerId": "MY_SELLER_ID"
        },
        "featuredOfferExpectedPriceResults": [
          {
            "featuredOfferExpectedPrice": {
              "listingPrice": {
                "amount": 10.00,
                "currencyCode": "USD"
              },
              "points": {
                "pointsNumber": 3,
                "pointsMonetaryValue": {
                  "amount": 0.03,
                  "currencyCode": "USD"
                }
              }
            },
            "resultStatus": "VALID_FOEP",
            "competingFeaturedOffer": {
              "offerIdentifier": {
                "asin": "ASIN",
                "marketplaceId": "MARKETPLACE_ID",
                "fulfillmentType": "AFN",
                "sellerId": "OTHER_SELLER_ID"
              },
              "condition": "New",
              "price": {
                "listingPrice": {
                  "amount": 12.00,
                  "currencyCode": "USD"
                },
                "shippingPrice": {
                  "amount": 0,
                  "currencyCode": "USD"
                },
                "points": {
                  "pointsNumber": 3,
                  "pointsMonetaryValue": {
                    "amount": 0.03,
                    "currencyCode": "USD"
                  }
                }
              }
            },
            "currentFeaturedOffer": {
              "offerIdentifier": {
                "asin": "ASIN",
                "marketplaceId": "MARKETPLACE_ID",
                "fulfillmentType": "AFN",
                "sellerId": "OTHER_SELLER_ID"
              },
              "condition": "New",
              "price": {
                "listingPrice": {
                  "amount": 12.00,
                  "currencyCode": "USD"
                },
                "shippingPrice": {
                  "amount": 0,
                  "currencyCode": "USD"
                },
                "points": {
                  "pointsNumber": 3,
                  "pointsMonetaryValue": {
                    "amount": 0.03,
                    "currencyCode": "USD"
                  }
                }
              }
            }
          }
        ]
      }
    },
    {
      "request": {
        "marketplaceId": "MARKETPLACE_ID",
        "sku": "MY_UNIQUE_SKU"
      },
      "status": {
        "statusCode": 200,
        "reasonPhrase": "Success"
      },
      "headers": {},
      "body": {
        "offerIdentifier": {
          "asin": "ASIN",
          "sku": "MY_UNIQUE_SKU",
          "marketplaceId": "MARKETPLACE_ID",
          "fulfillmentType": "AFN",
          "sellerId": "MY_SELLER_ID"
        },
        "featuredOfferExpectedPriceResults": [
          {
            "resultStatus": "NO_COMPETING_OFFERS",
            "currentFeaturedOffer": {
              "offerIdentifier": {
                "asin": "ASIN",
                "marketplaceId": "MARKETPLACE_ID",
                "fulfillmentType": "AFN",
                "sellerId": "MY_SELLER_ID"
              },
              "condition": "New",
              "price": {
                "listingPrice": {
                  "amount": 12.00,
                  "currencyCode": "USD"
                },
                "shippingPrice": {
                  "amount": 0,
                  "currencyCode": "USD"
                },
                "points": {
                  "pointsNumber": 3,
                  "pointsMonetaryValue": {
                    "amount": 0.03,
                    "currencyCode": "USD"
                  }
                }
              }
            }
          }
        ]
      }
    },
    {
      "request": {
        "marketplaceId": "MARKETPLACE_ID",
        "sku": "MY_NONEXISTENT_SKU"
      },
      "status": {
        "statusCode": 400,
        "reasonPhrase": "Client Error"
      },
      "headers": {},
      "body": {
        "errors": [
          {
            "code": "INVALID_SKU",
            "message": "The requested SKU does not exist for the seller in the requested marketplace."
          }
        ]
      }
    }
  ]
}

General recommendations

When to call the getFeaturedOfferExpectedPriceBatch operation

If your seller is subscribed to ANY_OFFER_CHANGED notifications and receives a notification for an ASIN that they want to compete with for the feature offer, you can request FOEP data.

About the resultStatus response property

The resultStatus response property indicates if Amazon returned an FOEP value. This also provides the reason why no FOEP value is returned, when applicable. The possible values are:

Result statusDescription
VALID_FOEPThe offer was eligible for FOEP. Amazon returned a valid FOEP value.
NO_COMPETING_OFFERThe offer might be eligible to become featured, but there are no other offers for that ASIN that are also eligible to become the featured offer.
OFFER_NOT_ELIGIBLEThe offer was not eligible to become the featured offer.
OFFER_NOT_FOUNDThe offer was not found. It might be unbuyable, or the merchant might not be qualified to be featured.
ASIN_NOT_ELIGIBLEThe ASIN is not eligible for an FOEP value.

Availability of the getFeaturedOfferExpectedPriceBatch operation

This API is available in all marketplaces.

Tutorial: Retrieve a list of featured offers for a batch of up to 20 ASINs

Learn how to retrieve information about the featured offers by ASIN (up to 20 ASINs) using a batch operation.

Prerequisites

To complete this tutorial, you must have:

Get the competitive summary

The getCompetitiveSummary operation retrieves detailed pricing and offer information for specific products within a marketplace. It returns data on featured buying options, reference prices, and the lowest-priced offers available, which include information such as the seller, item condition, listing price, and shipping costs. The response helps you compare various offers and pricing options, including segmented details based on customer type.

Call the getCompetitiveSummary operation and pass the following parameters:

Body parameters

NameDescriptionSchema
requestsThe List of CompetitiveSummaryRequest batched requests to run.Type: < CompetitiveSummaryRequest > array

Response

A successful response includes the following:

NameDescriptionSchema
responsesA list of CompetitiveSummary batched responses.Type: < CompetitiveSummary > array

ReferencePrices

The following reference prices might be returned in the referencePrices section of the API:

NameDescription
CompetitivePriceThresholdThis price is based on competitive prices from other retailers (excluding other Amazon sellers). The offer may be ineligible for the Buy Box if the seller's price + shipping (minus Amazon Points) is greater than this competitive price.
WasPriceThis price is determined using the 90-day median price paid by customers for the product on Amazon. We exclude prices paid by customers for the product during limited time promotions. For Amazon Fresh offers, the Typical Price is calculated as the median price offered locally in the last 35 days, excluding prices on promotions.

Request example

POST https://sellingpartnerapi-na.amazon.com/batches/products/pricing/2022-05-01/items/competitiveSummary
{
    "requests": [{
            "asin": "B00ZIAODGE",
            "marketplaceId": "ATVPDKIKX0DER",
            "includedData": [
                "featuredBuyingOptions",
                "referencePrices",
                "lowestPricedOffers"
            ],
            "lowestPricedOffersInputs": [{
                    "itemCondition": "New",
                    "offerType": "Consumer"
                },
                {
                    "itemCondition": "Used",
                    "offerType": "Consumer"
                }
            ],
            "uri": "/products/pricing/2022-05-01/items/competitiveSummary",
            "method": "GET"
        },
        {
            "asin": "11_AABB_123",
            "marketplaceId": "ATVPDKIKX0DER",
            "includedData": [
                "featuredBuyingOptions"
            ],
            "uri": "/products/pricing/2022-05-01/items/competitiveSummary",
            "method": "GET"
        }
    ]
}

Response example

{
    "responses": [{
            "status": {
                "statusCode": 200,
                "reasonPhrase": "Success"
            },
            "body": {
                "asin": "B00ZIAODGE",
                "marketplaceId": "ATVPDKIKX0DER",
                "featuredBuyingOptions": [{
                    "buyingOptionType": "New",
                    "segmentedFeaturedOffers": [{
                            "sellerId": "A3DJR8M9Y3OUPG",
                            "condition": "New",
                            "fulfillmentType": "MFN",
                            "listingPrice": {
                                "amount": 18.11,
                                "currencyCode": "USD"
                            },
                            "shippingOptions": [{
                                "shippingOptionType": "DEFAULT",
                                "price": {
                                    "amount": 2.50,
                                    "currencyCode": "USD"
                                }
                            }],
                            "points": {
                                "pointsNumber": 3,
                                "pointsMonetaryValue": {
                                    "amount": 0.03,
                                    "currencyCode": "USD"
                                }
                            },
                            "featuredOfferSegments": [{
                                    "customerMembership": "NON_PRIME",
                                    "segmentDetails": {
                                        "glanceViewWeightPercentage": 72
                                    }
                                },
                                {
                                    "customerMembership": "PRIME",
                                    "segmentDetails": {
                                        "glanceViewWeightPercentage": 10
                                    }
                                }
                            ]
                        },
                        {
                            "sellerId": "A2ZWOLFOFDPJL1",
                            "condition": "New",
                            "fulfillmentType": "MFN",
                            "listingPrice": {
                                "amount": 17.15,
                                "currencyCode": "USD"
                            },
                            "shippingOptions": [{
                                "shippingOptionType": "DEFAULT",
                                "price": {
                                    "amount": 2.50,
                                    "currencyCode": "USD"
                                }
                            }],
                            "points": {
                                "pointsNumber": 3,
                                "pointsMonetaryValue": {
                                    "amount": 0.03,
                                    "currencyCode": "USD"
                                }
                            },
                            "featuredOfferSegments": [{
                                "customerMembership": "NON_PRIME",
                                "segmentDetails": {
                                    "glanceViewWeightPercentage": 18
                                }
                            }]
                        }
                    ]
                }],
                "referencePrices": [{
                        "name": "CompetitivePriceThreshold",
                        "price": {
                            "amount": 18.11,
                            "currencyCode": "USD"
                        }
                    },
                    {
                        "name": "WasPrice",
                        "price": {
                            "amount": 18.49,
                            "currencyCode": "USD"
                        }
                    }
                ],
                "lowestPricedOffers": [{
                        "lowestPricedOffersInput": {
                            "itemCondition": "New",
                            "offerType": "Consumer"
                        },
                        "offers": [{
                                "listingPrice": {
                                    "currencyCode": "USD",
                                    "amount": 17.15
                                },
                                "shippingOptions": [{
                                    "shippingOptionType": "DEFAULT",
                                    "price": {
                                        "amount": 2.50,
                                        "currencyCode": "USD"
                                    }
                                }],
                                "points": {
                                    "pointsMonetaryValue": {
                                        "amount": 0.50,
                                        "currencyCode": "USD"
                                    },
                                    "pointsNumber": 50
                                },
                                "primeDetails": {
                                    "eligibility": "REGIONAL"
                                },
                                "subCondition": "New",
                                "sellerId": "A2ZWOLFOFDPJL1",
                                "fulfillmentType": "MFN"
                            },
                            {
                                "listingPrice": {
                                    "amount": 18.11,
                                    "currencyCode": "USD"
                                },
                                "shippingOptions": [{
                                    "shippingOptionType": "DEFAULT",
                                    "price": {
                                        "amount": 2.50,
                                        "currencyCode": "USD"
                                    }
                                }],
                                "points": {
                                    "pointsNumber": 3,
                                    "pointsMonetaryValue": {
                                        "amount": 0.03,
                                        "currencyCode": "USD"
                                    }
                                },
                                "primeDetails": {
                                    "eligibility": "NATIONAL"
                                },
                                "sellerId": "A3DJR8M9Y3OUPG",
                                "subCondition": "New",
                                "fulfillmentType": "MFN"
                            }
                        ]
                    },
                    {
                        "lowestPricedOffersInput": {
                            "itemCondition": "Used",
                            "offerType": "Consumer"
                        },
                        "offers": [{
                            "listingPrice": {
                                "currencyCode": "USD",
                                "amount": 12.00
                            },
                            "shippingOptions": [{
                                "shippingOptionType": "DEFAULT",
                                "price": {
                                    "amount": 2.50,
                                    "currencyCode": "USD"
                                }
                            }],
                            "primeDetails": {
                                "eligibility": "REGIONAL"
                            },
                            "subCondition": "Acceptable",
                            "sellerId": "A3DH5AGPM3JVAB",
                            "fulfillmentType": "AFN"
                        }]
                    }
                ]
            }
        },
        {
            "status": {
                "statusCode": 400,
                "reasonPhrase": "Client Error"
            },
            "body": {
                "asin": "11_AABB_123",
                "marketplaceId": "ATVPDKIKX0DER",
                "errors": [{
                    "code": "INVALID_ASIN",
                    "message": "11_AABB_123 is not a valid ASIN"
                }]
            }
        }
    ]
}