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.
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.
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.
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.
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.
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(...)
Start by creating
MoneyType
instances to account for different prices associated with the request, such aslisting_price
andshipping
: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')
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
.Use the
PriceToEstimateFees
instance along with other data to construct the finalFeesEstimateRequest
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.
Accepts instances of
MoneyType
for itslisting_price
andshipping
, and optionally accepts aPoints
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.
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.
Points are expressed in terms of a
points_number
and amonetary_value
for those points, the latter of which must be an instance ofMoneyType
.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 theMoneyType.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
-