Product Pricing API v2022-05-01 Reference
Retrieve product pricing and offer information for Amazon Marketplace products.
The Selling Partner API for Pricing helps you programmatically retrieve product pricing and offer pricing information for Amazon Marketplace products.
For more information, refer to the Product Pricing v2022-05-01 Use Case Guide.
Version information
Version : 2022-05-01
Contact information
Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html
License information
License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
URI scheme
Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS
Consumes
application/json
Produces
application/json
Operations
getFeaturedOfferExpectedPriceBatch
getCompetitiveSummary
Paths
POST /batches/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice
Operation: getFeaturedOfferExpectedPriceBatch
Description
Returns the set of responses that correspond to the batched list of up to 40 requests defined in the request body. The response for each successful (HTTP status code 200) request in the set includes the computed listing price at or below which a seller can expect to become the featured offer (before applicable promotions). This is called the featured offer expected price (FOEP). Featured offer is not guaranteed because competing offers might change. Other offers might be featured based on factors such as fulfillment capabilities to a specific customer. The response to an unsuccessful request includes the available error text.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 0.033 | 1 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that are applied to the requested operation, when available. The preceding table contains the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may receive higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | getFeaturedOfferExpectedPriceBatchRequestBody required | The batch of getFeaturedOfferExpectedPrice requests. | GetFeaturedOfferExpectedPriceBatchRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetFeaturedOfferExpectedPriceBatchResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
POST /batches/products/pricing/2022-05-01/items/competitiveSummary
Operation: getCompetitiveSummary
Description
Returns the competitive summary response, including featured buying options for the ASIN and marketplaceId combination.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 0.033 | 1 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that are applied to the requested operation, when available. The preceding table contains the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may receive higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | requests required | The batch of getCompetitiveSummary requests. | CompetitiveSummaryBatchRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | CompetitiveSummaryBatchResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | Errors |
| 401 | The request's Authorization header is not formatted correctly or does not contain a valid token. Headers: x-amzn-RequestId (string):Unique request reference identifier. | Errors |
| 403 | Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: x-amzn-RequestId (string):Unique request reference identifier. | Errors |
| 404 | The specified resource does not exist. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | Errors |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RequestId (string):Unique request reference identifier. | Errors |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers: x-amzn-RequestId (string):Unique request reference identifier. | Errors |
| 503 | Temporary overloading or maintenance of the server. Headers: x-amzn-RequestId (string):Unique request reference identifier. | Errors |
Definitions
GetFeaturedOfferExpectedPriceBatchRequest
The request body for the getFeaturedOfferExpectedPriceBatch operation.
| Name | Description | Schema |
|---|---|---|
| requests optional | A batched list of FOEP requests. | FeaturedOfferExpectedPriceRequestList |
FeaturedOfferExpectedPriceRequestList
A batched list of FOEP requests.
Type : < FeaturedOfferExpectedPriceRequest > array
Min items : 1
FeaturedOfferExpectedPriceRequest
An individual FOEP request for a particular SKU.
Polymorphism : Composition
| Name | Description | Schema |
|---|---|---|
| uri required | The URI associated with an individual request within a batch. For FeaturedOfferExpectedPrice, this is /products/pricing/2022-05-01/offer/featuredOfferExpectedPrice. | string |
| method required | The HTTP method associated with an individual request within a batch. | HttpMethod |
| body optional | Additional HTTP body information that is associated with an individual request within a batch. | HttpBody |
| headers optional | A mapping of additional HTTP headers to send or receive for an individual request within a batch. | HttpHeaders |
| marketplaceId required | A marketplace identifier. Specifies the marketplace for which data is returned. | MarketplaceId |
| sku required | The seller SKU of the item. | Sku |
FeaturedOfferExpectedPriceRequestParams
The parameters for an individual request.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | A marketplace identifier. Specifies the marketplace for which data is returned. | MarketplaceId |
| sku required | The seller SKU of the item. | Sku |
GetFeaturedOfferExpectedPriceBatchResponse
The response schema for the getFeaturedOfferExpectedPriceBatch operation.
| Name | Description | Schema |
|---|---|---|
| responses optional | A batched list of FOEP responses. | FeaturedOfferExpectedPriceResponseList |
FeaturedOfferExpectedPriceResponseList
A batched list of FOEP responses.
Type : < FeaturedOfferExpectedPriceResponse > array
Min items : 1
FeaturedOfferExpectedPriceResponse
Schema for an individual FOEP response.
Polymorphism : Composition
| Name | Description | Schema |
|---|---|---|
| headers required | A mapping of additional HTTP headers to send or receive for an individual request within a batch. | HttpHeaders |
| status required | The HTTP status line associated with the response for an individual request within a batch. For more information, refer to RFC 2616. | HttpStatusLine |
| request required | Use these request parameters to map the response back to the request. | FeaturedOfferExpectedPriceRequestParams |
| body optional | The FOEP response data for a requested SKU. | FeaturedOfferExpectedPriceResponseBody |
CompetitiveSummaryBatchRequest
The competitiveSummary batch request data.
| Name | Description | Schema |
|---|---|---|
| requests required | A batched list of competitiveSummary requests. | CompetitiveSummaryRequestList |
CompetitiveSummaryRequestList
A batched list of competitiveSummary requests.
Type : < CompetitiveSummaryRequest > array
Min items : 1
Max items : 20
CompetitiveSummaryRequest
An individual competitiveSummary request for an ASIN and marketplaceId.
| Name | Description | Schema |
|---|---|---|
| asin required | The Amazon Standard Identification Number for the item. | Asin |
| marketplaceId required | A marketplace identifier. | MarketplaceId |
| includedData required | The list of requested competitive pricing data for the product. | < CompetitiveSummaryIncludedData > array |
| lowestPricedOffersInputs optional | The list of lowestPricedOffersInput parameters that are used to build lowestPricedOffers in the response. This attribute is only valid if lowestPricedOffers is requested in includedData | < LowestPricedOffersInput > array |
| method required | HTTP method type | HttpMethod |
| uri required | The URI associated with the individual APIs that are called as part of the batch request. For getCompetitiveSummary, this is /products/pricing/2022-05-01/items/competitiveSummary. | HttpUri |
CompetitiveSummaryIncludedData
The supported data types in the getCompetitiveSummary API.
Type : enum
| Value | Description |
|---|---|
| featuredBuyingOptions | Describes the current segmented featured offer information for the item. |
| referencePrices | Provides reference price points for the item, such as the Competitive Price Threshold. |
| lowestPricedOffers | The lowest-priced standard offers that are available for the item in the Amazon store. |
LowestPricedOffersInput
The input required for building LowestPricedOffers data in the response.
| Name | Description | Schema |
|---|---|---|
| itemCondition required | The input parameter specifies the itemCondition of the offer that is requested for LowestPricedOffers. New is the default value for itemCondition. | Condition |
| offerType required | The input parameter specifies the type of offers requested for LowestPricedOffers. This applies to Consumer and Business offers. Consumer is the default offerType. | enum (OfferType) |
CompetitiveSummaryBatchResponse
The response schema for the competitiveSummaryBatch operation.
| Name | Description | Schema |
|---|---|---|
| responses required | The response list for the competitiveSummaryBatch operation. | CompetitiveSummaryResponseList |
CompetitiveSummaryResponseList
The response list for the competitiveSummaryBatch operation.
Type : < CompetitiveSummaryResponse > array
Min items : 1
Max items : 20
CompetitiveSummaryResponse
The response for the individual competitiveSummary request in the batch operation.
| Name | Description | Schema |
|---|---|---|
| status required | The HTTP status line associated with the response. For more information, refer to RFC 2616. | HttpStatusLine |
| body required | The competitiveSummaryResponse body for a requested ASIN and marketplaceId. | CompetitiveSummaryResponseBody |
CompetitiveSummaryResponseBody
The competitiveSummaryResponse body for a requested ASIN and marketplaceId.
| Name | Description | Schema |
|---|---|---|
| asin required | The Amazon identifier for the item. | Asin |
| marketplaceId required | A marketplace identifier. | MarketplaceId |
| featuredBuyingOptions optional | A list of featured buying options for the specified ASIN marketplaceId combination. | < FeaturedBuyingOption > array |
| lowestPricedOffers optional | A list of lowest priced offers for the specified ASIN marketplaceId combination. | < LowestPricedOffer > array |
| referencePrices optional | A list of reference prices for the specified ASIN marketplaceId combination. | < ReferencePrice > array |
| errors optional | A list of errors | ErrorList |
ReferencePrice
The reference price for the specified ASIN marketplaceId combination.
| Name | Description | Schema |
|---|---|---|
| name required | The name of the reference price, such as CompetitivePriceThreshold and WasPrice. For reference price definitions, refer to the Use Case Guide. | string |
| price required | The reference price for the ASIN marketplaceId combination. | MoneyType |
FeaturedBuyingOption
Describes a featured buying option, which includes a list of segmented featured offers for a particular item condition.
| Name | Description | Schema |
|---|---|---|
| buyingOptionType required | The buying option type for the featured offer. buyingOptionType represents the buying options that a customer receives on the detail page, such as B2B, Fresh, and Subscribe n Save. buyingOptionType currently supports NEW as a value. | enum (BuyingOptionType) |
| segmentedFeaturedOffers required | A list of segmented featured offers for the current buying option type. A segment can be considered as a group of regional contexts that all have the same featured offer. A regional context is a combination of factors such as customer type, region, or postal code and buying option. | < SegmentedFeaturedOffer > array |
SegmentedFeaturedOffer
A product offer with segment information indicating where it's featured.
Polymorphism : Composition
| Name | Description | Schema |
|---|---|---|
| sellerId required | The seller identifier for the offer. | string |
| condition required | Item Condition. | Condition |
| subCondition optional | The item subcondition of the offer. | enum (SubCondition) |
| fulfillmentType required | The fulfillment type for the offer. Possible values are AFN (Amazon Fulfillment Network) and MFN (Merchant Fulfillment Network). | FulfillmentType |
| listingPrice required | The offer buying price. This doesn't include shipping, points, or applicable promotions. | MoneyType |
| shippingOptions optional | A list of shipping options associated with this offer | < ShippingOption > array |
| points optional | The number of Amazon Points that are offered with the purchase of an item and the monetary value of these points. Note that the Points element is only returned in Japan (JP). | Points |
| primeDetails optional | Amazon Prime details. | PrimeDetails |
| featuredOfferSegments required | The list of segment information in which the offer is featured. | < FeaturedOfferSegment > array |
LowestPricedOffer
Describes the lowest priced offers for the specified item condition and offer type.
| Name | Description | Schema |
|---|---|---|
| lowestPricedOffersInput required | The filtering criteria that are used to retrieve the lowest priced offers that correspond to the lowestPricedOffersInputs request. | LowestPricedOffersInput |
| offers required | A list of up to 20 lowest priced offers that match the criteria specified in lowestPricedOffersInput. | < Offer > array |
Offer
The offer data of a product.
| Name | Description | Schema |
|---|---|---|
| sellerId required | The seller identifier for the offer. | string |
| condition required | Item Condition. | Condition |
| subCondition optional | The item subcondition of the offer. | enum (SubCondition) |
| fulfillmentType required | The fulfillment type for the offer. Possible values are AFN (Amazon Fulfillment Network) and MFN (Merchant Fulfillment Network). | FulfillmentType |
| listingPrice required | The offer buying price. This doesn't include shipping, points, or applicable promotions. | MoneyType |
| shippingOptions optional | A list of shipping options associated with this offer | < ShippingOption > array |
| points optional | The number of Amazon Points that are offered with the purchase of an item and the monetary value of these points. Note that the Points element is only returned in Japan (JP). | Points |
| primeDetails optional | Amazon Prime details. | PrimeDetails |
PrimeDetails
Amazon Prime details.
| Name | Description | Schema |
|---|---|---|
| eligibility required | Indicates whether the offer is an Amazon Prime offer. | enum (Eligibility) |
ShippingOption
The shipping option available for the offer.
| Name | Description | Schema |
|---|---|---|
| shippingOptionType required | The type of shipping option. | enum (ShippingOptionType) |
| price required | Shipping price for the offer. | MoneyType |
FeaturedOfferSegment
Describes the segment in which the offer is featured.
| Name | Description | Schema |
|---|---|---|
| customerMembership required | The customer membership type that makes up this segment | enum (CustomerMembership) |
| segmentDetails required | The details about the segment. | SegmentDetails |
SegmentDetails
The details about the segment.
| Name | Description | Schema |
|---|---|---|
| glanceViewWeightPercentage optional | The glance view weighted percentage for this segment, which is the glance views for this segment as a percentage of total glance views across all segments for the ASIN. A higher percentage indicates that more Amazon customers receive this offer as the Featured Offer. | number |
Errors
A list of error responses returned when a request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| errors required | One or more unexpected errors occurred during the operation. | ErrorList |
FeaturedOfferExpectedPriceResponseBody
The FOEP response data for a requested SKU.
| Name | Description | Schema |
|---|---|---|
| offerIdentifier optional | Metadata that identifies the target offer for which the FOEP result data was computed. | OfferIdentifier |
| featuredOfferExpectedPriceResults optional | The FOEP results for the requested target offer. | FeaturedOfferExpectedPriceResultList |
| errors optional | The errors that occurred if the operation wasn't successful (HTTP status code non-200). | ErrorList |
FeaturedOfferExpectedPriceResultList
A list of FOEP results for the requested offer.
Type : < FeaturedOfferExpectedPriceResult > array
FeaturedOfferExpectedPriceResult
The FOEP result data for the requested offer.
| Name | Description | Schema |
|---|---|---|
| featuredOfferExpectedPrice optional | The item price at or below which the target offer may be featured. | FeaturedOfferExpectedPrice |
| resultStatus required | The status of the FOEP computation. Possible values include VALID_FOEP, NO_COMPETING_OFFER, OFFER_NOT_ELIGIBLE, OFFER_NOT_FOUND, and ASIN_NOT_ELIGIBLE. Additional values might be added in the future. | string |
| competingFeaturedOffer optional | The offer that will likely be the featured offer if the target offer is priced above its FOEP. If the target offer is currently the featured offer, this property will be different than currentFeaturedOffer. | FeaturedOffer |
| currentFeaturedOffer optional | The offer that is currently the featured offer. If the target offer is not currently featured, then this property will be equal to competingFeaturedOffer. | FeaturedOffer |
FeaturedOfferExpectedPrice
The item price at or below which the target offer may be featured.
| Name | Description | Schema |
|---|---|---|
| listingPrice required | A computed listing price at or below which a seller can expect to become the featured offer (before applicable promotions). | MoneyType |
| points optional | The number of Amazon Points that are offered with the purchase of an item and the monetary value of these points. | Points |
FeaturedOffer
Schema for currentFeaturedOffer or competingFeaturedOffer.
| Name | Description | Schema |
|---|---|---|
| offerIdentifier required | An offer identifier used to identify the merchant of the featured offer. Since this may not belong to the requester, the SKU field is omitted. | OfferIdentifier |
| condition optional | The item condition. | Condition |
| price optional | The current active price of the offer. | Price |
HttpHeaders
A mapping of additional HTTP headers to send or receive for an individual request within a batch.
Type : < string, string > map
HttpStatusLine
The HTTP status line associated with the response for an individual request within a batch. For more information, refer to RFC 2616.
| Name | Description | Schema |
|---|---|---|
| statusCode optional | The HTTP response status code. Minimum value : 100 Maximum value : 599 | integer |
| reasonPhrase optional | The HTTP response reason phrase. | string |
HttpBody
Additional HTTP body information that is associated with an individual request within a batch.
Type : object
HttpUri
The URI associated with the individual APIs that are called as part of the batch request.
Type : string
minLength : 6
maxLength : 512
HttpMethod
The HTTP method associated with an individual request within a batch.
Type : enum
| Value | Description |
|---|---|
| GET | GET |
| PUT | PUT |
| PATCH | PATCH |
| DELETE | DELETE |
| POST | POST |
BatchRequest
The common properties for individual requests within a batch.
| Name | Description | Schema |
|---|---|---|
| uri required | The URI associated with an individual request within a batch. For FeaturedOfferExpectedPrice, this is /products/pricing/2022-05-01/offer/featuredOfferExpectedPrice. | string |
| method required | The HTTP method associated with an individual request within a batch. | HttpMethod |
| body optional | Additional HTTP body information that is associated with an individual request within a batch. | HttpBody |
| headers optional | A mapping of additional HTTP headers to send or receive for an individual request within a batch. | HttpHeaders |
BatchResponse
The common properties for responses to individual requests within a batch.
| Name | Description | Schema |
|---|---|---|
| headers required | A mapping of additional HTTP headers to send or receive for an individual request within a batch. | HttpHeaders |
| status required | The HTTP status line associated with the response for an individual request within a batch. For more information, refer to RFC 2616. | HttpStatusLine |
OfferIdentifier
Identifies an offer from a particular seller for a specified ASIN.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | A marketplace identifier. | MarketplaceId |
| sellerId optional | The seller identifier for the offer. | string |
| sku optional | The seller SKU of the item. This will only be present for the target offer, which belongs to the requesting seller. | string |
| asin required | The Amazon identifier for the item. | Asin |
| fulfillmentType optional | The fulfillment type for the offer. | FulfillmentType |
MoneyType
Currency type and monetary value schema to demonstrate pricing information.
| Name | Description | Schema |
|---|---|---|
| currencyCode optional | The currency code in ISO 4217 format. | string |
| amount optional | The monetary value. | number |
Price
The schema for item's price information, including listing price, shipping price, and Amazon Points.
| Name | Description | Schema |
|---|---|---|
| listingPrice required | The listing price for the item, excluding any promotions. | MoneyType |
| shippingPrice optional | The shipping cost of the product. Note that the shipping cost is not always available. | MoneyType |
| points optional | The number of Amazon Points that are offered with the purchase of an item and the monetary value of these points. | Points |
Points
The number of Amazon Points that are offered with the purchase of an item and the monetary value of these points.
| Name | Description | Schema |
|---|---|---|
| pointsNumber optional | The number of Amazon Points. | integer (int32) |
| pointsMonetaryValue optional | The monetary value of the Amazon Points. | MoneyType |
FulfillmentType
Indicates whether the item is fulfilled by Amazon or by the seller (merchant).
Type : enum
| Value | Description |
|---|---|
| AFN | Fulfilled by Amazon. |
| MFN | Fulfilled by the seller. |
MarketplaceId
A marketplace identifier. Specifies the marketplace for which data is returned.
Type : string
Sku
The seller SKU of the item.
Type : string
Condition
The condition of the item.
Type : enum
| Value | Description |
|---|---|
| New | New |
| Used | Used |
| Collectible | Collectible |
| Refurbished | Refurbished |
| Club | Club |
Asin
The ASIN of the item.
Type : string
ErrorList
A list of error responses that are returned when a request is unsuccessful.
Type : < Error > array
Error
Error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
CustomerMembership
The customer membership type that makes up this segment
Type : enum
| Value | Description |
|---|---|
| PRIME | PRIME |
| NON_PRIME | NON_PRIME |
Eligibility
Indicates whether the offer is an Amazon Prime offer.
Type : enum
| Value | Description |
|---|---|
| NATIONAL | Indicates that this offer has Amazon Prime eligibility in all regions within the marketplace. |
| REGIONAL | Indicates that this offer has Amazon Prime eligibility in some (but not all) regions within the marketplace. |
| NONE | Indicates that this offer is not an Amazon Prime offer in any region within the marketplace. |
BuyingOptionType
The buying option type for the featured offer. buyingOptionType represents the buying options that a customer receives on the detail page, such as B2B, Fresh, and Subscribe n Save. buyingOptionType currently supports NEW as a value.
Type : enum
| Value | Description |
|---|---|
| New | New |
SubCondition
The item subcondition of the offer.
Type : enum
| Value | Description |
|---|---|
| New | New |
| Mint | Mint |
| VeryGood | VeryGood |
| Good | Good |
| Acceptable | Acceptable |
| Poor | Poor |
| Club | Club |
| OEM | OEM |
| Warranty | Warranty |
| RefurbishedWarranty | RefurbishedWarranty |
| Refurbished | Refurbished |
| OpenBox | OpenBox |
| Other | Other |
ShippingOptionType
The type of shipping option.
Type : enum
| Value | Description |
|---|---|
| DEFAULT | The estimated shipping cost of the product. Note that the shipping cost is not always available. |
OfferType
The input parameter specifies the type of offers requested for LowestPricedOffers. This applies to Consumer and Business offers. Consumer is the default offerType.
Type : enum
| Value | Description |
|---|---|
| CONSUMER | An offer that is available to all Amazon customers. |
Updated 3 days ago