python-amazon-sp-api 1.9.60__py3-none-any.whl → 2.0.2__py3-none-any.whl

sp_api/asyncio/api/products/products.py

@@ -0,0 +1,405 @@
+from typing import Optional, List, Dict, Union
+
+from sp_api.base import ApiResponse, Client, fill_query_params, sp_endpoint
+from sp_api.asyncio.base import AsyncBaseClient
+from sp_api.api.products.products_definitions import (
+    GetCompetitiveSummaryBatch,
+    GetFeaturedOfferExpectedPriceBatch,
+    GetItemOffersBatchRequest,
+    GetListingOffersBatchRequest,
+)
+from sp_api.util import ensure_csv
+
+
+class Products(AsyncBaseClient):
+    """
+    :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")
+    async 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.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                      1
+        ======================================  ==============
+
+        Examples:
+            literal blocks::
+
+                Products().get_product_pricing_for_skus(['sku', 'sku1'], MarketplaceId="ATVPDKIKX0DER")
+
+        Args:
+            seller_sku_list: [str]
+            item_condition: str ("New", "Used", "Collectible", "Refurbished", "Club")
+            offer_type: str ("B2C" or "B2B") Default is B2C.
+            **kwargs:
+
+        Returns:
+            ApiResponse:
+        """
+        if item_condition is not None:
+            kwargs["ItemCondition"] = item_condition
+        if offer_type is not None:
+            kwargs["OfferType"] = offer_type
+
+        return self._create_get_pricing_request(seller_sku_list, "Sku", **kwargs)
+
+    @sp_endpoint("/products/pricing/v0/price", method="GET")
+    async 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.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                      1
+        ======================================  ==============
+
+        Examples:
+            literal blocks::
+
+                Products().get_product_pricing_for_asins(['asin1', 'asin2'], MarketplaceId="ATVPDKIKX0DER")
+
+        Args:
+            asin_list: [str]
+            item_condition: str | ("New", "Used", "Collectible", "Refurbished", "Club") Filters the offer listings based on item condition. Possible values: New, Used, Collectible, Refurbished, Club. Available values : New, Used, Collectible, Refurbished, Club
+            offer_type: str ("B2C" or "B2B") Default is B2C.
+        Returns:
+            ApiResponse
+        """
+        if item_condition is not None:
+            kwargs["ItemCondition"] = item_condition
+        if offer_type is not None:
+            kwargs["OfferType"] = offer_type
+
+        return self._create_get_pricing_request(asin_list, "Asin", **kwargs)
+
+    @sp_endpoint("/products/pricing/v0/competitivePrice", method="GET")
+    async 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
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                      1
+        ======================================  ==============
+
+        Examples:
+            literal blocks::
+
+                Products().get_competitive_pricing_for_skus([], MarketplaceId="ATVPDKIKX0DER")
+
+        Args:
+            seller_sku_list: [str]
+            customer_type: Optional (query) str ("Consumer" or "Business") Indicates whether to request pricing information from the point of view of Consumer or Business buyers. Default is Consumer.
+
+        Returns:
+            ApiResponse
+        """
+
+        if customer_type is not None:
+            kwargs["CustomerType"] = customer_type
+
+        return self._create_get_pricing_request(seller_sku_list, "Sku", **kwargs)
+
+    @sp_endpoint("/products/pricing/v0/competitivePrice", method="GET")
+    async 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
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                      1
+        ======================================  ==============
+
+        Examples:
+            literal blocks::
+
+                Products().get_competitive_pricing_for_asins([], MarketplaceId="ATVPDKIKX0DER")
+
+        Args:
+            asin_list: [str]
+            customer_type: Optional (query) str ("Consumer" or "Business") Indicates whether to request pricing information from the point of view of Consumer or Business buyers. Default is Consumer.
+
+        Returns:
+            ApiResponse
+
+        """
+        if customer_type is not None:
+            kwargs["CustomerType"] = customer_type
+
+        return self._create_get_pricing_request(asin_list, "Asin", **kwargs)
+
+    @sp_endpoint("/products/pricing/v0/listings/{}/offers", method="GET")
+    async 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
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       2
+        ======================================  ==============
+
+        Args:
+            key MarketplaceId: Required (query) str
+            item_condition: Required (query) str | ("New", "Used", "Collectible", "Refurbished", "Club") Filters the offer listings based on item condition. Possible values: New, Used, Collectible, Refurbished, Club. Available values : New, Used, Collectible, Refurbished, Club
+            seller_sku: Required (path) str
+            customer_type: Optional (query) str ("Consumer" or "Business") Indicates whether to request pricing information from the point of view of Consumer or Business buyers. Default is Consumer.
+
+
+        Returns:
+            ApiResponse
+
+        """
+        kwargs["ItemCondition"] = item_condition
+
+        if customer_type is not None:
+            kwargs["CustomerType"] = customer_type
+
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), seller_sku), params={**kwargs}
+        )
+
+    @sp_endpoint("/products/pricing/v0/items/{}/offers", method="GET")
+    async 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
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                      1
+        ======================================  ==============
+
+        Args:
+            key MarketplaceId: Required (query) str
+            item_condition: Required (query) str | ("New", "Used", "Collectible", "Refurbished", "Club") Filters the offer listings based on item condition. Possible values: New, Used, Collectible, Refurbished, Club. Available values : New, Used, Collectible, Refurbished, Club
+            asin: Required (path) str
+            customer_type: Optional (query) str ("Consumer" or "Business") Indicates whether to request pricing information from the point of view of Consumer or Business buyers. Default is Consumer.
+
+
+        Returns:
+            ApiResponse
+
+        """
+        kwargs["ItemCondition"] = item_condition
+
+        if customer_type is not None:
+            kwargs["CustomerType"] = customer_type
+
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), asin), params={**kwargs}
+        )
+
+    @sp_endpoint("/batches/products/pricing/v0/itemOffers", method="POST")
+    async 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.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                       1
+        ======================================  ==============
+
+        Args:
+            requests_: Optional (Body) [dict] The request associated with the getItemOffersBatch API call.
+
+
+        Returns:
+            ApiResponse
+
+        """
+        if isinstance(requests_, GetItemOffersBatchRequest):
+            get_item_offers_batch_request = requests_.to_dict()
+        else:
+            get_item_offers_batch_request = {"requests": requests_}
+
+        return await 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")
+    async 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.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        .5                                       1
+        ======================================  ==============
+
+        Args:
+            requests_: Optional (Body) [dict] The request associated with the getListingOffersBatch API call.
+
+
+        Returns:
+            ApiResponse
+
+        """
+        if isinstance(requests_, GetListingOffersBatchRequest):
+            get_listing_offers_batch_request = requests_.to_dict()
+        else:
+            get_listing_offers_batch_request = {"requests": requests_}
+
+        return await self._request(
+            kwargs.pop("path"),
+            data=get_listing_offers_batch_request,
+            params={**kwargs},
+            add_marketplace=False,
+        )
+
+    @sp_endpoint('/batches/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice', method='POST')
+    async 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 await 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')
+    async 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 await self._request(
+            kwargs.pop('path'),
+            data=get_competitive_summary_batch_request,
+            params={**kwargs},
+            add_marketplace=False
+        )
+
+    async def _create_get_pricing_request(self, item_list, item_type, **kwargs):
+        items_csv = ensure_csv(item_list)
+        return await 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/asyncio/api/products/products_definitions.py

@@ -0,0 +1,170 @@
+from sp_api.asyncio.base import AsyncBaseClient
+from enum import Enum
+from typing import Optional, List, Dict, Union
+from dataclasses import dataclass, asdict
+
+
+class CompetitiveSummaryIncludedData(Enum):
+    FEATURED_BUYING_OPTIONS = "featuredBuyingOptions"
+    LOWEST_PRICED_OFFERS = "lowestPricedOffers"
+    REFERENCE_PRICES = "referencePrices"
+
+
+@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
+
+
+@dataclass
+class FeaturedOfferExpectedPriceRequest:
+    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v2022-05-01-reference
+        #FeaturedOfferExpectedPriceRequest """
+    marketplaceId: str
+    sku: str
+    uri: str = "/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice"
+    method: str = "GET"
+
+
+@dataclass
+class GetFeaturedOfferExpectedPriceBatch:
+    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v2022-05-01-reference
+        #getFeaturedOfferExpectedPriceBatch """
+    requests: Optional[List[Union[FeaturedOfferExpectedPriceRequest, 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[FeaturedOfferExpectedPriceRequest]:
+        parsed_requests = []
+
+        for request in requests:
+            if isinstance(request, Dict):
+                request = FeaturedOfferExpectedPriceRequest(**request)
+
+            if not isinstance(request, FeaturedOfferExpectedPriceRequest):
+                raise TypeError
+
+            parsed_requests.append(request)
+
+        return parsed_requests
+
+
+@dataclass
+class CompetitiveSummaryRequest:
+    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v2022-05-01-reference
+        #FeaturedOfferExpectedPriceRequest """
+    marketplaceId: str
+    asin: str
+    includedData: List[CompetitiveSummaryIncludedData]
+    uri: str = "/products/pricing/2022-05-01/items/competitiveSummary"
+    method: str = "GET"
+
+
+@dataclass
+class GetCompetitiveSummaryBatch:
+    """ Implements definition: https://developer-docs.amazon.com/sp-api/docs/product-pricing-api-v2022-05-01-reference
+        #getCompetitiveSummary """
+    requests: Optional[List[Union[CompetitiveSummaryRequest, 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[CompetitiveSummaryRequest]:
+        parsed_requests = []
+
+        for request in requests:
+            if isinstance(request, Dict):
+                request = CompetitiveSummaryRequest(**request)
+
+            if not isinstance(request, CompetitiveSummaryRequest):
+                raise TypeError
+
+            parsed_requests.append(request)
+
+        return parsed_requests