Products

According to Amazon’s documentation:

The Products API section of Amazon Marketplace Web Service (Amazon MWS) helps you get information to match your products to existing product listings on Amazon Marketplace websites and to make sourcing and pricing decisions for listing those products on Amazon Marketplace websites. The Amazon MWS Products API returns product attributes, current Marketplace pricing information, and a variety of other product and listing information.

Using examples on this page

All examples below assume you have setup your Products API instance appropriately. Refer to Getting started for details:

from mws import Products

products_api = Products(
    access_key="...",
    secret_key="...",
    account_id="...",
    auth_token="...",
)

All request methods in the Products API also require a MarketplaceId to specify which marketplace the products are sold in. MarketplaceId values should match one of the values specified in Amazon documentation: Amazon MWS endpoints and MarkeplaceId values

python-amazon-mws makes these values available through the Marketplaces Enum, which contains both the endpoint and marketplace_id for each Amazon region via that region’s country code.

For convenience, a Marketplaces instance will return its MarketplaceId through the .value attribute, as well. Further, all request methods in python-amazon-mws will automatically “clean” Enum instances by returning their .value attributes.

The following are all valid methods for obtaining, for example, the MarketplaceId for the US region and passing it to a request method in the Products API:

from mws import Marketplaces

my_market = Marketplaces.US
# Returns the Enum instance for the US region.
# When used in a request method, the `marketplace_id` value will be used automatically.

print(my_market.marketplace_id)
# 'ATVPDKIKX0DER'
print(my_market.value)
# 'ATVPDKIKX0DER'
# (alias for `.marketplace_id`)

# You can also return the endpoint for that region, if needed:
print(my_market.endpoint)
# 'https://mws.amazonservices.com'

In all examples below, replace my_market with the Marketplaces Enum instance or MarketplaceId string value relevant to your region.

Products API reference

class mws.Products(access_key, secret_key, account_id, region='US', uri='', version='', auth_token='', proxy=None, user_agent_str='', headers=None, force_response_encoding=None)[source]

Amazon MWS Products API

MWS Docs: Products API Overview

list_matching_products(marketplace_id, query, context_id=None)[source]

Returns a list of products and their attributes, based on a search query.

MWS Docs: ListMatchingProducts

Examples:

  • Obtaining ASINs for products returned by the query "Python":

    resp = products_api.list_matching_products(
    marketplace_id=my_market,
    query="Python",
)

for product in resp.parsed.Products.Product:
    asin = product.Identifiers.MarketplaceASIN.ASIN
    print(f"ASIN: {asin}")

    Note

    As a shorthand, you may access the first product from the response using a list index:

    resp.parsed.Products.Product[0].Identifiers.MarketplaceASIN.ASIN

    Beware: if only one product is returned, this may result in an error, as the Product node will not be a list. Iterating nodes is generally safer to avoid this issue (see: DotDict Native Iteration).

  • Returning sales rank categories and rank numbers:

    for product in resp.parsed.Products.Product:
    for rank in product.SalesRankings.SalesRank:
        category_id = rank.ProductCategoryId
        sales_rank = rank.Rank
        print(f"Category: {category_id}, Rank: {sales_rank}")

  • Returning product titles:

    for product in resp.parsed.Products.Product:
    product_title = product.AttributeSets.ItemAttributes.Title
    print(f"Title: {product_title}")
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • query (str) –

  • context_id (Optional[str]) –

get_matching_product(marketplace_id, asins)[source]

Returns a list of products and their attributes, based on a list of ASIN values.

MWS Docs: GetMatchingProduct

Example

resp = products_api.get_matching_product(
    marketplace_id=my_market,
    asins=["B085G58KWT", "B07ZZW7QCM"],
)

# Iterate over products returned by the request
for product in resp.parsed.Product:
    # Access identifiers
    print(product.Identifiers.MarketplaceASIN.ASIN)
    print(product.Identifiers.MarketplaceASIN.MarketplaceId)

    # Attributes of the product, for instance a ListPrice (by amount and currency code):
    print(product.AttributeSets.ItemAttributes.ListPrice.Amount)
    print(product.AttributeSets.ItemAttributes.ListPrice.CurrencyCode)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • asins (Union[List[str], str]) –

get_matching_product_for_id(marketplace_id: str, type_: str, ids: Union[List[str], str])[source]

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

MWS Docs: GetMatchingProductForId

Example

resp = products_api.get_matching_product_for_id(
    marketplace_id=my_market,
    type_="ASIN",
    ids=["B085G58KWT", "B07ZZW7QCM"],
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • type_ (str) –

  • ids (Union[List[str], str]) –

get_competitive_pricing_for_sku(marketplace_id, skus)[source]

Returns the current competitive price of a product, based on SellerSKU.

MWS Docs: GetCompetitivePricingForSKU

Example

resp = products_api.get_competitive_pricing_for_sku(
    marketplace_id=my_market,
    skus=["OO-NL0F-795Z"],
)

for product in resp.parsed.Product:
    product.CompetitivePricing.NumberOfOfferListings
    product.CompetitivePricing.CompetitivePrices.CompetitivePrice.Price.LandedPrice.Amount
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • skus (Union[List[str], str]) –

get_competitive_pricing_for_asin(marketplace_id, asins)[source]

Returns the current competitive price of a product, based on ASIN.

MWS Docs: GetCompetitivePricingForASIN

Example

resp = products_api.get_competitive_pricing_for_asin(
    marketplace_id=my_market,
    asins=["B085G58KWT"],
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • asins (Union[List[str], str]) –

get_lowest_offer_listings_for_sku(marketplace_id, skus, condition='Any', exclude_me=False)[source]

Returns pricing information for the lowest-price active offer listings for up to 20 products, based on SellerSKU.

MWS Docs: GetLowestOfferListingsForSKU

Example

resp = products_api.get_lowest_offer_listings_for_sku(
    marketplace_id=my_market,
      skus=["OO-NL0F-795Z"],
      condition="New" # Any, New, Used, Collectible, Refurbished, Club. Default = Any
  )
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • skus (Union[List[str], str]) –

  • condition (str) –

  • exclude_me (bool) –

get_lowest_offer_listings_for_asin(marketplace_id, asins, condition='Any', exclude_me=False)[source]

Returns pricing information for the lowest-price active offer listings for up to 20 products, based on ASIN.

MWS Docs: GetLowestOfferListingsForASIN

Example

resp = products_api.get_lowest_offer_listings_for_asin(
    marketplace_id=my_market,
    asins=["B085G58KWT"],
    condition="New" # Any, New, Used, Collectible, Refurbished, Club. Default = Any
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • asins (Union[List[str], str]) –

  • condition (str) –

  • exclude_me (bool) –

get_lowest_priced_offers_for_sku(marketplace_id, sku, condition='New', exclude_me=False)[source]

Returns lowest priced offers for a single product, based on SellerSKU.

MWS Docs: GetLowestPricedOffersForSKU

Example

resp = products_api.get_lowest_priced_offers_for_sku(
    marketplace_id=my_market,
    skus=["OO-NL0F-795Z"],
    condition="New" # Any, New, Used, Collectible, Refurbished, Club. Default = Any
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • sku (str) –

  • condition (str) –

  • exclude_me (bool) –

get_lowest_priced_offers_for_asin(marketplace_id, asin, condition='New', exclude_me=False)[source]

Returns lowest priced offers for a single product, based on ASIN.

MWS Docs: GetLowestPricedOffersForASIN

Example

resp = products_api.get_lowest_priced_offers_for_asin(
    marketplace_id=my_market,
    asins=["B085G58KWT"],
    condition="New" # Any, New, Used, Collectible, Refurbished, Club. Default = Any
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • asin (str) –

  • condition (str) –

  • exclude_me (bool) –

get_my_fees_estimate(fees_estimate, *fees_estimates)[source]

Returns the estimated fees for a list of products.

MWS Docs: GetMyFeesEstimate

Accepts one or more FeesEstimateRequest instances as arguments:

Example

estimate_request = FeesEstimateRequest(...)
resp = products_api.get_my_fees_estimate(estimate_request)

Multiple estimates can be requested at the same time, as well:

estimate_request1 = FeesEstimateRequest(...)
estimate_request2 = FeesEstimateRequest(...)
resp = products_api.get_my_fees_estimate(estimate_request1, estimate_request2, ...)
Parameters

  • fees_estimate (mws.models.products.FeesEstimateRequest) –

  • fees_estimates (mws.models.products.FeesEstimateRequest) –

get_my_price_for_sku(marketplace_id, skus, condition=None)[source]

Returns pricing information for your own offer listings, based on SellerSKU.

MWS Docs: GetMyPriceForSKU

Example

  resp = products_api.get_my_price_for_sku(
    marketplace_id = my_market,
    skus="OO-NL0F-795Z",
    condition="New"
    # Any, New, Used, Collectible, Refurbished, Club. Default = All
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • skus (Union[List[str], str]) –

  • condition (Optional[str]) –

get_my_price_for_asin(marketplace_id, asins, condition=None)[source]

Returns pricing information for your own offer listings, based on ASIN.

MWS Docs: GetMyPriceForASIN

Example

resp = products_api.get_my_price_for_asin(
    marketplace_id=my_market,
    asins="B07QR73T66",
    condition="New"
    # Any, New, Used, Collectible, Refurbished, Club. Default = All
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • asins (Union[List[str], str]) –

  • condition (Optional[str]) –

get_product_categories_for_sku(marketplace_id, sku)[source]

Returns the parent product categories that a product belongs to, based on SellerSKU.

MWS Docs: GetProductCategoriesForSKU

Example

resp = products_api.get_product_categories_for_sku(
    marketplace_id=my_market,
    sku="OO-NL0F-795Z"
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • sku (str) –

get_product_categories_for_asin(marketplace_id, asin)[source]

Returns the parent product categories that a product belongs to, based on ASIN.

MWS Docs: GetProductCategoriesForASIN

Example

resp = products_api.get_product_categories_for_asin(
    marketplace_id=my_market,
    asin="B07QR73T66"
)
Parameters

  • marketplace_id (Union[mws.mws.Marketplaces, str]) –

  • asin (str) –

Data models

Several data models are attached to the Products API class, either from the class itself or an instance of it. These can be used as arguments for certain requests.

class mws.Products.FeesEstimateRequest(marketplace_id, id_type, id_value, price_to_estimate_fees, is_amazon_fulfilled, identifier)

A product, marketplace, and proposed price used to request estimated fees.

MWS Docs: FeesEstimateRequest

Instances of this model are required for the argument(s) of get_my_fees_estimate. Constructing an instance of this model requires the use of other data models in the Products API, as well.

Example

Note

In examples below, we use the Products class definition to locate our models:

from mws import Products
Products.MoneyType(...)

You can also access the same models from any instance of the Products class:

products_api = Products(...)
products_api.MoneyType(...)

  1. Start by creating MoneyType instances to account for different prices associated with the request, such as listing_price and shipping:

    my_price = Products.MoneyType(
    amount=123.45,
    currency_code=Products.CurrencyCode.GBP,
)
# Note the `currency_code` argument also accepts string literals of the currency code:
my_shipping = Products.MoneyType(amount=5.00, currency_code='GBP')

  2. Combine these prices into a PriceToEstimateFees instance:

    my_product_price = Products.PriceToEstimateFees(
    listing_price=my_price,
    shipping=my_shipping,
)

    For the JP market only, this price to estimate fees may optionally include Points.

  3. Use the PriceToEstimateFees instance along with other data to construct the final FeesEstimateRequest instance:

    estimate_request = Products.FeesEstimateRequest(
    marketplace_id=my_market,
    id_type="ASIN",  # either 'ASIN' or 'SKU', indicating the type of the `id_value` argument:
    id_value="B07QR73T66",
    price_to_estimate_fees=my_product_price,  # your `PriceToEstimateFees` instance
    is_amazon_fulfilled=False,
    identifier="request001",  # a unique identifier of your choosing
)
class mws.Products.PriceToEstimateFees(listing_price, shipping, points=None)

Price information for a product, used to estimate fees.

MWS Docs: PriceToEstimateFees

Accepts instances of MoneyType for its listing_price and shipping, and optionally accepts a Points instance to denote a points value (in JP region only).

class mws.Products.MoneyType(amount, currency_code)

An amount of money in a specified currency.

MWS Docs: MoneyType

Example

my_money = Products.MoneyType(
    amount=3.50,
    currency_code=Products.CurrencyCode.USD,
)
class mws.Products.Points(points_number, monetary_value)

The number of Amazon Points offered with the purchase of an item. The Amazon Points program is only available in Japan.

MWS Docs: Points

Points are expressed in terms of a points_number and a monetary_value for those points, the latter of which must be an instance of MoneyType.

Example:

# A monetary value of 2000 Japanese yen
monetary_value = Products.MoneyType(
    amount=2000.0,
    currency_code=Products.CurrencyCode.JPY,
)

# Now assign the points like so:
points = Products.Points(
    points_number=35,
    monetary_value=monetary_value,
)

When used in a request, points will be converted to a set of parameters like so:

print(points.to_params())
# {'PointsNumber': 35, 'PointsMonetaryValue.Amount': 2000.0, 'PointsMonetaryValue.CurrencyCode': <CurrencyCode.JPY: ('JPY', 'Japanese yen')>}

Note

You will see the PointsMonetaryValue.CurrencyCode element remains an instance of Enum at this stage. When used in a request, it is automatically “cleaned” to its parameterized value, 'JPY'.

Passing the string literal 'JPY' as the MoneyType.currency_code argument is also accepted.

Enums

Related Enums are also attached to the Products API class, and can be accessed the same way as Data models.

class mws.Products.CurrencyCode(value)

Bases: str, enum.Enum

Constants for currency codes supported by Amazon.

Example:

# 10 US dollars
listing_price = Products.MoneyType(
    amount=10.0,
    currency_code=Products.CurrencyCode.USD,
)
print(listing_price.to_params())
# {"Amount": 10.0, "CurrencyCode": "USD"}

# 30 Chinese yuan
shipping = Products.MoneyType(30.0, Products.CurrencyCode.RMB)
print(shipping.to_params())
# {"Amount": 30.0, "CurrencyCode": "RMB"}
USD = 'USD'

United States dollar

EUR = 'EUR'

European euro

GBP = 'GBP'

Great Britain pounds

RMB = 'RMB'

Chinese yuan

INR = 'INR'

Indian rupee

JPY = 'JPY'

Japanese yen

CAD = 'CAD'

Canadian dollar

MXN = 'MXN'

Mexican peso