amazon-sp-api-clients

Python clients for the Amazon Selling Partner API, generated from the official open api models. Fully type hinted and battle-tested. Enjoy it!

Attention

V1.0.0 changes many apis, compared with v0.x.x!

注意！V1.0.0 相较于 v0.x.x 更改了大量的 API！

Features

• Ready to use
• Fully type hinted
• Orders, feeds, reports and all other Selling Partner APIs
• Automatically manage LWA access tokens and STS role assumption
• Ships with a code generator, in case Amazon updates the models
• 700+ mocked tests, runnable without any credentials

Installation

pip install amazon-sp-api-clients

Quick Start

All credential fields below follow the real layout of actual credentials, with the sensitive parts replaced by ....

from datetime import datetime
import amazon_sp_api_clients

endpoint = "https://sellingpartnerapi-eu.amazon.com"
marketplace_id = "A1F83G8C2ARO7P"
refresh_token = "Atzr|...xxxx"
role_arn = "arn:aws:iam::123456789012:role/xxxxxx"
aws_access_key = "...xxxx"
aws_secret_key = "...xxxx"
client_id = "amzn1.application-oa2-client....xxxx"
client_secret = "...xxxx"

client_config = dict(
    role_arn=role_arn,
    endpoint=endpoint,
    marketplace_id=marketplace_id,
    refresh_token=refresh_token,
    aws_access_key=aws_access_key,
    aws_secret_key=aws_secret_key,
    lwa_client_key=client_id,
    lwa_client_secret=client_secret,
)

clients = amazon_sp_api_clients.AmazonSpApiClients(**client_config)
orders = clients.orders_v0.getOrders(
    MarketplaceIds=[marketplace_id],
    CreatedAfter=datetime(2000, 1, 1).isoformat(),
).payload.Orders

for order in orders:
    print(order.AmazonOrderId, order.LastUpdateDate)

Configuration

Configuration can be passed to the constructor, or read from environment variables.

Constructor parameters

• role_arn — IAM role to assume, e.g. arn:aws:iam::xxxxxxxxxxxx:role/sp_api_role
• endpoint — Selling Partner API endpoint, e.g. https://sellingpartnerapi-eu.amazon.com
• region — AWS region for the STS role, default us-east-1
• marketplace_id — e.g. A1F83G8C2ARO7P (EU marketplace)
• refresh_token — LWA refresh token
• aws_access_key — IAM user access key
• aws_secret_key — IAM user secret key
• lwa_client_key — LWA application client id
• lwa_client_secret — LWA application client secret
• raise_exceptions — if True raise SellingApiException on error, if False return the response json as-is (default True)

Environment variables

• SP_API_ROLE_ARN
• SP_API_ENDPOINT
• SP_API_REGION
• SP_API_MARKETPLACE_ID
• SP_API_REFRESH_TOKEN
• SP_API_AWS_ACCESS_KEY
• SP_API_AWS_SECRET_KEY
• SP_API_LWA_CLIENT_KEY
• SP_API_LWA_CLIENT_SECRET

Documentation

Detailed Chinese documentation lives under docs/, with docs/README.md as the index.

中文详细文档见 docs/ 目录，docs/README.md 为索引。

• docs/README.md — 文档索引
• 01_项目概览
• 02_快速开始
• 03_核心机制
• 04_API客户端参考
• 05_市场与端点
• 06_报表与Feed类型
• 07_代码生成器
• 08_测试指南
• 09_常见问题与调试
• 10_版本历史与兼容性

Tests

700+ mocked tests runnable without any credentials. 无需任何凭证即可运行全部测试：

py -m pytest tests -q

Build

Clients are generated from the Amazon open api models:

1. download the amazon selling-partner-api-models repository
2. copy open api 2 json files from the amazon repository to a single directory
3. convert open api 2 json files to open api 3 json files
4. convert open api 3 json files to py clients

The main generation script is test_main, and the conversion is split into 6 steps defined in the swager_client_generator.stages module.

If the build does not fit your demand, or Amazon updates the models but this repo has not followed yet, clone the repo, modify the api.pyt template and build it by yourself — and please push a PR, thanks!

See docs/07_代码生成器.md for details.

Acknowledgement

The auth method is partially from python-amazon-sp-api.

Note

For technical support, please contact panhaoyu.china@outlook.com.

Previously this lib was only open access but not open source, and now it's time to make it public to serve more developers.

If there's any bug, please feel free to open an issue or send a PR.

If this library helps you, please give me a star, thanks!

如果这个库对您有用，请为我点亮 Star，谢谢！