Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation

Deprecation Notice:

Amazon Marketplace Web Service (MWS) will no longer be available after March 31, 2024. All MWS developers must migrate to Selling Partner API (SP-API) to avoid service disruptions. Refer to the Migration Hub for more information.

Amazon MWS Documentation

Recommendations Datatypes

The following datatypes are used in the request parameters and response elements of the Amazon Marketplace Web Service (Amazon MWS) Recommendations API section:

Datatype Description
AdvertisingRecommendation A recommendation for advertising your products and for using the sponsored products program.
CategoryQuery A category-specific filter that you can specify to narrow down the types of recommendations returned for each category.
DimensionMeasure Dimension unit and amount
FulfillmentRecommendation A recommendation for the top products to fulfill through Fulfillment by Amazon (FBA).
GlobalSellingRecommendation A recommendation for expanding your products to more regions and marketplaces.
InventoryRecommendation A recommendation for restocking low or out-of-stock items in your inventory.
ItemDimensions The dimensions of an item.
Price Currency type and amount.
PricingRecommendation A recommendation to review pricing on items in your inventory where your offer is not the lowest price.
ProductIdentifier The ASIN, SKU, and UPC of the item.
WeightMeasure Weight unit and amount.

AdvertisingRecommendation

A recommendation for advertising your products and for using the sponsored products program. This datatype is used in all marketplaces except Brazil.

Operations

The AdvertisingRecommendation datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the AdvertisingRecommendation datatype:

Name Description
RecommendationId A unique recommendation identifier, in the format of {Category}-{RecommendationReason}-{ASIN}-{SKU}-{UPC}-{ItemName}. If any of these values are null, the value will be empty.

Type: xs:string

RecommendationReason A detailed description of the recommendation.

Type: xs:string

LastUpdated The date and time when the recommendation was generated or last updated. In ISO 8601 date time format.

Type: xs:dateTime

ItemIdentifier The ASIN, SKU, and UPC of the item.

Type: ProductIdentifier

ItemName The name of the item.

Optional

Type: xs:string

BrandName The brand name of the item.

Optional

Type: xs:string

ProductCategory The product category of the item.

Optional

Type: xs:string

SalesRank The sales rank of the item in the given product category.

Optional

Type: xs:int

YourPricePlusShipping The price that you have set for the item, including shipping.

Optional

Type: Price

LowestPricePlusShipping The lowest price for the item in the same Condition and SubCondition, including shipping.

Optional

Type: Price

AvailableQuantity The total number of the items in your inventory.

Optional

Type: xs:int

SalesForTheLast30Days The number of your sales of the item in the last 30 days.

Optional

Type: xs:int

CategoryQuery

A category-specific filter that you can specify to narrow down the types of recommendations returned for each category.

Operations

The CategoryQuery datatype is used in a request parameter of the following operations:

Datatype content

The following table shows the elements of the CategoryQuery datatype:

Name Description Required Valid values
RecommendationCategory Specifies a category for the recommendations to retrieve.

Type: xs:string

Yes RecommendationCategory values:
  • Selection
  • Fulfillment
  • ListingQuality
  • GlobalSelling
  • Advertising
Note: If you specify a RecommendationCategory value here that was not specified in the RecommendationCategory request parameter to the ListRecommendations operation, then this value is ignored.
FilterOptions Specifies the filters to apply to narrow down the recommendations to return for the given recommendation category.

Filters are specified as a list of FilterName=FilterValue pairs. For more information, see the examples for the ListRecommendations operation.

Yes FilterOptions values for ListingQuality recommendations:
  • QualitySet=Defect Filter for listings that have a defect, but the listing is still valid. For example, this query will return listings where there is no detailed description.
  • QualitySet=Quarantine Filter for listings that are being suppressed from the catalog because they do not meet Amazon's standards. For example, this query will return listings where there is no main image.
  • ListingStatus=Active Filter for active inventory items only. Returns items within inventory that are set to active status.
  • ListingStatus=Inactive Filter for inactive inventory items only. Returns items within inventory that are set to inactive status.

FilterOptions values for Selection, Fulfillment, GlobalSelling, and Advertising recommendations:

  • BrandName=<BrandName> - Filter for recommendations that apply to the specified brand name.
  • ProductCategory=<ProductCategory> - Filter for recommendations that apply to the specified product category.

FilterOptions values for Selection recommendations:

  • IncludeCommonRecommendations=true - Include Selection recommendations common to all sellers in addition to seller-specific recommendations.
  • IncludeCommonRecommendations=false - Do not include Selection recommendations common to all sellers. Only include seller-specific recommendations.

DimensionMeasure

Operations

The DimensionMeasure datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the DimensionMeasure datatype:

Name Description
Value The value of the measurement.

Type: xs:decimal

Unit The unit of the measurement.

Type: xs:string

FulfillmentRecommendation

A recommendation for the top products to fulfill through Fulfillment by Amazon (FBA). This datatype is used in all marketplaces except Brazil.

Operations

The FulfillmentRecommendation datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the FulfillmentRecommendation datatype:

Name Description
RecommendationId A unique recommendation identifier, in the format of {Category}-{RecommendationReason}-{ASIN}-{SKU}-{UPC}-{ItemName}. If any of these values are null, the value will be empty.

Type: xs:string

RecommendationReason A detailed description of the recommendation.

Type: xs:string

LastUpdated The date and time when the recommendation was generated or last updated. In ISO 8601 date time format.

Type: xs:dateTime

ItemIdentifier The ASIN, SKU, and UPC of the item.

Type: ProductIdentifier

ItemName The name of the item.

Optional

Type: xs:string

BrandName The brand name of the item.

Optional

Type: xs:string

ProductCategory The product category of the item.

Optional

Type: xs:string

SalesRank The sales rank of the item in the given product category.

Optional

Type: xs:int

BuyboxPrice The price of the item that is displayed in the Buy Box.

Optional

Type: Price

NumberOfOffers The number of current offers for the item.

Optional

Type: xs:int

NumberOfOffersFulfilledByAmazon The number of current offers for the item that are fulfilled by Amazon.

Optional

Type: xs:int

AverageCustomerReview The average customer review of the item.

Optional

Type: xs:decimal

NumberOfCustomerReviews The number of customer reviews for the item.

Optional

Type: xs:int

ItemDimensions The dimensions of the item.

Optional

Type: ItemDimensions

GlobalSellingRecommendation

A recommendation for expanding your products to more regions and marketplaces.

Operations

The GlobalSellingRecommendation datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the GlobalSellingRecommendation datatype:

Name Description
RecommendationId A unique recommendation identifier, in the format of {Category}-{RecommendationReason}-{ASIN}-{SKU}-{UPC}-{ItemName}. If any of these values are null, the value will be empty.

Type: xs:string

RecommendationReason A detailed description of the recommendation.

Type: xs:string

LastUpdated The date and time when the recommendation was generated or last updated. In ISO 8601 date time format.

Type: xs:dateTime

ItemIdentifier The ASIN, SKU, and UPC of the item.

Type: ProductIdentifier

ItemName The name of the item.

Optional

Type: xs:string

BrandName The brand name of the item.

Optional

Type: xs:string

ProductCategory The product category of the item.

Optional

Type: xs:string

SalesRank The sales rank of the item in the given product category.

Optional

Type: xs:int

BuyboxPrice The price of the item that is displayed in the Buy Box.

Optional

Type: Price

NumberOfOffers The number of current offers for the item.

Optional

Type: xs:int

NumberOfOffersFulfilledByAmazon The number of current offers for the item that are fulfilled by Amazon.

Optional

Type: xs:int

AverageCustomerReview The average customer review of the item.

Optional

Type: xs:decimal

NumberOfCustomerReviews The number of customer reviews for the item.

Optional

Type: xs:int

ItemDimensions The dimensions of the item.

Optional

Type: ItemDimensions

InventoryRecommendation

A recommendation for restocking low or out-of-stock items in your inventory.

Operations

The InventoryRecommendation datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the InventoryRecommendation datatype:

Name Description
RecommendationId A unique recommendation identifier, in the format of {Category}-{RecommendationReason}-{ASIN}-{SKU}-{UPC}-{ItemName}. If any of these values are null, the value will be empty.

Type: xs:string

RecommendationReason A detailed description of the recommendation.

Type: xs:string

LastUpdated The date and time when the recommendation was generated or last updated. In ISO 8601 date time format.

Type: xs:dateTime

ItemIdentifier The ASIN, SKU, and UPC of the item.

Type: ProductIdentifier

ItemName The name of the item.

Optional

Type: xs:string

FulfillmentChannel FulfillmentChannel values:
  • MFN Indicates that you are fulfilling the item.
  • AFN Indicates that Amazon is fulfilling the item.

Optional

Type: xs:string

AvailableQuantity The total number of the items in your inventory.

Optional

Type: xs:int

DaysUntilStockRunsOut The estimated number of days until you run out of inventory of the item based on current sales.

Optional

Type: xs:int

DaysOutOfStockLast30Days The number of days in the last 30 days when you were out of stock of the item.

Optional

Type: xs:int

ItemDimensions

The dimensions of an item.

Operations

The ItemDimensions datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the ItemDimensions datatype:

Name Description
Height The height of the unit.

Type: DimensionMeasure

Width The width of the unit.

Type: DimensionMeasure

Length The length of the unit.

Type: DimensionMeasure

Weight The weight of the unit.

Type: WeightMeasure

Price

Currency type and amount.

Operations

The Price datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the Price datatype:

Name Description
CurrencyCode Three-digit currency code. In ISO 4217 format .

Type: xs:string

Amount The currency amount.

Type: xs:decimal

PricingRecommendation

A recommendation to review pricing on items in your inventory where your offer is not the lowest price.

Operations

The PricingRecommendation datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the PricingRecommendation datatype:

Name Description
RecommendationId A unique recommendation identifier, in the format of {Category}-{RecommendationReason}-{ASIN}-{SKU}-{UPC}-{ItemName}. If any of these values are null, the value will be empty.

Type: xs:string

RecommendationReason A detailed description of the recommendation.

Type: xs:string

LastUpdated The date and time when the recommendation was generated or last updated. In ISO 8601 date time format.

Type: xs:dateTime

ItemIdentifier The ASIN, SKU, and UPC of the item.

Type: ProductIdentifier

ItemName The name of the item.

Optional

Type: xs:string

Condition The condition of the item.

Optional

Type: xs:string

SubCondition The subcondition of the item.

Optional

Type: xs:string

FulfillmentChannel FulfillmentChannel values:
  • MFN Indicates that you are fulfilling the item.
  • AFN Indicates that Amazon is fulfilling the item.

Optional

Type: xs:string
YourPricePlusShipping The price that you have set for the item, including shipping.

Optional

Type: Price

LowestPricePlusShipping The lowest price for the item in the same Condition and SubCondition, including shipping.

Optional

Type: Price

PriceDifferenceToLowPrice The difference between what you are charging for the item and the lowest price for the item in the same Condition and SubCondition.

Optional

Type: Price

MedianPricePlusShipping The median price for the item in the same Condition and SubCondition, including shipping.

Optional

Type: Price

LowestMerchantFulfilledOfferPrice The lowest price for the item in the same Condition and SubCondition that is fulfilled by a seller.

Optional

Type: Price

LowestAmazonFulfilledOfferPrice The lowest price for the item in the same Condition and SubCondition that is fulfilled by Amazon.

Optional

Type: Price

NumberOfOffers The total number of offers for the item.

Optional

Type: xs:int

NumberOfMerchantFulfilledOffers The total number of offers for the item that are fulfilled by a seller.

Optional

Type: xs:int

NumberOfAmazonFulfilledOffers The total number of offers for the item that are fulfilled by Amazon.

Optional

Type: xs:int

ProductIdentifier

The ASIN, SKU, and UPC of the item.

Operations

The ProductIdentifier datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the ProductIdentifier datatype:

Name Description
Asin The ASIN of the item.

Type: xs:string

Sku The SKU of the item.

Type: xs:string

Upc The UPC of the item.

Type: xs:string

WeightMeasure

Weight unit and amount.

Operations

The WeightMeasure datatype is used in a response element of the following operations:

Datatype content

The following table shows the elements of the WeightMeasure datatype:

Name Description
Value The value of the measurement.

Type: xs:decimal

Unit The unit of the measurement.

Type: xs:string