Amazon Selling Partner API (SP-API) Python Client

2.1.8 · active · verified Sun Apr 12

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.

Warnings

gotcha 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`.
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.
gotcha 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.
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.
gotcha 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.
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.
breaking 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.
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`).

Install

pip install python-amazon-sp-api Install stable version

Imports

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

Quickstart

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

view raw JSON →