Registry / aws / python-amazon-sp-api

python-amazon-sp-api

JSON →
library2.1.22pypypi✓ verified 24d ago

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.

pip install python-amazon-sp-api
INSTALL
IMPORT
SIG · PYTHON-AMAZON-SP-A
P
python-amazon-sp-api
awspythonv2.1.22
Install
2.6s avg
Import
538ms
Disk
29MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.1.22 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.556s · 29.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.6s · import 0.520s · 31MB
29MB installed
● package 29MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Orders
from sp_api.api import Orders
Marketplaces
from sp_api.base import Marketplaces
SellingPartnerAPI
from sp_api.base import SellingPartnerAPI
from sp_api import SellingPartnerAPI
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`.
Client
from sp_api.base import Client
from sp_api import Client
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.

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.

import os from sp_api.api import Orders from sp_api.base import Marketplaces # It is highly recommended to set these as environment variables # for security and ease of management. REFRESH_TOKEN = os.environ.get('SP_API_REFRESH_TOKEN', 'YOUR_REFRESH_TOKEN_HERE') LWA_APP_ID = os.environ.get('SP_API_LWA_APP_ID', 'YOUR_LWA_APP_ID_HERE') LWA_CLIENT_SECRET = os.environ.get('SP_API_LWA_CLIENT_SECRET', 'YOUR_LWA_CLIENT_SECRET_HERE') AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID_HERE') AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY_HERE') IAM_ROLE_ARN = os.environ.get('SP_API_IAM_ROLE_ARN', 'YOUR_IAM_ROLE_ARN_HERE') # If using IAM try: client = Orders( refresh_token=REFRESH_TOKEN, lwa_app_id=LWA_APP_ID, lwa_client_secret=LWA_CLIENT_SECRET, aws_access_key_id=AWS_ACCESS_KEY_ID, aws_secret_access_key=AWS_SECRET_ACCESS_KEY, role_arn=IAM_ROLE_ARN, # Use role_arn if using IAM for AWS credentials marketplace=Marketplaces.US # Or specify your target marketplace ) # Example: Get orders created after a specific date response = client.get_orders(CreatedAfter='2023-01-01T00:00:00Z', MaxResultsPerPage=10) print("Successfully retrieved orders:") print(response.payload) except Exception as e: print(f"An error occurred: {e}") # Specific error handling for SP-API e.g., AuthorizationError, RateLimitError
Debug
Known issues
gotchaAmazon 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`.
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.
affects: All versions
gotchaThe 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.
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.
affects: All versions
gotchaAmazon 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.
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.
affects: All versions
breakingThe 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.
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`).
affects: All versions (due to upstream API changes)
Errors
Common errors & fixes
sp_api.base.exceptions.SellingApiBadRequestException: [{'code': 'InvalidInput', 'message': 'InvalidInput', 'details': ''}]
This error occurs when the request parameters are incorrect or missing required fields.
fix
Ensure all required parameters are included and correctly formatted in your request. Refer to the API documentation for the correct request structure.
sp_api.base.exceptions.SellingApiForbiddenException: [{'code': 'Unauthorized', 'message': 'Access to requested resource is denied.', 'details': ''}]
This error indicates that the credentials provided do not have the necessary permissions to access the requested resource.
fix
Verify that your IAM role has the appropriate policies attached and that the credentials are correctly configured.
sp_api.base.exceptions.SellingApiNotFoundException: [{'code': 'NotFound', 'message': 'The resource specified does not exist.', 'details': ''}]
This error occurs when the requested resource cannot be found, possibly due to an incorrect endpoint or identifier.
fix
Check the resource identifiers and ensure the endpoint URL is correct.
sp_api.base.exceptions.SellingApiRequestThrottledException: [{'code': 'QuotaExceeded', 'message': 'The frequency of requests was greater than allowed.', 'details': ''}]
This error indicates that the request rate has exceeded the allowed limit.
fix
Implement rate limiting in your application to stay within the allowed request limits.
sp_api.base.exceptions.SellingApiServerException: [{'code': 'InternalFailure', 'message': 'An unexpected condition occurred that prevented the server from fulfilling the request.', 'details': ''}]
This error signifies an internal server error on Amazon's side.
fix
Retry the request after some time. If the issue persists, contact Amazon support.
Upgrade
Version history
2.1.22latest on PyPI · released Aug 29, 2026
Audit
Dependencies
httpxrequiredCore HTTP client for making API requests.
typing-extensionsrequiredAdded in v2.1.8 for compatibility with newer Python type hinting features.
arrowrequiredUsed for date/time manipulation.
cachetoolsrequiredUsed for caching mechanisms.
xmltodictrequiredFor handling XML responses.
rsarequiredFor cryptographic operations, likely related to authentication or signature generation.
jsonpath-rwrequiredFor querying JSON structures.
Agent activity
49 hits · last 30 days
node
46
Resources
python-amazon-sp-api — pip install python-amazon-sp-api · libregistry