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
getFeaturedOfferExpectedPriceBatchoperation 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
getCompetitiveSummaryAPI 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
| Parameter | Description | Required |
|---|---|---|
requests | A 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
| Parameter | Description | Required |
|---|---|---|
responses | A 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
getFeaturedOfferExpectedPriceBatch operationIf 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
resultStatus response propertyThe 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 status | Description |
|---|---|
VALID_FOEP | The offer was eligible for FOEP. Amazon returned a valid FOEP value. |
NO_COMPETING_OFFER | The 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_ELIGIBLE | The offer was not eligible to become the featured offer. |
OFFER_NOT_FOUND | The offer was not found. It might be unbuyable, or the merchant might not be qualified to be featured. |
ASIN_NOT_ELIGIBLE | The ASIN is not eligible for an FOEP value. |
Availability of the getFeaturedOfferExpectedPriceBatch operation
getFeaturedOfferExpectedPriceBatch operationThis 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:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
- The Pricing and Product Listing roles assigned to your developer profile.
- The Pricing and Product Listing roles selected in the app registration page for your application.
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
| Name | Description | Schema |
|---|---|---|
requests | The List of CompetitiveSummaryRequest batched requests to run. | Type: < CompetitiveSummaryRequest > array |
Response
A successful response includes the following:
| Name | Description | Schema |
|---|---|---|
| responses | A list of CompetitiveSummary batched responses. | Type: < CompetitiveSummary > array |
ReferencePrices
ReferencePricesThe following reference prices might be returned in the referencePrices section of the API:
| Name | Description |
|---|---|
CompetitivePriceThreshold | This 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. |
WasPrice | This 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"
}]
}
}
]
}
Updated 14 days ago