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

GetMatchingProductForId

Returns a list of products and their attributes, based on a list of ASIN, GCID, SellerSKU, UPC, EAN, ISBN, and JAN values.

Description

The GetMatchingProductForId operation returns a list of products and their attributes, based on a list of product identifier values that you specify. Possible product identifiers are ASIN, GCID, SellerSKU, UPC, EAN, ISBN, and JAN.

Restrictions

  • The operation only returns product information if an active offer exists when IdType input is GCID, UPC, EAN, ISBN, or JAN.
  • The operation always returns product information if IdType input is ASIN.
  • The operation always returns product information when IdType input is SellerSKU and the seller has not deleted the offer. The offer can be inactive or active, but must exist.

Availability

This operation is available in all marketplaces.

Throttling

Maximum request quota Restore rate Hourly request quota
20 requests Five items every second 18000 requests per hour
Operations in the Products API section that send lists of items as input parameters have restore rates that are measured by item. For information on per-item throttling, see Throttling in the Products API. For definitions of throttling terminology and for a complete explanation of throttling, see Throttling: Limits to how often you can submit requests in the Amazon MWS Developer Guide.

Request parameters

For more information about the request parameters that are required for all Amazon MWS operations, see Required request parameters in the Amazon MWS Developer Guide.

Name Description Required Valid values
MarketplaceId An encrypted, Amazon-defined marketplace identifier. Yes Type: MarketplaceType
IdType The type of product identifier that Id values refer to. Yes IdType values: ASIN, GCID, SellerSKU, UPC, EAN, ISBN, JAN

Type: xs:string

IdList A structured list of Id values. Used to identify products in the given marketplace. Yes Maximum: Five Id values

Type: List of xs:string

Response elements

The response elements that the GetMatchingProductForId operation returns are described by the following publicly available XSDs:

GetMatchingProductForId returns Invalid UPC identifier when an external identifier is given (UPC, ISBN, etc.) and no offers/listings are active on Amazon MWS. See Restrictions for additional information.

The following table provides additional information about some of the key elements that are returned by the GetMatchingProductForId operation.

Note: As Amazon updates the Amazon MWS Products API section to include new response elements, we may update the ProductsAPI_Response.xsd and default.xsd schemas. Keep this in mind if you choose to use these schemas for validation.
Name Description
Product Contains four of the sub-elements of the Product element from ProductsAPI_Response.xsd. These sub-elements are: Identifiers, AttributeSets, Relationships, and SalesRankings.
Identifiers Contains the MarketplaceASIN combination that uniquely identifies a product.
AttributeSets Contains product attributes, from the ItemAttributes element of default.xsd, if they are applicable to the product that is returned. Note that a Product response element will have multiple attribute sets if it has attributes in more than one language. All of the attributes, even ones that are not translated, are repeated in each attribute set. The language used by each attribute set is denoted by a lang attribute.
Note: If a single product has more than one image, then only the URL for the main image is returned.
Relationships Contains product variation information, if applicable. If your search criteria match a product that is identified by a variation parent ASIN, the related VariationChild elements are contained in the Relationships element. If your search criteria match a specific variation child ASIN, the related VariationParent element is contained in the Relationships element.
Note: Because this operation does not return all product attributes, it is possible to get VariationChild elements with different ASIN values but the same variation element values. These are distinct variation child ASINs even though product attributes that differentiate them from each other are not returned.

Variation attributes can be found in the VariationChild element of default.xsd.

Note: Variation attributes are not included in the VariationChild element if the input ASIN values have more than 2000 combined VariationChild elements.
SalesRankings Sales rank information for the product by product category.

Sub-elements are:

  • ProductCategoryId. Identifies the product category that the sales rank is taken from.
  • Rank. The sales rank of the product within the product category.

Examples

Example query request

For information about standard request requirements, see Required request parameters.

Show example code Hide example code

POST /Products/2011-10-01 HTTP/1.1
Content-Type: x-www-form-urlencoded
Host: mws.amazonservices.com
User-Agent: <Your User Agent Header>

AWSAccessKeyId=AKIAEXAMPLEFWR4TJ7ZQ
&Action=GetMatchingProductForId
&IdList.Id.1=9781933988665
&IdList.Id.2=0439708184
&IdType=ISBN
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&MarketplaceId=ATVPDKIKX0DER
&SellerId=A1IMEXAMPLEWRC
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-12-04T21%3A09%3A02Z
&Version=2011-10-01
&Signature=ZhhdEXAMPLEiTy6k5etzw%2BIOCvbDrGop5u9EXAMPLE8%3D

↑ Top

Example response

For information about standard response formatting, see Response format.

Show example code Hide example code

<?xml version="1.0"?>
<GetMatchingProductForIdResponse
    xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01">
    <GetMatchingProductForIdResult Id="9781933988665"
        IdType="ISBN"
        status="Success">
        <Products xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01"
            xmlns:ns2="http://mws.amazonservices.com/schema/Products/2011-10-01/default.xsd">
            <Product>
                <Identifiers>
                    <MarketplaceASIN>
                        <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
                        <ASIN>1933988665</ASIN>
                    </MarketplaceASIN>
                </Identifiers>
                <AttributeSets>
                    <ns2:ItemAttributes xml:lang="en-US">
                        <ns2:Author>Marmanis, Haralambos</ns2:Author>
                        <ns2:Author>Babenko, Dmitry</ns2:Author>
                        <ns2:Binding>Paperback</ns2:Binding>
                        <ns2:Edition>1</ns2:Edition>
                        <ns2:ItemDimensions>
                            <ns2:Height Units="inches">9.17</ns2:Height>
                            <ns2:Length Units="inches">7.36</ns2:Length>
                            <ns2:Width Units="inches">0.75</ns2:Width>
                            <ns2:Weight Units="pounds">1.40</ns2:Weight>
                        </ns2:ItemDimensions>
                        <ns2:IsEligibleForTradeIn>true</ns2:IsEligibleForTradeIn>
                        <ns2:Label>Manning Publications</ns2:Label>
                        <ns2:Languages>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Unknown</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Original Language</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Published</ns2:Type>
                            </ns2:Language>
                        </ns2:Languages>
                        <ns2:ListPrice>
                            <ns2:Amount>44.99</ns2:Amount>
                            <ns2:CurrencyCode>USD</ns2:CurrencyCode>
                        </ns2:ListPrice>
                        <ns2:Manufacturer>Manning Publications</ns2:Manufacturer>
                        <ns2:NumberOfItems>1</ns2:NumberOfItems>
                        <ns2:NumberOfPages>368</ns2:NumberOfPages>
                        <ns2:PackageDimensions>
                            <ns2:Height Units="inches">0.80</ns2:Height>
                            <ns2:Length Units="inches">9.10</ns2:Length>
                            <ns2:Width Units="inches">7.30</ns2:Width>
                            <ns2:Weight Units="pounds">1.35</ns2:Weight>
                        </ns2:PackageDimensions>
                        <ns2:ProductGroup>Book</ns2:ProductGroup>
                        <ns2:ProductTypeName>ABIS_BOOK</ns2:ProductTypeName>
                        <ns2:PublicationDate>2009-07-05</ns2:PublicationDate>
                        <ns2:Publisher>Manning Publications</ns2:Publisher>
                        <ns2:SmallImage>
                            <ns2:URL>
                                http://ecx.images-amazon.com/images/I/51EEz05N2HL._SL75_.jpg
                            </ns2:URL>
                            <ns2:Height Units="pixels">75</ns2:Height>
                            <ns2:Width Units="pixels">60</ns2:Width>
                        </ns2:SmallImage>
                        <ns2:Studio>Manning Publications</ns2:Studio>
                        <ns2:Title>Algorithms of the Intelligent Web</ns2:Title>
                    </ns2:ItemAttributes>
                </AttributeSets>
                <Relationships/>
                <SalesRankings>
                    <SalesRank>
                        <ProductCategoryId>book_display_on_website</ProductCategoryId>
                        <Rank>59485</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>377886011</ProductCategoryId>
                        <Rank>32</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3887</ProductCategoryId>
                        <Rank>66</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3870</ProductCategoryId>
                        <Rank>82</Rank>
                    </SalesRank>
                </SalesRankings>
            </Product>
        </Products>
    </GetMatchingProductForIdResult>
    <GetMatchingProductForIdResult Id="0439708184" IdType="ISBN" status="Success">
        <Products xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01"
            xmlns:ns2="http://mws.amazonservices.com/schema/Products/2011-10-01/default.xsd">
            <Product>
                <Identifiers>
                    <MarketplaceASIN>
                        <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
                        <ASIN>059035342X</ASIN>
                    </MarketplaceASIN>
                </Identifiers>
                <AttributeSets>
                    <ns2:ItemAttributes xml:lang="en-US">
                        <ns2:Author>Rowling, J.K.</ns2:Author>
                        <ns2:Binding>Paperback</ns2:Binding>
                        <ns2:Brand>Scholastic Press</ns2:Brand>
                        <ns2:Creator Role="Illustrator">GrandPré, Mary</ns2:Creator>
                        <ns2:Edition>1st</ns2:Edition>
                        <ns2:Feature>Recommended Age: 9 years and up</ns2:Feature>
                        <ns2:ItemDimensions>
                            <ns2:Height Units="inches">0.80</ns2:Height>
                            <ns2:Length Units="inches">7.50</ns2:Length>
                            <ns2:Width Units="inches">5.20</ns2:Width>
                            <ns2:Weight Units="pounds">0.50</ns2:Weight>
                        </ns2:ItemDimensions>
                        <ns2:IsAutographed>false</ns2:IsAutographed>
                        <ns2:IsMemorabilia>false</ns2:IsMemorabilia>
                        <ns2:Label>Scholastic Paperbacks</ns2:Label>
                        <ns2:Languages>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Unknown</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Original Language</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Published</ns2:Type>
                            </ns2:Language>
                        </ns2:Languages>
                        <ns2:ListPrice>
                            <ns2:Amount>10.99</ns2:Amount>
                            <ns2:CurrencyCode>USD</ns2:CurrencyCode>
                        </ns2:ListPrice>
                        <ns2:Manufacturer>Scholastic Paperbacks</ns2:Manufacturer>
                        <ns2:NumberOfItems>1</ns2:NumberOfItems>
                        <ns2:NumberOfPages>320</ns2:NumberOfPages>
                        <ns2:PackageDimensions>
                            <ns2:Height Units="inches">1.00</ns2:Height>
                            <ns2:Length Units="inches">7.50</ns2:Length>
                            <ns2:Width Units="inches">5.20</ns2:Width>
                            <ns2:Weight Units="pounds">0.50</ns2:Weight>
                        </ns2:PackageDimensions>
                        <ns2:PackageQuantity>1</ns2:PackageQuantity>
                        <ns2:PartNumber>9780590353427</ns2:PartNumber>
                        <ns2:ProductGroup>Book</ns2:ProductGroup>
                        <ns2:ProductTypeName>ABIS_BOOK</ns2:ProductTypeName>
                        <ns2:PublicationDate>1999-10-01</ns2:PublicationDate>
                        <ns2:Publisher>Scholastic Paperbacks</ns2:Publisher>
                        <ns2:ReleaseDate>1999-09-08</ns2:ReleaseDate>
                        <ns2:SmallImage>
                            <ns2:URL>
                                http://ecx.images-amazon.com/images/I/51MU5VilKpL._SL75_.jpg
                            </ns2:URL>
                            <ns2:Height Units="pixels">75</ns2:Height>
                            <ns2:Width Units="pixels">51</ns2:Width>
                        </ns2:SmallImage>
                        <ns2:Studio>Scholastic Paperbacks</ns2:Studio>
                        <ns2:Title>Harry Potter and the Sorcerer's Stone (Book 1)</ns2:Title>
                    </ns2:ItemAttributes>
                </AttributeSets>
                <Relationships/>
                <SalesRankings>
                    <SalesRank>
                        <ProductCategoryId>book_display_on_website</ProductCategoryId>
                        <Rank>362</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>15356791</ProductCategoryId>
                        <Rank>6</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3153</ProductCategoryId>
                        <Rank>9</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3045</ProductCategoryId>
                        <Rank>14</Rank>
                    </SalesRank>
                </SalesRankings>
            </Product>
            <Product>
                <Identifiers>
                    <MarketplaceASIN>
                        <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
                        <ASIN>0439708184</ASIN>
                    </MarketplaceASIN>
                </Identifiers>
                <AttributeSets>
                    <ns2:ItemAttributes xml:lang="en-US">
                        <ns2:Author>J.K. Rowling, Mary GrandPré</ns2:Author>
                        <ns2:Binding>Paperback</ns2:Binding>
                        <ns2:Label>Scholastic Paperbacks</ns2:Label>
                        <ns2:Languages>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Unknown</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Published</ns2:Type>
                            </ns2:Language>
                        </ns2:Languages>
                        <ns2:Manufacturer>Scholastic Paperbacks</ns2:Manufacturer>
                        <ns2:NumberOfItems>1</ns2:NumberOfItems>
                        <ns2:NumberOfPages>784</ns2:NumberOfPages>
                        <ns2:PackageDimensions>
                            <ns2:Height Units="inches">0.73</ns2:Height>
                            <ns2:Length Units="inches">8.43</ns2:Length>
                            <ns2:Width Units="inches">5.85</ns2:Width>
                            <ns2:Weight Units="pounds">0.79</ns2:Weight>
                        </ns2:PackageDimensions>
                        <ns2:ProductGroup>Book</ns2:ProductGroup>
                        <ns2:ProductTypeName>BOOKS_1973_AND_LATER</ns2:ProductTypeName>
                        <ns2:PublicationDate>1999-09-08</ns2:PublicationDate>
                        <ns2:Publisher>Scholastic Paperbacks</ns2:Publisher>
                        <ns2:SmallImage>
                            <ns2:URL>
                                http://ecx.images-amazon.com/images/I/51STfI7UiCL._SL75_.jpg
                            </ns2:URL>
                            <ns2:Height Units="pixels">75</ns2:Height>
                            <ns2:Width Units="pixels">52</ns2:Width>
                        </ns2:SmallImage>
                        <ns2:Studio>Scholastic Paperbacks</ns2:Studio>
                        <ns2:Title>Harry Potter and the Sorcerer's Stone</ns2:Title>
                    </ns2:ItemAttributes>
                </AttributeSets>
                <Relationships/>
                <SalesRankings>
                    <SalesRank>
                        <ProductCategoryId>book_display_on_website</ProductCategoryId>
                        <Rank>2091024</Rank>
                    </SalesRank>
                </SalesRankings>
            </Product>
        </Products>
    </GetMatchingProductForIdResult>
    <ResponseMetadata>
        <RequestId>7ba3245e-a213-430a-bea9-EXAMPLE38d76</RequestId>
    </ResponseMetadata>
</GetMatchingProductForIdResponse>

↑ Top

Example response with error

For information about standard response formatting, see Response format.

When you include multiple Id values in one request, it is possible to have a successful response (HTTP status code 200) that may contain errors for individual Id values.

Show example code Hide example code

<?xml version="1.0"?>
<GetMatchingProductForIdResponse xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01">
    <GetMatchingProductForIdResult Id="0439708623" IdType="ISBN" status="ClientError">
        <Error>
            <Type>Sender</Type>
            <Code>InvalidParameterValue</Code>
            <Message>Invalid ISBN identifier 0439708623 for marketplace ATVPDKIKX0DER</Message>
        </Error>
    </GetMatchingProductForIdResult>
    <GetMatchingProductForIdResult Id="9781933988665" IdType="ISBN" status="Success">
        <Products xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01" xmlns:ns2="http://mws.amazonservices.com/schema/Products/2011-10-01/default.xsd">
            <Product>
                <Identifiers>
                    <MarketplaceASIN>
                        <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
                        <ASIN>1933988665</ASIN>
                    </MarketplaceASIN>
                </Identifiers>
                <AttributeSets>
                    <ns2:ItemAttributes xml:lang="en-US">
                        <ns2:Author>Marmanis, Haralambos</ns2:Author>
                        <ns2:Author>Babenko, Dmitry</ns2:Author>
                        <ns2:Binding>Paperback</ns2:Binding>
                        <ns2:Brand>Marmanis, Haralambos/ Babenko, Dmitry</ns2:Brand>
                        <ns2:Edition>1</ns2:Edition>
                        <ns2:ItemDimensions>
                            <ns2:Height Units="inches">9.25</ns2:Height>
                            <ns2:Length Units="inches">7.38</ns2:Length>
                            <ns2:Width Units="inches">0.73</ns2:Width>
                            <ns2:Weight Units="pounds">1.38</ns2:Weight>
                        </ns2:ItemDimensions>
                        <ns2:Label>Manning Publications</ns2:Label>
                        <ns2:Languages>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Published</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Original Language</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Unknown</ns2:Type>
                            </ns2:Language>
                        </ns2:Languages>
                        <ns2:ListPrice>
                            <ns2:Amount>44.99</ns2:Amount>
                            <ns2:CurrencyCode>USD</ns2:CurrencyCode>
                        </ns2:ListPrice>
                        <ns2:Manufacturer>Manning Publications</ns2:Manufacturer>
                        <ns2:NumberOfItems>1</ns2:NumberOfItems>
                        <ns2:NumberOfPages>368</ns2:NumberOfPages>
                        <ns2:PackageDimensions>
                            <ns2:Height Units="inches">0.80</ns2:Height>
                            <ns2:Length Units="inches">9.10</ns2:Length>
                            <ns2:Width Units="inches">7.30</ns2:Width>
                            <ns2:Weight Units="pounds">1.35</ns2:Weight>
                        </ns2:PackageDimensions>
                        <ns2:PackageQuantity>1</ns2:PackageQuantity>
                        <ns2:PartNumber>9781933988665</ns2:PartNumber>
                        <ns2:ProductGroup>Book</ns2:ProductGroup>
                        <ns2:ProductTypeName>ABIS_BOOK</ns2:ProductTypeName>
                        <ns2:PublicationDate>2009-07-08</ns2:PublicationDate>
                        <ns2:Publisher>Manning Publications</ns2:Publisher>
                        <ns2:SmallImage>
                            <ns2:URL>http://ecx.images-amazon.com/images/I/51EEz05N2HL._SL75_.jpg</ns2:URL>
                            <ns2:Height Units="pixels">75</ns2:Height>
                            <ns2:Width Units="pixels">60</ns2:Width>
                        </ns2:SmallImage>
                        <ns2:Studio>Manning Publications</ns2:Studio>
                        <ns2:Title>Algorithms of the Intelligent Web</ns2:Title>
                    </ns2:ItemAttributes>
                </AttributeSets>
                <Relationships/>
                <SalesRankings>
                    <SalesRank>
                        <ProductCategoryId>book_display_on_website</ProductCategoryId>
                        <Rank>689405</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>491298</ProductCategoryId>
                        <Rank>150</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3870</ProductCategoryId>
                        <Rank>375</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3887</ProductCategoryId>
                        <Rank>836</Rank>
                    </SalesRank>
                </SalesRankings>
            </Product>
        </Products>
    </GetMatchingProductForIdResult>
    <ResponseMetadata>
        <RequestId>a34b6cca-d7dc-4939-b226-b13ea3ac1d88</RequestId>
    </ResponseMetadata>
</GetMatchingProductForIdResponse>

↑ Top

Related topics