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

sp_api/asyncio/api/orders/orders.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import enum
+from typing import Any, Literal, overload
+
+from sp_api.asyncio.base import AsyncBaseClient
+from sp_api.base import ApiResponse, deprecated, fill_query_params, sp_endpoint
+from sp_api.util import normalize_csv_param
+
+from .orders_2026_01_01 import OrdersV20260101
+
+
+class OrdersVersion(str, enum.Enum):
+    V0 = "v0"  # legacy
+    V_2026_01_01 = "2026-01-01"
+    LATEST = "2026-01-01"
+
+
+class Orders(AsyncBaseClient):
+    """Orders API client (async).
+
+    This class implements the legacy Orders API **v0**.
+
+    If you pass version "2026-01-01" (or :class:`OrdersVersion.V_2026_01_01`)
+    to the constructor, :meth:`__new__` returns an instance of
+    :class:`~sp_api.asyncio.api.orders.orders_2026_01_01.OrdersV20260101` instead.
+
+    :link: https://github.com/amzn/selling-partner-api-docs/tree/main/references/orders-api
+    """
+
+    @overload
+    def __new__(
+        cls,
+        *args: Any,
+        version: Literal[OrdersVersion.V_2026_01_01, "2026-01-01"],
+        **kwargs: Any,
+    ) -> OrdersV20260101: ...
+
+    @overload
+    def __new__(
+        cls,
+        *args: Any,
+        version: str | OrdersVersion | None = None,
+        **kwargs: Any,
+    ) -> "Orders": ...
+
+    def __new__(
+        cls,
+        *args: Any,
+        version: str | OrdersVersion | None = None,
+        **kwargs: Any,
+    ):
+        if cls is Orders:
+            v = version if version is not None else kwargs.get("version")
+            if v in (OrdersVersion.V_2026_01_01, OrdersVersion.LATEST, "2026-01-01"):
+                kwargs.pop("version", None)
+                return OrdersV20260101(*args, **kwargs)
+        return super().__new__(cls)
+
+    @sp_endpoint("/orders/v0/orders")
+    async def get_orders(self, **kwargs) -> ApiResponse:
+        """
+        get_orders(self, **kwargs) -> ApiResponse
+        Returns orders created or updated during the time frame indicated by the specified parameters.
+        You can also apply a range of filtering criteria to narrow the list of orders returned.
+        If NextToken is present, that will be used to retrieve the orders instead of other criteria.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       1
+        ======================================  ==============
+
+
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+
+        Examples:
+            literal blocks::
+
+                Orders().get_orders(CreatedAfter='TEST_CASE_200', MarketplaceIds=["ATVPDKIKX0DER"])
+
+        Args:
+            key CreatedAfter: date
+            key CreatedBefore: date
+            key LastUpdatedAfter: date
+            key LastUpdatedBefore: date
+            key OrderStatuses: [str]
+            key MarketplaceIds: [str]
+            key FulfillmentChannels: [str]
+            key PaymentMethods: [str]
+            key BuyerEmail: str
+            key SellerOrderId: str
+            key MaxResultsPerPage: int
+            key EasyShipShipmentStatuses: [str]
+            key NextToken: str
+            key AmazonOrderIds: [str]
+            key RestrictedResources: [str]
+
+        Returns:
+            ApiResponse:
+
+
+        """
+        normalize_csv_param(kwargs, "OrderStatuses")
+        normalize_csv_param(kwargs, "MarketplaceIds")
+        normalize_csv_param(kwargs, "FulfillmentChannels")
+        normalize_csv_param(kwargs, "PaymentMethods")
+        normalize_csv_param(kwargs, "AmazonOrderIds")
+
+        if "RestrictedResources" in kwargs:
+            return self._access_restricted(kwargs)
+        return await self._request(kwargs.pop("path"), params={**kwargs})
+
+    @sp_endpoint("/orders/v0/orders/{}")
+    async def get_order(self, order_id: str, **kwargs) -> ApiResponse:
+        """
+        get_order(self, order_id: str, **kwargs) -> ApiResponse
+        Returns the order indicated by the specified order ID.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       1
+        ======================================  ==============
+
+
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+
+        Examples:
+            literal blocks::
+
+                Orders().get_order('TEST_CASE_200')
+
+        Args:
+            order_id: str
+            key RestrictedResources: [str]
+            **kwargs:
+
+        Returns:
+            ApiResponse:
+
+
+        """
+        if "RestrictedResources" in kwargs:
+            kwargs.update(
+                {"original_path": fill_query_params(kwargs.get("path"), order_id)}
+            )
+            return self._access_restricted(kwargs)
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id),
+            params={**kwargs},
+            add_marketplace=False,
+        )
+
+    @sp_endpoint("/orders/v0/orders/{}/orderItems")
+    async def get_order_items(self, order_id: str, **kwargs) -> ApiResponse:
+        """
+        get_order_items(self, order_id: str, **kwargs) -> ApiResponse
+
+        Returns detailed order item information for the order indicated by the specified order ID.
+        If NextToken is provided, it's used to retrieve the next page of order items.
+
+        Note: When an order is in the Pending state (the order has been placed but payment has not been authorized),
+        the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or
+        promotions for the order items in the order.
+        After an order leaves the Pending state (this occurs when payment has been authorized) and enters the Unshipped,
+        Partially Shipped, or Shipped state, the getOrderItems operation returns information about pricing, taxes,
+        shipping charges, gift status and promotions for the order items in the order.
+
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       1
+        ======================================  ==============
+
+
+
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+
+        Examples:
+            literal blocks::
+
+                Orders().get_order_items('TEST_CASE_200')
+
+        Args:
+            order_id: str
+            key RestrictedResources: [str]
+            **kwargs:
+
+        Returns:
+            ApiResponse:
+
+        """
+        if "RestrictedResources" in kwargs:
+            kwargs.update(
+                {"original_path": fill_query_params(kwargs.get("path"), order_id)}
+            )
+            return self._access_restricted(kwargs)
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id), params={**kwargs}
+        )
+
+    @sp_endpoint("/orders/v0/orders/{}/address")
+    async def get_order_address(self, order_id, **kwargs) -> ApiResponse:
+        """
+        get_order_address(self, order_id, **kwargs) -> ApiResponse
+
+        Returns the shipping address for the order indicated by the specified order ID.
+
+        :note: To get useful information from this method, you need to have access to PII.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       1
+        ======================================  ==============
+
+        Examples:
+            Orders().get_order_address('TEST_CASE_200')
+
+        Args:
+            order_id: str
+            **kwargs:
+
+        Returns:
+            ApiResponse
+        """
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id), params={**kwargs}
+        )
+
+    @sp_endpoint("/orders/v0/orders/{}/buyerInfo")
+    async def get_order_buyer_info(self, order_id: str, **kwargs) -> ApiResponse:
+        """
+        get_order_buyer_info(self, order_id: str, **kwargs) -> ApiResponse
+        Returns buyer information for the order indicated by the specified order ID.
+
+        :note: To get useful information from this method, you need to have access to PII.
+
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       1
+        ======================================  ==============
+
+
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+
+        Examples:
+            Orders().get_order_buyer_info('TEST_CASE_200')
+
+        Args:
+            order_id: str
+            **kwargs:
+
+        Returns:
+            GetOrderBuyerInfoResponse:
+
+        """
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id), params={**kwargs}
+        )
+
+    @sp_endpoint("/orders/v0/orders/{}/orderItems/buyerInfo")
+    async def get_order_items_buyer_info(self, order_id: str, **kwargs) -> ApiResponse:
+        """
+        get_order_items_buyer_info(self, order_id: str, **kwargs) -> ApiResponse
+
+        Returns buyer information in the order items of the order indicated by the specified order ID.
+
+        **Usage Plan:**
+
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        1                                       1
+        ======================================  ==============
+
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+
+        Examples:
+            literal blocks::
+
+                Orders().get_order_items_buyer_info('TEST_CASE_200')
+
+        Args:
+            order_id: str
+            key NextToken: str | retrieve data by next token
+
+        Returns:
+            ApiResponse
+        """
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id), params=kwargs
+        )
+
+    @sp_endpoint("/orders/v0/orders/{}/shipment", method="POST")
+    async def update_shipment_status(self, order_id: str, **kwargs) -> ApiResponse:
+        """
+        update_shipment_status(self, order_id: str, **kwargs) -> ApiResponse
+        Update the shipment status.
+        **Usage Plan:**
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        5                                       15
+        ======================================  ==============
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+        Examples:
+            literal blocks::
+                Orders().update_shipment_status(
+                    order_id='123-1234567-1234567',
+                    marketplaceId='ATVPDKIKX0DER',
+                    shipmentStatus='ReadyForPickup'
+                )
+        Args:
+            order_id: str
+        Returns:
+            ApiResponse
+        """
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id),
+            res_no_data=True,
+            data=kwargs,
+        )
+
+    @sp_endpoint("/orders/v0/orders/{}/shipmentConfirmation", method="POST")
+    async def confirm_shipment(self, order_id: str, **kwargs) -> ApiResponse:
+        """
+        confirm_shipment(self, order_id: str, **kwargs) -> ApiResponse
+        Updates the shipment confirmation status for a specified order.
+        **Usage Plan:**
+        ======================================  ==============
+        Rate (requests per second)               Burst
+        ======================================  ==============
+        2                                       10
+        ======================================  ==============
+        For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.
+        Examples:
+            literal blocks::
+                Orders().confirm_shipment(
+                    order_id='123-1234567-1234567',
+                    marketplaceId='ATVPDKIKX0DER',
+                    packageDetail={
+                        'packageReferenceId': '0001',
+                        'carrierCode': 'DHL',
+                        "shippingMethod": 'Paket',
+                        'trackingNumber': '1234567890',
+                        'shipDate': '2023-03-19T12:00:00Z',
+                        'orderItems': [
+                            {
+                                'orderItemId': '123456789',
+                                'quantity': 1
+                            },
+                            {
+                                'orderItemId': '2345678901',
+                                'quantity': 2
+                            },
+                        ]
+                    }
+                )
+        Args:
+            order_id: str
+        Returns:
+            ApiResponse
+        """
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id),
+            add_marketplace=False,
+            res_no_data=True,
+            data=kwargs,
+        )
+
+    @sp_endpoint("/tokens/2021-03-01/restrictedDataToken", method="POST")
+    async def _get_token(self, **kwargs):
+        data_elements = kwargs.pop("RestrictedResources")
+
+        restricted_resources = [
+            {
+                "method": "GET",
+                "path": kwargs.get("original_path"),
+                "dataElements": data_elements,
+            }
+        ]
+
+        return await self._request(
+            kwargs.pop("path"),
+            data={"restrictedResources": restricted_resources, **kwargs},
+        )
+
+    async def _access_restricted(self, kwargs):
+        if "original_path" not in kwargs:
+            kwargs.update({"original_path": kwargs["path"]})
+        token = self._get_token(**kwargs).payload
+        self.restricted_data_token = token["restrictedDataToken"]
+        r = await self._request(kwargs.pop("original_path"), params={**kwargs})
+        if not self.keep_restricted_data_token:
+            self.restricted_data_token = None
+        return r
+

sp_api/asyncio/api/orders/orders_2026_01_01.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sp_api.asyncio.base import AsyncBaseClient
+from sp_api.base import ApiResponse, fill_query_params, sp_endpoint
+from sp_api.util import normalize_csv_param
+
+
+class OrdersV20260101(AsyncBaseClient):
+    """Orders API (version 2026-01-01) - async client.
+
+    This is a newer Orders API version that uses different endpoints/parameters
+    than the legacy v0 Orders API implemented by :class:`sp_api.asyncio.api.orders.orders.Orders`.
+
+    Model source:
+    https://github.com/amzn/selling-partner-api-models/blob/main/models/orders-api-model/orders_2026-01-01.json
+    """
+
+    @sp_endpoint("/orders/2026-01-01/orders")
+    async def search_orders(self, **kwargs: Any) -> ApiResponse:
+        """Search orders (async)."""
+
+        normalize_csv_param(kwargs, "fulfillmentStatuses")
+        normalize_csv_param(kwargs, "marketplaceIds")
+        normalize_csv_param(kwargs, "fulfilledBy")
+        normalize_csv_param(kwargs, "includedData")
+
+        return await self._request(kwargs.pop("path"), params={**kwargs})
+
+    @sp_endpoint("/orders/2026-01-01/orders/{}")
+    async def get_order(self, order_id: str, **kwargs: Any) -> ApiResponse:
+        """Get order by orderId (async)."""
+
+        normalize_csv_param(kwargs, "includedData")
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), order_id),
+            params={**kwargs},
+            add_marketplace=False,
+        )

sp_api/asyncio/api/overrides/__init__.py

@@ -0,0 +1 @@
+

sp_api/asyncio/api/product_fees/product_fees.py

@@ -0,0 +1,194 @@
+from typing import List
+from urllib.parse import quote_plus
+
+from sp_api.base.helpers import sp_endpoint, fill_query_params
+from sp_api.base import ApiResponse
+from sp_api.asyncio.base import AsyncBaseClient
+from sp_api.util.product_fees import create_fees_body
+
+
+class ProductFees(AsyncBaseClient):
+    """
+    :link: https://github.com/amzn/selling-partner-api-docs/tree/main/references/product-fees-api
+    """
+
+    @sp_endpoint("/products/fees/v0/listings/{}/feesEstimate", method="POST")
+    async def get_product_fees_estimate_for_sku(
+        self,
+        seller_sku,
+        price: float,
+        shipping_price=None,
+        currency="USD",
+        is_fba=False,
+        points: dict = None,
+        marketplace_id: str = None,
+        optional_fulfillment_program: str = None,
+        force_safe_sku: bool = True,
+        **kwargs
+    ) -> ApiResponse:
+        """
+        get_product_fees_estimate_for_sku(self, seller_sku, price: float, shipping_price=None, currency='USD', is_fba=False, points: dict = dict, **kwargs) -> ApiResponse
+
+        Returns fees for sku
+
+        Examples:
+            literal blocks::
+
+                ProductFees().get_product_fees_estimate_for_sku("UmaS1", 10, currency='USD', shipping_price=10, is_fba=False,
+                                                          points={
+                                                              "PointsNumber": 0,
+                                                              "PointsMonetaryValue": {
+                                                                  "CurrencyCode": "USD",
+                                                                  "Amount": 0
+                                                              }
+                                                          })
+
+        Args:
+            seller_sku:
+            price:
+            shipping_price:
+            currency:
+            is_fba:
+            points:
+            marketplace_id: str | Defaults to self.marketplace_id
+            optional_fulfillment_program:
+            force_safe_sku: bool | Force user SKU quote
+            **kwargs:
+
+        Returns:
+            ApiResponse:
+
+        """
+
+        if force_safe_sku:
+            # handle `forward slash` issue in SKU
+            seller_sku = quote_plus(seller_sku)
+
+        kwargs.update(
+            create_fees_body(
+                price=price,
+                shipping_price=shipping_price,
+                currency=currency,
+                is_fba=is_fba,
+                identifier=seller_sku,
+                points=points,
+                marketplace_id=marketplace_id or self.marketplace_id,
+                optional_fulfillment_program=optional_fulfillment_program,
+            )
+        )
+        return await self._request(
+            fill_query_params(kwargs.pop("path"), seller_sku), data=kwargs
+        )
+
+    @sp_endpoint("/products/fees/v0/items/{}/feesEstimate", method="POST")
+    async def get_product_fees_estimate_for_asin(
+        self,
+        asin,
+        price: float,
+        currency="USD",
+        shipping_price=None,
+        is_fba=False,
+        points: dict = None,
+        marketplace_id: str = None,
+        optional_fulfillment_program: str = None,
+        **kwargs
+    ) -> ApiResponse:
+        """
+        get_product_fees_estimate_for_asin(self, asin, price: float, currency='USD', shipping_price=None, is_fba=False,  points: dict = dict, **kwargs) -> ApiResponse
+
+        Returns fees for asin
+
+        Examples:
+            literal blocks::
+
+                ProductFees().get_product_fees_estimate_for_asin("UmaS1", 10, currency='USD', shipping_price=10, is_fba=False,
+                                                           points={
+                                                               "PointsNumber": 0,
+                                                               "PointsMonetaryValue": {
+                                                                   "CurrencyCode": "USD",
+                                                                   "Amount": 0
+                                                               }
+                                                           })
+
+        Args:
+            asin:
+            price:
+            currency:
+            shipping_price:
+            is_fba:
+            points:
+            marketplace_id: str | Defaults to self.marketplace_id
+            optional_fulfillment_program:
+            **kwargs:
+
+        Returns:
+            ApiResponse:
+
+        """
+        kwargs.update(
+            create_fees_body(
+                price=price,
+                shipping_price=shipping_price,
+                currency=currency,
+                is_fba=is_fba,
+                identifier=asin,
+                points=points,
+                marketplace_id=marketplace_id or self.marketplace_id,
+                optional_fulfillment_program=optional_fulfillment_program,
+            )
+        )
+        return await self._request(fill_query_params(kwargs.pop("path"), asin), data=kwargs)
+
+    async def get_product_fees_estimate(self, estimate_requests: List[dict]) -> ApiResponse:
+        """
+        get_product_fees_estimate(self, estimate_requests: List[dict]) -> ApiResponse
+
+        Return fees for multiple products
+
+        Examples:
+            literal blocks::
+
+                ProductFees().get_product_fees_estimate(
+                        [
+                            dict(id_type='ASIN', id_value='B012345678', price=100),
+                            dict(id_type='ASIN', id_value='B012345678', price=50, is_fba=True),
+                        ]
+                    )
+
+
+        Args:
+            estimate_requests: list of dict where the allowed keys are :
+                id_type: str | ASIN or SellerSKU
+                id_value: str
+                price:
+                currency:
+                shipping_price:
+                is_fba:
+                points:
+                marketplace_id: str | Defaults to self.marketplace_id
+                optional_fulfillment_program:
+        """
+        data = []
+        for estimate in estimate_requests:
+            estimate_payload = dict(estimate)
+            marketplace_id = estimate_payload.pop("marketplace_id", None)
+            data.append(
+                dict(
+                    **create_fees_body(
+                        marketplace_id=marketplace_id or self.marketplace_id,
+                        **estimate_payload,
+                    )
+                )
+            )
+        return await self._request(
+            "/products/fees/v0/feesEstimate",
+            data=data,
+            params=dict(method="POST"),
+            wrap_list=True,
+        )
+
+    def _add_marketplaces(self, data):
+        # MarketplaceID is a property of the body's FeesEstimateRequest for this section, and does
+        # not need to be added. Additionally, Client._add_marketplaces will fail as it assumes
+        # data is a dict, which is not the case for get_product_fees_estimate.
+        pass