Product Pricing API v2022-05-01 Use Case Guide

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 : < `FeaturedOfferExpectedPriceRequest` > array

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

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

This 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"
	  ],
	  "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
					  }
					}
				  ]
				}
			  ]
			}
		  ]
		}
	  },
	  {
		"status": {
		  "statusCode": 400,
		  "reasonPhrase": "Invalid Input"
		},
		"body": {
		  "asin": "11_AABB_123",
		  "marketplaceId": "ATVPDKIKX0DER",
		  "errors": [
			{
			  "code": "INVALID_ASIN",
			  "message": "11_AABB_123 is not a valid ASIN"
			}
		  ]
		}
	  }
	]
  }

What is the Product Pricing API?

Key features

Terminology

Tutorial 1: Return a batch of featured offer expected price data for a set of SKUs

Prerequisites

Step 1: Get the featured offer expected price data for a set of SKUs

Request parameters

Request example

Response properties

Response example

General recommendations

When to call the getFeaturedOfferExpectedPriceBatch operation

About the resultStatus response property

Availability of the getFeaturedOfferExpectedPriceBatch operation

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

Prerequisites

Get the competitive summary

Response

Request example

Response example

When to call the `getFeaturedOfferExpectedPriceBatch` operation

About the `resultStatus` response property

Availability of the `getFeaturedOfferExpectedPriceBatch` operation