Quickstart#

After setting up your credentials, you can make your first SP-API calls in a few lines.

This page focuses on practical workflows rather than listing every parameter. For full reference, see:

Prerequisites#

  • Python 3.8+

  • An SP-API application in Seller Central

  • A valid refresh token and IAM role / user configured according to Amazon’s guide

Install the package:

pip install python-amazon-sp-api

If you want to use AWS Secrets Manager for credential storage:

pip install "python-amazon-sp-api[aws]"
pip install "python-amazon-sp-api[aws-caching]"

Credentials#

The library can read credentials in three ways (in this order):

  1. From arguments passed in code

  2. From environment variables

  3. From a config file

See Credentials for the full list of supported fields.

Example – credentials from code:

credentials = dict(
    refresh_token='your_refresh_token',
    lwa_app_id='your_lwa_app_id',
    lwa_client_secret='your_lwa_client_secret',
    aws_access_key='your_aws_access_key',
    aws_secret_key='your_aws_secret_key',
    role_arn='your_role_arn',
)

from sp_api.api import Orders
orders = Orders(credentials=credentials)

Default marketplace#

By default, the library uses the US marketplace.

You can change this:

  • Per client, by passing a sp_api.base.Marketplaces value

  • Globally, via the SP_API_DEFAULT_MARKETPLACE environment variable

export SP_API_DEFAULT_MARKETPLACE=DE

from sp_api.base import Marketplaces
from sp_api.api import Orders

# Explicit marketplace
orders = Orders(marketplace=Marketplaces.DE)

# Or rely on SP_API_DEFAULT_MARKETPLACE:
orders = Orders()

All endpoint clients share the same signature:

SomeClient(
    marketplace=Marketplaces.US,
    *,
    refresh_token=None,
    account='default',
    credentials=None,
    restricted_data_token=None,
)

First request: get a single order#

from sp_api.base import Marketplaces
from sp_api.api import Orders

client = Orders(marketplace=Marketplaces.DE)

order = client.get_order('YOUR-ORDER-ID')

# `order` is an ApiResponse
print(order.payload)   # raw response dict
print(order.Orders)    # helper to access payload['Orders'] when present

Fetching many orders with pagination#

SP-API uses NextToken for pagination. This library ships a utility decorator that turns endpoint calls into a generator that automatically follows all pages.

from datetime import datetime, timedelta

from sp_api.api import Orders
from sp_api.util import throttle_retry, load_all_pages

@throttle_retry()      # retry on throttling
@load_all_pages()      # follow NextToken automatically
def iter_orders(**kwargs):
    return Orders().get_orders(**kwargs)

for page in iter_orders(
    LastUpdatedAfter=(datetime.utcnow() - timedelta(days=7)).isoformat()
):
    for order in page.payload.get('Orders', []):
        print(order['AmazonOrderId'], order['OrderStatus'])

Notes:

  • @load_all_pages yields one ApiResponse per page.

  • Some endpoints use a different token name (for example next_token). You can pass next_token_param to the decorator:

    @load_all_pages(next_token_param='next_token')
def iter_something(**kwargs):
    ...

Handling throttling & retries#

Amazon enforces strict rate limits per operation. When you hit the limit, SP-API returns HTTP 429 and this library raises sp_api.base.SellingApiRequestThrottledException.

The sp_api.util module provides retry decorators:

Example: retry a single call:

from sp_api.api import Orders
from sp_api.util import throttle_retry

@throttle_retry(tries=10, delay=5, rate=1.3)
def get_orders(**kwargs):
    return Orders().get_orders(**kwargs)

res = get_orders(CreatedAfter='2024-01-01T00:00:00Z')

Combining retries and auto-pagination:

from sp_api.util import sp_retry, load_all_pages

@sp_retry(tries=10, delay=10, rate=1.2)
@load_all_pages()
def get_all_orders(**kwargs):
    return Orders().get_orders(**kwargs)

for page in get_all_orders(CreatedAfter='2024-01-01T00:00:00Z'):
    ...

Creating reports#

Creating a report with sp_api.api.ReportsV2:

from datetime import datetime, timedelta

from sp_api.api import ReportsV2
from sp_api.base.reportTypes import ReportType

reports = ReportsV2()

res = reports.create_report(
    reportType=ReportType.GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL,
    dataStartTime=(datetime.utcnow() - timedelta(days=7)).isoformat(),
    dataEndTime=(datetime.utcnow() - timedelta(days=1)).isoformat(),
)

print(res.payload)  # contains the report id

Submitting feeds#

from sp_api.api import Feeds

with open("my_feed_file.tsv", "rb") as f:
    Feeds().submit_feed(
        feed_type="POST_PRODUCT_DATA",   # use your feed type
        file=f,
        content_type="text/tsv",
    )

Working with PII (Restricted Data Token)#

Some endpoints require access to PII (personally identifiable information), e.g.:

  • Order shipping address

  • Buyer info

For those, you must:

  1. Use Amazon’s Tokens API to request a Restricted Data Token (RDT)

  2. Pass the token to the client via restricted_data_token

from sp_api.api import Orders

rdt = "YOUR_RESTRICTED_DATA_TOKEN"

orders = Orders(restricted_data_token=rdt)

res = orders.get_orders(
    LastUpdatedAfter="2024-01-01T00:00:00Z",
    # and any RestrictedResources required by Amazon
)

Next steps#

From here, you probably want to look at: