python-amazon-paapi

In version 7, errors are mapped directly from the Creators API response. While except RequestError still catches 401 (AuthenticationError) and 403 (AccessDeniedError), a 400 error that previously raised RequestError now raises InvalidArgumentError.

To catch all library-specific errors, catch AmazonCreatorsApiError. Note that error messages now include specific details from Amazon, such as the rejected fields and request identifier, so any logic relying on exact error message text should be reviewed.

from amazon_creatorsapi.errors import AmazonCreatorsApiError

try:
    items = api.get_items(["B01N5IB20Q"])
except AmazonCreatorsApiError as error:  # Catches every error of the library
    print(error)

In version 7, every client instance maintains its own configuration. Global configuration via Configuration.set_default() is no longer supported.

To point the client to a different server (e.g., for testing against a mock server), use the host argument. To use a specific authentication endpoint (useful for using unsupported API versions), use the auth_endpoint argument.

# Use a custom host for testing
api = AmazonCreatorsApi(..., host="http://localhost:8080")

# Use a specific auth endpoint for a specific version
api = AmazonCreatorsApi(
    ...,
    version="2.4",
    auth_endpoint="https://creatorsapi.auth.eu-west-1.amazoncognito.com/oauth2/token",
)

The search_items method now requires at least one search criterion. A request containing only filters will raise an InvalidArgumentError. You must include at least one of the following: keywords, actor, artist, author, brand, title, browse_node_id, or search_index.

# This will raise InvalidArgumentError
api.search_items(min_price=1000) 

# This is correct
api.search_items(keywords="laptop", min_price=1000) 

To use the library, initialize the AmazonCreatorsApi client with your Amazon Associates Creators API credentials. You can then use the client to fetch product information using ASINs.

Required parameters for AmazonCreatorsApi:

• credential_id: Your Creators API credential ID.
• credential_secret: Your Creators API credential secret.
• version: The API version (e.g., "2.2").
• tag: Your affiliate tag.
• country: The Country enum value representing the target market (e.g., Country.US).

from amazon_creatorsapi import AmazonCreatorsApi, Country

api = AmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
)

# Get product information by ASIN
items = api.get_items(["B01N5IB20Q"])
print(items[0].item_info.title.display_value)

Timeouts

The synchronous client now has default timeouts: 5 seconds to connect and 25 seconds to read. You can customize this using the timeout parameter. Setting timeout=None allows the client to wait indefinitely.

Retries

The client automatically retries requests that fail with 429, 500, 502, 503, or 504. It uses an exponential backoff strategy, honoring the Retry-After header up to 30 seconds. To disable automatic retries (e.g., if you have your own backoff logic), set retries=0.

# Custom timeout
api = AmazonCreatorsApi(..., timeout=60)    # Wait up to a minute
api = AmazonCreatorsApi(..., timeout=None)  # Wait indefinitely

# Disable retries
api = AmazonCreatorsApi(..., retries=0)

To use the asynchronous version of the API, you must install the package with the [async] extra, which includes the httpx dependency required for non-blocking operations.

pip install python-amazon-paapi[async] --upgrade

Use the following pattern to initialize the client and retrieve product information using either an ASIN or an Amazon URL.

from amazon_creatorsapi import AmazonCreatorsApi, Country

# Initialize with your Creators API credentials
api = AmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
)

# Get product information by ASIN
items = api.get_items(["B01N5IB20Q"])
print(items[0].item_info.title.display_value)

# Or use Amazon URLs directly
items = api.get_items(["https://www.amazon.com/dp/B01N5IB20Q"])

The client maintains a connection pool and is intended to be reused. To ensure connections are closed properly, use the client as a context manager.

with AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY) as api:
    items = api.get_items(["B01N5IB20Q"])

Starting from version 7.0.0, the amazon_paapi module has been removed. Users must migrate to the amazon_creatorsapi module which utilizes Amazon's Creators API. This migration involves updating imports, changing initialization parameters, and adjusting method signatures to include a resources parameter.

Upgrade Command

To upgrade to the latest version containing the Creators API support, run:

pip install python-amazon-paapi --upgrade

In version 7, get_items raises ItemsNotFoundError if none of the requested items are found.

To avoid exceptions and receive a list containing all requested identifiers (where missing items are returned as Item objects containing only their asin), use the include_unavailable=True parameter. You can inspect the errors attribute of the returned list to find the reason for any missing items.

from amazon_creatorsapi.errors import ItemsNotFoundError

# Option 1: Catch the error
try:
    items = api.get_items(["B01N5IB20Q", "0000000000"])
except ItemsNotFoundError as error:
    items = []

# Option 2: Use include_unavailable to get partial results
items = api.get_items(["B01N5IB20Q", "0000000000"], include_unavailable=True)

# Inspect errors for specific items
for error in items.errors:
    print(error.code, error.message)