{"id":4725,"library":"python-amazon-sp-api","title":"Amazon Selling Partner API (SP-API) Python Client","description":"python-amazon-sp-api is a comprehensive Python wrapper for the Amazon Selling Partner API (SP-API). It provides a convenient way to interact with various Amazon SP-API endpoints for tasks such as order management, inventory, reports, and more. The library is actively maintained, with frequent updates to support new API versions and features. The current stable version is 2.1.8.","status":"active","version":"2.1.8","language":"en","source_language":"en","source_url":"https://github.com/saleweaver/python-amazon-sp-api","tags":["amazon","sp-api","ecommerce","seller-central","marketplace","api-client"],"install":[{"cmd":"pip install python-amazon-sp-api","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core HTTP client for making API requests.","package":"httpx","optional":false},{"reason":"Added in v2.1.8 for compatibility with newer Python type hinting features.","package":"typing-extensions","optional":false},{"reason":"Used for date/time manipulation.","package":"arrow","optional":false},{"reason":"Used for caching mechanisms.","package":"cachetools","optional":false},{"reason":"For handling XML responses.","package":"xmltodict","optional":false},{"reason":"For cryptographic operations, likely related to authentication or signature generation.","package":"rsa","optional":false},{"reason":"For querying JSON structures.","package":"jsonpath-rw","optional":false}],"imports":[{"symbol":"Orders","correct":"from sp_api.api import Orders"},{"symbol":"Marketplaces","correct":"from sp_api.base import Marketplaces"},{"note":"Pre-v2.1.7, some core classes might have been imported directly from `sp_api`. Since v2.1.7, symbols like `Client`, `AccessTokenClient`, `Credentials`, and `AuthorizationError` use dynamic import handling via `__getattr__` for optimization, but `SellingPartnerAPI` and `Marketplaces` remain in `sp_api.base`.","wrong":"from sp_api import SellingPartnerAPI","symbol":"SellingPartnerAPI","correct":"from sp_api.base import SellingPartnerAPI"},{"note":"While `Client` can be dynamically imported from `sp_api` root due to v2.1.7 changes, explicit import from `sp_api.base` is often clearer and aligns with how `SellingPartnerAPI` and `Marketplaces` are used.","wrong":"from sp_api import Client","symbol":"Client","correct":"from sp_api.base import Client"}],"quickstart":{"code":"import os\nfrom sp_api.api import Orders\nfrom sp_api.base import Marketplaces\n\n# It is highly recommended to set these as environment variables\n# for security and ease of management.\nREFRESH_TOKEN = os.environ.get('SP_API_REFRESH_TOKEN', 'YOUR_REFRESH_TOKEN_HERE')\nLWA_APP_ID = os.environ.get('SP_API_LWA_APP_ID', 'YOUR_LWA_APP_ID_HERE')\nLWA_CLIENT_SECRET = os.environ.get('SP_API_LWA_CLIENT_SECRET', 'YOUR_LWA_CLIENT_SECRET_HERE')\nAWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID_HERE')\nAWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY_HERE')\nIAM_ROLE_ARN = os.environ.get('SP_API_IAM_ROLE_ARN', 'YOUR_IAM_ROLE_ARN_HERE') # If using IAM\n\ntry:\n    client = Orders(\n        refresh_token=REFRESH_TOKEN,\n        lwa_app_id=LWA_APP_ID,\n        lwa_client_secret=LWA_CLIENT_SECRET,\n        aws_access_key_id=AWS_ACCESS_KEY_ID,\n        aws_secret_access_key=AWS_SECRET_ACCESS_KEY,\n        role_arn=IAM_ROLE_ARN, # Use role_arn if using IAM for AWS credentials\n        marketplace=Marketplaces.US # Or specify your target marketplace\n    )\n\n    # Example: Get orders created after a specific date\n    response = client.get_orders(CreatedAfter='2023-01-01T00:00:00Z', MaxResultsPerPage=10)\n    print(\"Successfully retrieved orders:\")\n    print(response.payload)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    # Specific error handling for SP-API e.g., AuthorizationError, RateLimitError\n","lang":"python","description":"This quickstart demonstrates how to initialize an `Orders` client, which is a common use case for the Amazon SP-API. It highlights the required authentication parameters (LWA credentials, AWS IAM role/keys) and shows how to make a basic API call to retrieve orders. Ensure your environment variables are correctly set for authentication."},"warnings":[{"fix":"Thoroughly review Amazon's documentation for creating an LWA app, linking it to your Seller Central account, and configuring an IAM role with the necessary SP-API permissions. Ensure `refresh_token`, `lwa_app_id`, `lwa_client_secret`, and either `role_arn` OR `aws_access_key_id`/`aws_secret_access_key` are correctly provided to the client.","message":"Amazon SP-API authentication is complex, requiring a combination of Login With Amazon (LWA) credentials and AWS IAM credentials (either IAM user keys or an IAM role ARN). Misconfiguration of any of these can lead to `AuthorizationError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement robust rate limiting and back-off strategies in your application. The library itself might offer some retry mechanisms, but external rate limiters (e.g., using `tenacity`) are often necessary for complex workflows. Monitor your API usage dashboard in Seller Central.","message":"The Amazon SP-API has strict rate limits that vary by operation and region. Hitting these limits frequently will result in `RateLimitError` or HTTP 429 responses, impacting your application's reliability.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always specify the correct `marketplace` parameter (e.g., `Marketplaces.US`, `Marketplaces.EU`, `Marketplaces.JP`) when initializing a client, ensuring it matches the region where your seller account and the desired data reside.","message":"Amazon SP-API endpoints are region-specific, and some operations or data may only be available in certain marketplaces. Providing the incorrect `Marketplace` enum value can lead to errors or unexpected results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly check the changelog for `python-amazon-sp-api` and Amazon's SP-API documentation. When upgrading the library, test your code thoroughly, especially if new API versions have been introduced for the services you use. Explicitly specify the API version if the client supports multiple versions for the same service (e.g., `OrdersV20260101Client`).","message":"The underlying Amazon SP-API frequently introduces new API versions (e.g., `OrdersV0` vs. `OrdersV20260101`). While `python-amazon-sp-api` strives to support these, migrating to newer API versions might require changes to method calls and parameter structures in your code.","severity":"breaking","affected_versions":"All versions (due to upstream API changes)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}