feat: add delivery_flags parameter to search_items

Author: sergioteula

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.3.0] - 2026-05-15
+
+### Added
+
+- `delivery_flags` parameter in `search_items` for `amazon_creatorsapi` and `amazon_creatorsapi.aio`
+
 ## [6.2.0] - 2026-03-12
 
 ### Added

amazon_creatorsapi/aio/api.py

@@ -29,6 +29,7 @@
     )
     raise ImportError(msg) from exc
 
+from creatorsapi_python_sdk.models.delivery_flag import DeliveryFlag
 from creatorsapi_python_sdk.models.get_browse_nodes_resource import (
     GetBrowseNodesResource,
 )
@@ -245,6 +246,7 @@ async def search_items(  # noqa: PLR0912, C901
         item_page: int | None = None,
         condition: Condition | None = None,
         currency_of_preference: str | None = None,
+        delivery_flags: list[DeliveryFlag] | None = None,
         languages_of_preference: list[str] | None = None,
         max_price: int | None = None,
         min_price: int | None = None,
@@ -271,6 +273,7 @@ async def search_items(  # noqa: PLR0912, C901
             item_page: Page of items to return (1-10). Defaults to 1.
             condition: Filter offers by condition type.
             currency_of_preference: ISO 4217 currency code for prices.
+            delivery_flags: Delivery programs to filter search results by.
             languages_of_preference: Languages in order of preference.
             max_price: Max price in lowest currency denomination.
             min_price: Min price in lowest currency denomination.
@@ -319,6 +322,8 @@ async def search_items(  # noqa: PLR0912, C901
             request_body["condition"] = condition.value
         if currency_of_preference is not None:
             request_body["currencyOfPreference"] = currency_of_preference
+        if delivery_flags is not None:
+            request_body["deliveryFlags"] = [flag.value for flag in delivery_flags]
         if languages_of_preference is not None:
             request_body["languagesOfPreference"] = languages_of_preference
         if max_price is not None:

amazon_creatorsapi/api.py

@@ -40,6 +40,7 @@
     from amazon_creatorsapi.core.marketplaces import CountryCode
     from creatorsapi_python_sdk.models.browse_node import BrowseNode
     from creatorsapi_python_sdk.models.condition import Condition
+    from creatorsapi_python_sdk.models.delivery_flag import DeliveryFlag
     from creatorsapi_python_sdk.models.item import Item
     from creatorsapi_python_sdk.models.search_result import SearchResult
     from creatorsapi_python_sdk.models.sort_by import SortBy
@@ -171,6 +172,7 @@ def search_items(
         item_page: int | None = None,
         condition: Condition | None = None,
         currency_of_preference: str | None = None,
+        delivery_flags: list[DeliveryFlag] | None = None,
         languages_of_preference: list[str] | None = None,
         max_price: int | None = None,
         min_price: int | None = None,
@@ -197,6 +199,7 @@ def search_items(
             item_page: Page of items to return (1-10). Defaults to 1.
             condition: Filter offers by condition type.
             currency_of_preference: ISO 4217 currency code for prices.
+            delivery_flags: Delivery programs to filter search results by.
             languages_of_preference: Languages in order of preference.
             max_price: Max price in lowest currency denomination.
             min_price: Min price in lowest currency denomination.
@@ -229,6 +232,7 @@ def search_items(
             itemPage=item_page,
             condition=condition,
             currencyOfPreference=currency_of_preference,
+            deliveryFlags=delivery_flags,
             languagesOfPreference=languages_of_preference,
             maxPrice=max_price,
             minPrice=min_price,

docs/conf.py

@@ -23,7 +23,7 @@
 author = "Sergio Abad"
 
 # The full version, including alpha/beta/rc tags
-release = "6.2.0"
+release = "6.3.0"
 
 
 # -- General configuration ---------------------------------------------------

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-amazon-paapi"
-version = "6.2.0"
+version = "6.3.0"
 description = "Amazon Product Advertising API 5.0 wrapper for Python"
 readme = "README.md"
 requires-python = ">=3.9"

tests/amazon_creatorsapi/aio/api_test.py

@@ -14,6 +14,7 @@
     TooManyRequestsError,
 )
 from creatorsapi_python_sdk.models.condition import Condition
+from creatorsapi_python_sdk.models.delivery_flag import DeliveryFlag
 from creatorsapi_python_sdk.models.get_browse_nodes_resource import (
     GetBrowseNodesResource,
 )
@@ -289,6 +290,53 @@ async def test_get_items_not_found(
             with self.assertRaises(ItemsNotFoundError):
                 await api.get_items(["B0DLFMFBJX"])
 
+
+class TestAsyncAmazonCreatorsApiSearchItemsDeliveryFlags(
+    unittest.IsolatedAsyncioTestCase,
+):
+    """Focused tests for delivery_flags in search_items()."""
+
+    @patch("amazon_creatorsapi.aio.api.AsyncOAuth2TokenManager")
+    @patch("amazon_creatorsapi.aio.api.AsyncHttpClient")
+    async def test_search_items_with_delivery_flags(
+        self,
+        mock_http_client_class: MagicMock,
+        mock_token_manager_class: MagicMock,
+    ) -> None:
+        """Test search_items includes delivery flags in the request body."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "searchResult": {"items": [{"asin": "B0DLFMFBJW"}]}
+        }
+
+        mock_client = AsyncMock()
+        mock_client.post.return_value = mock_response
+        mock_client.__aenter__.return_value = mock_client
+        mock_http_client_class.return_value = mock_client
+
+        mock_token_manager = AsyncMock()
+        mock_token_manager.get_token.return_value = "test_token"
+        mock_token_manager_class.return_value = mock_token_manager
+
+        async with AsyncAmazonCreatorsApi(
+            credential_id="test_id",
+            credential_secret="test_secret",
+            version="2.2",
+            tag="test-tag",
+            country="ES",
+            throttling=0,
+        ) as api:
+            await api.search_items(
+                keywords="laptop",
+                delivery_flags=[DeliveryFlag.PRIME, DeliveryFlag.FREESHIPPING],
+            )
+
+        call_args = mock_client.post.call_args
+        self.assertIn("deliveryFlags", str(call_args))
+        self.assertIn("Prime", str(call_args))
+        self.assertIn("FreeShipping", str(call_args))
+
     @patch("amazon_creatorsapi.aio.api.AsyncOAuth2TokenManager")
     @patch("amazon_creatorsapi.aio.api.AsyncHttpClient")
     async def test_get_items_with_optional_params(

tests/amazon_creatorsapi/api_test.py

@@ -17,6 +17,7 @@
     TooManyRequestsError,
 )
 from creatorsapi_python_sdk.exceptions import ApiException
+from creatorsapi_python_sdk.models.delivery_flag import DeliveryFlag
 from creatorsapi_python_sdk.models.get_browse_nodes_resource import (
     GetBrowseNodesResource,
 )
@@ -183,6 +184,41 @@ def test_search_items(
         self.assertIsNotNone(result)
         mock_api.search_items.assert_called_once()
 
+    @mock.patch("amazon_creatorsapi.api.DefaultApi")
+    @mock.patch("amazon_creatorsapi.api.ApiClient")
+    def test_search_items_with_delivery_flags(
+        self,
+        _mock_client_class: MagicMock,
+        mock_api_class: MagicMock,
+    ) -> None:
+        """Test search_items forwards delivery flags to the SDK request."""
+        mock_api = MagicMock()
+        mock_api_class.return_value = mock_api
+        mock_response = MagicMock()
+        mock_response.search_result = MagicMock()
+        mock_api.search_items.return_value = mock_response
+
+        api = AmazonCreatorsApi(
+            credential_id=self.credential_id,
+            credential_secret=self.credential_secret,
+            version=self.version,
+            tag=self.tag,
+            country=self.country,
+            throttling=0,
+        )
+
+        result = api.search_items(
+            keywords="laptop",
+            delivery_flags=[DeliveryFlag.PRIME, DeliveryFlag.FREESHIPPING],
+        )
+
+        self.assertIsNotNone(result)
+        request = mock_api.search_items.call_args.kwargs["search_items_request_content"]
+        self.assertEqual(
+            request.delivery_flags,
+            [DeliveryFlag.PRIME, DeliveryFlag.FREESHIPPING],
+        )
+
     @mock.patch("amazon_creatorsapi.api.DefaultApi")
     @mock.patch("amazon_creatorsapi.api.ApiClient")
     def test_get_items_no_results(