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?
You can use the Product Pricing API v2022-05-01 to help a seller compete for featured offer placement on the product detail page, for items listed in new condition that ship nationwide. 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 featured offer expected price (FOEP) for a SKU. Because competing offers can change, featured offer is not guaranteed. Different offers can be featured based on other factors, including fulfillment capabilities to a specific customer. You can use the getFeaturedOfferExpectedPriceBatch
operation to retrieve batch reponses of up to 40 FOEP requests.
FOEP values are automatically generated and all users are encouraged to carefully verify the calculated values. All sellers using the API remain responsible, as the retailer of record for their offers, for setting their prices independently and in compliance with applicable laws and pricing regulations. Note that if there are no other competing offers that ship nationwide, Amazon might not return a value for the FOEP.
The getFeaturedOfferExpectedPriceBatch
operation is available in all marketplaces except Japan. For details about Product Pricing API operations, associated data types, and schemas, refer to the Product Pricing v2022-05-01 API Reference.
Key features
- Retrieve featured offer expected price response data: The
getFeaturedOfferExpectedPriceBatch
operation of the Product Pricing API 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. - Responses include a result status for each response: The result status indicates if a valid FOEP exists.
- Responses include the FOEP, competing featured offer, and current featured offer: The seller can use this information to compete for featured offer placement.
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. 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.
-
Featured offer expected price (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 priced higher than the featured offer expected price.
-
Current featured offer: An offer that has been selected as featured offer.
Tutorial 1: Return a batch of featured offer expected price data for a set of SKUs
Use this tutorial to return the set of responses for up to 40 requests for featured offer extended price data.
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 in the app registration page for your application.
Step 1: Get the featured offer expected price 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 featured offer expected price 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 : < |
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 : < |
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 whether Amazon returned an FOEP value and, if not, the reason why. Here are the possible values:
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 except Japan (JP). Calls to the JP marketplace return a 400 response (InvalidMarketplace
).
Tutorial: Retrieve a list of featured offers for a batch of up to 20 ASINs
This tutorial shows you how to retrieve information about the featured offers by ASIN (up to 20 ASINs) using a batch operation.
Prerequisites
To successfully complete this tutorial, you must have the following:
- 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 role assigned to your developer profile.
- The Pricing and Product Listing role selected in the app registration page for your application.
Get the competitive summary
The getCompetitiveSummary
operation retrieves the current featured offers for a batch of items by ASIN. This operation allows up to 20 ASIN requests in a single batch. Call the getCompetitiveSummary
operation, passing 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 |
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"
],
"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.5,
"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.5,
"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"
}
}
],
"lowestPricedOffers": [
{
"lowestPricedOffersInput": {
"itemCondition": "New",
"offerType": "Consumer"
},
"offers": [
{
"listingPrice": {
"currencyCode": "USD",
"amount": 17.15
},
"shippingOptions": [
{
"shippingOptionType": "DEFAULT",
"price": {
"amount": 2.5,
"currencyCode": "USD"
}
}
],
"points": {
"pointsMonetaryValue": {
"amount": 0.5,
"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.5,
"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
},
"shippingOptions": [
{
"shippingOptionType": "DEFAULT",
"price": {
"amount": 2.5,
"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 19 days ago