PYTHON-AMAZON-AD-API

CodeQL CodeQL CodeQL PyPI Downloads

Amazon's Advertising API

A python 3 wrapper to access Amazon's Advertising API with an easy-to-use interface.

Install

pip install python-amazon-ad-api

Donate

If you find this project is useful consider donating or sponsor it to keep on going on it, thank you.

alt text

Overview

You need obtain your own credentials with Amazon that may include an amazon developer account and access as seller or vendor. Please view the checklist of Amazon Ads API onboarding overview

Code Credentials

You can use your credentials as follows passing it to the client as a dict. Please review the full documentation to see all posibilities to include your credentials.

from ad_api.api import sponsored_products


my_credentials = dict(
    refresh_token='your-refresh_token',
    client_id='your-client_id',
    client_secret='your-client_secret',
    profile_id='your-profile_id',
)

info = \
    {
        "stateFilter":
            {
                "include": [
                    "ENABLED"
                ]
            }
    }

result = sponsored_products.CampaignsV3(credentials=my_credentials).list_campaigns(
    body=info
)

YAML Credentials

Use a credentials.yml file with your credentials for more convenience and manage diferent accounts or profiles. Amazon requires one profile per marketplace so it is helpful to keep all in one file and switch directly from the code, using the account.

Create a file credentials.yml

version: '1.0'

default:
  refresh_token: 'your-refresh-token'
  client_id: 'your-client-id'
  client_secret: 'your-client-secret'
  profile_id: 'your-profile-id'

germany:
  refresh_token: 'other-refresh-token'
  client_id: 'other-client-id'
  client_secret: 'other-client-secret'
  profile_id: 'other-profile-id'

Python code

from ad_api.api import sponsored_products

# Leave empty will use the 'default' account
result=sponsored_products.CampaignsV3().list_campaigns()
# will use germany account data
result=sponsored_products.CampaignsV3(account="germany").list_campaigns()

Search path for credentials.yml

macOS and Other Unix: ~/.config/python-ad-api
Windows: %APPDATA%\python-ad-api where the APPDATA environment variable falls back to %HOME%\AppData\Roaming if undefined

Confuse Help

Marketplaces

Marketplaces are used to define basically the API endpoints Amazon need to use depending on the regions, by default it will use EU so if you are using one of the marketplaces that are under the Europe (EU). Covers UK, FR, IT, ES, DE, NL, AE, SE, PL, and TR marketplaces you can skip. If you are using either North America (NA) or Far East (FE), you will need import from base and pass the marketplace as follows:

from ad_api.api import sponsored_products
from ad_api.base import Marketplaces

# You can pass NA or US, CA, MX or BR for North America and JP, AU or SG for Far East
result=sponsored_products.CampaignsV3(marketplace=Marketplaces.NA).list_campaigns()

Exceptions

You can use a try except statement when you call the API and catch exceptions if some problem ocurred:

from ad_api.api import sponsored_products
from ad_api.base import AdvertisingApiException

info = \
    {
        "stateFilter":
            {
                "include": [
                    "ENABLED"
                ]
            }
    }

try:

    result = sponsored_products.CampaignsV3().list_campaigns(
        body=info
    )

    logging.info(result)

except AdvertisingApiException as error:
    logging.info(error)

Debug

Use debug=True if you want see some logs like the header you submit to the api endpoint, the method and path used among the params and the data submitted if any, to trace some possible errors.

from ad_api.api import sponsored_products
from ad_api.base import AdvertisingApiException


info = \
    {
        "stateFilter":
            {
                "include": [
                    "ENABLED"
                ]
            }
    }

try:

    result = sponsored_products.CampaignsV3(debug=True).list_campaigns(
        body=info
    )

    logging.info(result)

except AdvertisingApiException as error:
    logging.info(error)

import logging
from ad_api.api import Profiles
from ad_api.base import AdvertisingApiException

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s:%(levelname)s:%(message)s"
)


def register_assistant(value: str):

    logging.info("-------------------------------------")
    logging.info("Profiles > register_assistant(%s)" % value)
    logging.info("-------------------------------------")

    try:

        result = Profiles(debug=True).register_assistant(
            country_code=value
        )
        logging.info(result)

    except AdvertisingApiException as error:
        logging.info(error)


if __name__ == '__main__':

    amz_country_code = "ES"
    register_assistant(amz_country_code)

Or you could do with a curl command, note the {"countryCode":"ES"} that refers to the marketplace you will operate.

curl \
    -X PUT \
    -H "Content-Type:application/json" \
    -H "Authorization: Bearer Your-Token \
    -H "Amazon-Advertising-API-ClientId: your-client-id" \
    --data '{"countryCode":"ES"}' \
     https://advertising-api-test.amazon.com/v2/profiles/register

Reports

Simple Example Usage Campaigns with Credentials

import logging
from ad_api.base import AdvertisingApiException
from ad_api.api import sponsored_products

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s:%(levelname)s:%(message)s"
)

def sp_list_campaigns_v3(info: dict = None):

    credentials = dict(
        refresh_token='your-refresh_token',
        client_id='your-client_id',
        client_secret='your-client_secret',
        profile_id='your-profile_id',
    )

    try:
        result = sponsored_products.CampaignsV3(credentials=credentials, debug=True).list_campaigns(
            body=info
        )
        payload = result.payload
        return payload
    except AdvertisingApiException as error:
        logging.error(error)
        logging.error(error.code)


state_filter = \
    {
        "stateFilter":
            {
                "include": [
                    "ENABLED"
                ]
            }
    }

enabled_campaigns = sp_list_campaigns_v3(state_filter).get("campaigns")


for campaign in enabled_campaigns:
    logging.info(campaign)

logging.info(len(campaigns))

API NOTICE

This API is based on the API Client created by @saleweaver but adapted to amazon advertising authentication requeriments

DISCLAIMER

We are not affiliated with Amazon but they used our api :)

LICENSE

License

Last release: v0.8.6 (via electroduende automated release random access memory)

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for python-amazon-ad-api 0.8.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-amazon-ad-api 0.8.6
File	Size	Uploaded
python_amazon_ad_api-0.8.6.tar.gz	98.4 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for python-amazon-ad-api 0.8.6
File	Interpreter	ABI	Platform	Reset
python_amazon_ad_api-0.8.6-py3-none-any.whl 161.8 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 260.2 kB

Release files / python_amazon_ad_api-0.8.6.tar.gz

Download URL	python_amazon_ad_api-0.8.6.tar.gz
Size	98.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`6a4a7066e1231a3f7c6b8e5fb686823afdbf1dedfff730f298fd984c76623c6b`
BLAKE2b-256 checksum How to use checksums	`e26c2cbe6197a3bf33abd6727ecf012d2efc1e3b4a823ce7aa912e430319b176`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / python_amazon_ad_api-0.8.6-py3-none-any.whl

Download URL	python_amazon_ad_api-0.8.6-py3-none-any.whl
Size	161.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`61887d152c574197e44d7d01d11511155c51eb404263d66202700277e2684059`
BLAKE2b-256 checksum How to use checksums	`9ab1d0f9c1b2c67a0fd924a92e319e9d8bde79526076dc9c7d440026edf1713c`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`