python-amazon-sp-api 1.7.5__py3-none-any.whl → 2.0.10__py3-none-any.whl

sp_api/api/products/products.py

@@ -1,16 +1,26 @@
 from typing import Optional, List, Dict, Union
 
 from sp_api.base import ApiResponse, Client, fill_query_params, sp_endpoint
-from sp_api.api.products.products_definitions import GetItemOffersBatchRequest, GetListingOffersBatchRequest
+from sp_api.api.products.products_definitions import (
+    GetCompetitiveSummaryBatch,
+    GetFeaturedOfferExpectedPriceBatch,
+    GetItemOffersBatchRequest,
+    GetListingOffersBatchRequest,
+)
+from sp_api.util import ensure_csv
 
 
 class Products(Client):
     """
-    :link: https://github.com/amzn/selling-partner-api-docs/blob/main/references/product-pricing-api/productPricingV0.md
+    :links:
+        https://github.com/amzn/selling-partner-api-docs/blob/main/references/product-pricing-api/productPricingV0.md
+        https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v2022-05-01-reference
     """
 
-    @sp_endpoint('/products/pricing/v0/price', method='GET')
-    def get_product_pricing_for_skus(self, seller_sku_list: [str], item_condition=None, offer_type=None, **kwargs) -> ApiResponse:
+    @sp_endpoint("/products/pricing/v0/price", method="GET")
+    def get_product_pricing_for_skus(
+        self, seller_sku_list: [str], item_condition=None, offer_type=None, **kwargs
+    ) -> ApiResponse:
         """
         get_product_pricing_for_skus(self, seller_sku_list: [str], item_condition: str = None, **kwargs) -> ApiResponse
         Returns pricing information for a seller's offer listings based on SKU.
@@ -38,14 +48,16 @@ class Products(Client):
             ApiResponse:
         """
         if item_condition is not None:
-            kwargs['ItemCondition'] = item_condition
+            kwargs["ItemCondition"] = item_condition
         if offer_type is not None:
-            kwargs['OfferType'] = offer_type
+            kwargs["OfferType"] = offer_type
 
-        return self._create_get_pricing_request(seller_sku_list, 'Sku', **kwargs)
+        return self._create_get_pricing_request(seller_sku_list, "Sku", **kwargs)
 
-    @sp_endpoint('/products/pricing/v0/price', method='GET')
-    def get_product_pricing_for_asins(self, asin_list: [str], item_condition=None, offer_type=None, **kwargs) -> ApiResponse:
+    @sp_endpoint("/products/pricing/v0/price", method="GET")
+    def get_product_pricing_for_asins(
+        self, asin_list: [str], item_condition=None, offer_type=None, **kwargs
+    ) -> ApiResponse:
         """
         get_product_pricing_for_asins(self, asin_list: [str], item_condition=None, **kwargs) -> ApiResponse
         Returns pricing information for a seller's offer listings based on ASIN.
@@ -71,14 +83,16 @@ class Products(Client):
             ApiResponse
         """
         if item_condition is not None:
-            kwargs['ItemCondition'] = item_condition
+            kwargs["ItemCondition"] = item_condition
         if offer_type is not None:
-            kwargs['OfferType'] = offer_type
+            kwargs["OfferType"] = offer_type
 
-        return self._create_get_pricing_request(asin_list, 'Asin', **kwargs)
+        return self._create_get_pricing_request(asin_list, "Asin", **kwargs)
 
-    @sp_endpoint('/products/pricing/v0/competitivePrice', method='GET')
-    def get_competitive_pricing_for_skus(self, seller_sku_list: [str], customer_type=None, **kwargs) -> ApiResponse:
+    @sp_endpoint("/products/pricing/v0/competitivePrice", method="GET")
+    def get_competitive_pricing_for_skus(
+        self, seller_sku_list: [str], customer_type=None, **kwargs
+    ) -> ApiResponse:
         """
         get_competitive_pricing_for_skus(self, seller_sku_list, **kwargs) -> ApiResponse
         Returns competitive pricing information for a seller's offer listings based on Seller Sku
@@ -105,12 +119,14 @@ class Products(Client):
         """
 
         if customer_type is not None:
-            kwargs['CustomerType'] = customer_type
+            kwargs["CustomerType"] = customer_type
 
-        return self._create_get_pricing_request(seller_sku_list, 'Sku', **kwargs)
+        return self._create_get_pricing_request(seller_sku_list, "Sku", **kwargs)
 
-    @sp_endpoint('/products/pricing/v0/competitivePrice', method='GET')
-    def get_competitive_pricing_for_asins(self, asin_list: [str], customer_type=None, **kwargs) -> ApiResponse:
+    @sp_endpoint("/products/pricing/v0/competitivePrice", method="GET")
+    def get_competitive_pricing_for_asins(
+        self, asin_list: [str], customer_type=None, **kwargs
+    ) -> ApiResponse:
         """
         get_competitive_pricing_for_asins(self, asin_list, **kwargs) -> ApiResponse
         Returns competitive pricing information for a seller's offer listings based on ASIN
@@ -137,12 +153,14 @@ class Products(Client):
 
         """
         if customer_type is not None:
-            kwargs['CustomerType'] = customer_type
+            kwargs["CustomerType"] = customer_type
 
-        return self._create_get_pricing_request(asin_list, 'Asin', **kwargs)
+        return self._create_get_pricing_request(asin_list, "Asin", **kwargs)
 
-    @sp_endpoint('/products/pricing/v0/listings/{}/offers', method='GET')
-    def get_listings_offer(self, seller_sku: str, item_condition: str, customer_type: str = None, **kwargs) -> ApiResponse:
+    @sp_endpoint("/products/pricing/v0/listings/{}/offers", method="GET")
+    def get_listings_offer(
+        self, seller_sku: str, item_condition: str, customer_type: str = None, **kwargs
+    ) -> ApiResponse:
         """
         get_listings_offer(self, seller_sku: str, **kwargs) -> ApiResponse
         Returns the lowest priced offers for a single SKU listing
@@ -166,15 +184,19 @@ class Products(Client):
             ApiResponse
 
         """
-        kwargs['ItemCondition'] = item_condition
+        kwargs["ItemCondition"] = item_condition
 
         if customer_type is not None:
-            kwargs['CustomerType'] = customer_type
+            kwargs["CustomerType"] = customer_type
 
-        return self._request(fill_query_params(kwargs.pop('path'), seller_sku), params={**kwargs})       
+        return self._request(
+            fill_query_params(kwargs.pop("path"), seller_sku), params={**kwargs}
+        )
 
-    @sp_endpoint('/products/pricing/v0/items/{}/offers', method='GET')
-    def get_item_offers(self, asin: str, item_condition: str, customer_type: str = None, **kwargs) -> ApiResponse:
+    @sp_endpoint("/products/pricing/v0/items/{}/offers", method="GET")
+    def get_item_offers(
+        self, asin: str, item_condition: str, customer_type: str = None, **kwargs
+    ) -> ApiResponse:
         """
         get_item_offers(self, asin: str, **kwargs) -> ApiResponse
         Returns the lowest priced offers for a single item based on ASIN
@@ -198,16 +220,21 @@ class Products(Client):
             ApiResponse
 
         """
-        kwargs['ItemCondition'] = item_condition
+        kwargs["ItemCondition"] = item_condition
 
         if customer_type is not None:
-            kwargs['CustomerType'] = customer_type
-
-        return self._request(fill_query_params(kwargs.pop('path'), asin), params={**kwargs})
-
-    @sp_endpoint('/batches/products/pricing/v0/itemOffers', method='POST')
-    def get_item_offers_batch(self, requests_: Optional[Union[List[Dict], GetItemOffersBatchRequest]] = None,
-                              **kwargs) -> ApiResponse:
+            kwargs["CustomerType"] = customer_type
+
+        return self._request(
+            fill_query_params(kwargs.pop("path"), asin), params={**kwargs}
+        )
+
+    @sp_endpoint("/batches/products/pricing/v0/itemOffers", method="POST")
+    def get_item_offers_batch(
+        self,
+        requests_: Optional[Union[List[Dict], GetItemOffersBatchRequest]] = None,
+        **kwargs,
+    ) -> ApiResponse:
         """
         get_item_offers_batch(self, requests_: Optional[List[Union[Dict, ItemOffersRequest]]], **kwargs) -> ApiResponse
         Returns the lowest priced offers for a batch of items based on ASIN.
@@ -233,11 +260,19 @@ class Products(Client):
         else:
             get_item_offers_batch_request = {"requests": requests_}
 
-        return self._request(kwargs.pop('path'), data=get_item_offers_batch_request, params={**kwargs},
-                             add_marketplace=False)
-
-    @sp_endpoint('/batches/products/pricing/v0/listingOffers', method='POST')
-    def get_listing_offers_batch(self, requests_: Optional[Union[List[Dict], GetListingOffersBatchRequest]] = None, **kwargs) -> ApiResponse:
+        return self._request(
+            kwargs.pop("path"),
+            data=get_item_offers_batch_request,
+            params={**kwargs},
+            add_marketplace=False,
+        )
+
+    @sp_endpoint("/batches/products/pricing/v0/listingOffers", method="POST")
+    def get_listing_offers_batch(
+        self,
+        requests_: Optional[Union[List[Dict], GetListingOffersBatchRequest]] = None,
+        **kwargs,
+    ) -> ApiResponse:
         """
         get_listing_offers_batch(self, requests_: Optional[Union[List[Dict], GetListingOffersBatchRequest]], **kwargs) -> ApiResponse
         Returns the lowest priced offers for a batch of listings based on ASIN.
@@ -263,18 +298,107 @@ class Products(Client):
         else:
             get_listing_offers_batch_request = {"requests": requests_}
 
-        return self._request(kwargs.pop('path'), data=get_listing_offers_batch_request, params={**kwargs},
-                             add_marketplace=False)
+        return self._request(
+            kwargs.pop("path"),
+            data=get_listing_offers_batch_request,
+            params={**kwargs},
+            add_marketplace=False,
+        )
 
-    def _create_get_pricing_request(self, item_list, item_type, **kwargs):
-        return self._request(kwargs.pop('path'),
-                             params={**{f"{item_type}s": ','.join(item_list)},
-                                     'ItemType': item_type,
-                                     **({'ItemCondition': kwargs.pop(
-                                         'ItemCondition')} if 'ItemCondition' in kwargs else {}),
-                                     **({'CustomerType': kwargs.pop(
-                                         'CustomerType')} if 'CustomerType' in kwargs else {}),
-                                     **({'OfferType': kwargs.pop(
-                                         'OfferType')} if 'OfferType' in kwargs else {}),
-                                     'MarketplaceId': kwargs.get('MarketplaceId', self.marketplace_id)})
+    @sp_endpoint('/batches/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice', method='POST')
+    def get_featured_offer_expected_price_batch(self, requests_: Optional[
+        Union[List[Dict], GetFeaturedOfferExpectedPriceBatch]], **kwargs) -> ApiResponse:
+        """
+        get_featured_offer_expected_price_batch(self, **kwargs) -> ApiResponse
+
+        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 may change, and different offers may be featured based on other factors, including fulfillment
+        capabilities to a specific customer. The response to an unsuccessful request includes the available error text.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .033                                    1
+        ======================================  ==============
+
+        Args:
+            requests_: [dict] The request associated with the getFeaturedOfferExpectedPriceBatch API call.
+
+        Returns:
+            ApiResponse:
+        """
+        if isinstance(requests_, GetFeaturedOfferExpectedPriceBatch):
+            get_featured_offer_expected_price_batch_request = requests_.to_dict()
+        else:
+            get_featured_offer_expected_price_batch_request = {"requests": requests_}
 
+        return self._request(
+            kwargs.pop('path'),
+            data=get_featured_offer_expected_price_batch_request,
+            params={**kwargs},
+            add_marketplace=False
+        )
+
+    @sp_endpoint('/batches/products/pricing/2022-05-01/items/competitiveSummary', method='POST')
+    def get_competitive_summary_batch(self, requests_: Optional[Union[List[Dict], GetCompetitiveSummaryBatch]], **kwargs) -> ApiResponse:
+        """
+        get_competitive_summary(self, **kwargs) -> ApiResponse
+
+        Returns the competitive summary response including featured buying options for the ASIN and `marketplaceId` combination.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .033                                    1
+        ======================================  ==============
+
+        Args:
+            requests_: The request associated with the getCompetitiveSummary API call.
+
+        Returns:
+            ApiResponse:
+        """
+        if isinstance(requests_, GetCompetitiveSummaryBatch):
+            get_competitive_summary_batch_request = requests_.to_dict()
+        else:
+            get_competitive_summary_batch_request = {"requests": requests_}
+
+        return self._request(
+            kwargs.pop('path'),
+            data=get_competitive_summary_batch_request,
+            params={**kwargs},
+            add_marketplace=False
+        )
+
+    def _create_get_pricing_request(self, item_list, item_type, **kwargs):
+        items_csv = ensure_csv(item_list)
+        return self._request(
+            kwargs.pop("path"),
+            params={
+                **{f"{item_type}s": items_csv},
+                "ItemType": item_type,
+                **(
+                    {"ItemCondition": kwargs.pop("ItemCondition")}
+                    if "ItemCondition" in kwargs
+                    else {}
+                ),
+                **(
+                    {"CustomerType": kwargs.pop("CustomerType")}
+                    if "CustomerType" in kwargs
+                    else {}
+                ),
+                **(
+                    {"OfferType": kwargs.pop("OfferType")}
+                    if "OfferType" in kwargs
+                    else {}
+                ),
+                "MarketplaceId": kwargs.get("MarketplaceId", self.marketplace_id),
+            },
+        )

sp_api/api/products/products_definitions.py

@@ -1,82 +1,11 @@
-from typing import Optional, List, Dict, Union
-from dataclasses import dataclass, asdict
-
-
-@dataclass
-class ItemOffersRequest:
-    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v0-reference
-    #itemoffersrequest """
-    uri: str
-    method: str
-    MarketplaceId: str
-    ItemCondition: str = None
-    CustomerType: str = None
-    headers: Dict = None
-
-
-@dataclass
-class GetItemOffersBatchRequest:
-    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v0-reference
-    #getitemoffersbatchrequest """
-    requests: Optional[List[Union[ItemOffersRequest, Dict]]] = None
-
-    def __post_init__(self):
-        self.requests = self.parse_requests(self.requests)
-
-    def to_dict(self):
-        return asdict(self)
-
-    @staticmethod
-    def parse_requests(requests) -> List[ItemOffersRequest]:
-        parsed_requestes = []
-
-        for request in requests:
-            if isinstance(request, Dict):
-                request = ItemOffersRequest(**request)
-
-            if not isinstance(request, ItemOffersRequest):
-                raise TypeError
-
-            parsed_requestes.append(request)
-
-        return parsed_requestes
-    
-
-@dataclass
-class ListingOffersRequest:
-    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v0-reference
-    #listingoffersrequest """
-    uri: str
-    MarketplaceId: str
-    ItemCondition: str
-    method: str = "GET"
-    CustomerType: str = "Consumer"
-
-
-@dataclass
-class GetListingOffersBatchRequest:
-    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v0-reference
-    #getlistingoffersbatchrequest """
-    requests: Optional[List[Union[ListingOffersRequest, Dict]]] = None
-
-    def __post_init__(self):
-        self.requests = self.parse_requests(self.requests)
-
-    def to_dict(self):
-        return asdict(self)
-
-    @staticmethod
-    def parse_requests(requests) -> List[ListingOffersRequest]:
-        parsed_requestes = []
-
-        for request in requests:
-            if isinstance(request, Dict):
-                request = ListingOffersRequest(**request)
-
-            if not isinstance(request, ListingOffersRequest):
-                raise TypeError
-
-            parsed_requestes.append(request)
-
-        return parsed_requestes
-
+from sp_api.util.products_definitions import (
+    CompetitiveSummaryIncludedData,
+    ItemOffersRequest,
+    GetItemOffersBatchRequest,
+    ListingOffersRequest,
+    GetListingOffersBatchRequest,
+    FeaturedOfferExpectedPriceRequest,
+    GetFeaturedOfferExpectedPriceBatch,
+    CompetitiveSummaryRequest,
+    GetCompetitiveSummaryBatch,
+)

sp_api/api/replenishment/replenishment.py

@@ -6,19 +6,21 @@ from sp_api.base import Client, sp_endpoint, fill_query_params, ApiResponse
 class Replenishment(Client):
     """
     Replenishment SP-API Client
-    :link: 
+    :link:
 
     The Selling Partner API for Replenishment (Replenishment API) provides programmatic access to replenishment program metrics and offers. These programs provide recurring delivery of any replenishable item at a frequency chosen by the customer.
 
     The Replenishment API is available worldwide wherever Amazon Subscribe & Save is available or is supported. The API is available to vendors and FBA selling partners.
     """
 
-    @sp_endpoint('/replenishment/2022-11-07/sellingPartners/metrics/search', method='POST')
+    @sp_endpoint(
+        "/replenishment/2022-11-07/sellingPartners/metrics/search", method="POST"
+    )
     def get_selling_partner_metrics(self, **kwargs) -> ApiResponse:
         """
         get_selling_partner_metrics(self, **kwargs) -> ApiResponse
 
-        Returns aggregated replenishment program metrics for a selling partner. 
+        Returns aggregated replenishment program metrics for a selling partner.
 
         **Usage Plan:**
 
@@ -29,7 +31,7 @@ class Replenishment(Client):
         The `x-amzn-RateLimit-Limit` response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see [Usage Plans and Rate Limits in the Selling Partner API](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits-in-the-sp-api).
 
         Args:
-        
+
             body: |  {'description': 'The request body for the `getSellingPartnerMetrics` operation.',
                      'properties': {'aggregationFrequency': {'$ref': '#/definitions/AggregationFrequency'},
                                     'marketplaceId': {'$ref': '#/definitions/MarketplaceId',
@@ -51,9 +53,9 @@ class Replenishment(Client):
             ApiResponse:
         """
 
-        return self._request(kwargs.pop('path'), data=kwargs)
+        return self._request(kwargs.pop("path"), data=kwargs)
 
-    @sp_endpoint('/replenishment/2022-11-07/offers/metrics/search', method='POST')
+    @sp_endpoint("/replenishment/2022-11-07/offers/metrics/search", method="POST")
     def list_offer_metrics(self, **kwargs) -> ApiResponse:
         """
         list_offer_metrics(self, **kwargs) -> ApiResponse
@@ -69,7 +71,7 @@ class Replenishment(Client):
         The `x-amzn-RateLimit-Limit` response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see [Usage Plans and Rate Limits in the Selling Partner API](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits-in-the-sp-api).
 
         Args:
-        
+
             body: |  {'description': 'The request body for the `listOfferMetrics` operation.',
                      'properties': {'filters': {'$ref': '#/definitions/ListOfferMetricsRequestFilters',
                                                 'description': 'Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array.'},
@@ -83,9 +85,9 @@ class Replenishment(Client):
             ApiResponse:
         """
 
-        return self._request(kwargs.pop('path'), data=kwargs)
+        return self._request(kwargs.pop("path"), data=kwargs)
 
-    @sp_endpoint('/replenishment/2022-11-07/offers/search', method='POST')
+    @sp_endpoint("/replenishment/2022-11-07/offers/search", method="POST")
     def list_offers(self, **kwargs) -> ApiResponse:
         """
         list_offers(self, **kwargs) -> ApiResponse
@@ -101,7 +103,7 @@ class Replenishment(Client):
         The `x-amzn-RateLimit-Limit` response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see [Usage Plans and Rate Limits in the Selling Partner API](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits-in-the-sp-api).
 
         Args:
-        
+
             body: |  {'description': 'The request body for the `listOffers` operation.',
                      'properties': {'filters': {'$ref': '#/definitions/ListOffersRequestFilters',
                                                 'description': 'Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array.'},
@@ -115,4 +117,4 @@ class Replenishment(Client):
             ApiResponse:
         """
 
-        return self._request(kwargs.pop('path'), data=kwargs)
+        return self._request(kwargs.pop("path"), data=kwargs)