Product Pricing API v2022-05-01 Use Case Guide

API Version: 2022-05-01

What is the Product Pricing API?

Using this version of the Selling Partner API for Product Pricing (Product Pricing API), you can 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 an SKU (stock keeping unit). Featured offer is not guaranteed, because competing offers may change, and different offers may be featured based on other factors, including fulfillment capabilities to a specific customer. The getFeaturedOfferExpectedPriceBatch operation lets you retrieve responses to a batch of up to 40 FOEP requests.

Note that if there are no other competing offers that ship nationwide, Amazon may not return a value for the FOEP.

This operation is available in the following marketplaces: France, Italy, Spain, Germany, Sweden, Poland, Netherlands, Belgium. See the Product Pricing v2022-05-01 API Reference for details about API operations and associated data types and schemas.

Key Features

Retrieve featured offer expected price response data: The getFeaturedOfferExpectedPriceBatch operation of the Product Pricing API lets you receive the 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 whether 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 may become featured if the target offer is priced above 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. See the Selling Partner API Developer Guide for more information.
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 will be a batch response that contains the list of individual HTTP responses, each mapping to one of the original requested SKUs in the batch.

Call the getFeaturedOfferExpectedPriceBatch operation to return featured offer expected price data, passing 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

You may wish to request featured offer expected price data if the seller has subscribed to the ANY_OFFER_CHANGED notification and then receives a notification for an ASIN for which they may want to compete for the featured offer.

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 may 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 may be unbuyable, or the merchant may not be qualified to be featured.

Availability of the getFeaturedOfferExpectedPriceBatch operation

This API is available in the marketplaces listed in What is the Product Pricing API?. Calls to NA and JP regions will fail, and calls to EU region for unavailable marketplaces will return a 400 response (InvalidMarketplace).