ebay-apiroute

Python clients for eBay's REST APIs and its Trading API, generated with apiroute from the API specs eBay publishes, and kept current by a weekly build.

• Two layers: every call works with plain dicts (api.inventory_item.get_inventory_item("SKU1")), and .models takes and returns typed pydantic models (api.inventory_item.models.get_inventory_item("SKU1")).
• Sync and async: add .aio to any call for the async version.
• Lazy loading: only the APIs, sections and models you use are imported, so a script that calls one endpoint stays fast, though the package covers 30 APIs and about 1,400 models.

Installation

pip install ebay-apiroute    # or: uv add ebay-apiroute

It needs Python 3.10 or newer.

REST APIs

Every REST client takes an OAuth access token. The token can be a string, or a function that returns the current one, which suits code that refreshes tokens.

from ebay_apiroute.sell.inventory import SellInventoryApi

api = SellInventoryApi(token="v^1.1#i^1#...", marketplace_id="EBAY_US")

item = api.inventory_item.get_inventory_item("SKU1")  # a dict
item = api.inventory_item.models.get_inventory_item("SKU1")  # InventoryItemWithSkuLocaleGroupid
items = await api.inventory_item.models.aio.get_inventory_items(limit="25")

sandbox = SellInventoryApi(token=refreshing_token, sandbox=True)  # api.sandbox.ebay.com

• marketplace_id is sent as the X-EBAY-C-MARKETPLACE-ID header.
• sandbox=True switches to eBay's sandbox hosts.
• Getting tokens is up to your application. eBay's OAuth guide covers application tokens (the client credentials grant) and user tokens (the authorization code grant).

Trading API

The Trading API is SOAP. Its client sends your token in the RequesterCredentials SOAP header, and adds the call name, site, application ID and API version to each request, as eBay's SOAP endpoint requires.

from ebay_apiroute.trading import TradingApi

trading = TradingApi(token="AgAAAA...", app_id="MyApp-PRD-...", site_id=0)
response = trading.get_item(body={"ItemID": "123456789", "DetailLevel": "ReturnAll"})
response = trading.models.get_item(body={"ItemID": "123456789"})  # GetItemResponseType

Bodies and responses use the xmltodict shape:

• child elements are keys
• "@name" is an attribute
• "#text" is an element's text

A SOAP fault raises apiroute.soap.SoapFault. The API version comes from the WSDL (ebay_apiroute.trading_version.TRADING_VERSION); pass version= to override it.

APIs

Errors raise apiroute.UnexpectedResponse, which carries the .response. For retries, transports and other client options, see apiroute's README.

How this repository stays up to date

Nothing under src/ebay_apiroute/ is written by hand except auth.py and __init__.py. Everything else is generated from the API descriptions listed in apis.yaml:

1. Every Monday, the Build workflow does the following:
   • Upgrades apiroute to its newest release.
   • Downloads each spec again into specs/, the committed copy of what eBay publishes.
   • Regenerates the clients with apiroute generate.
   • Runs the lint and tests.
2. If anything changed, it commits the result to main:
   • feat(specs): ... when eBay changed a spec, which produces a minor release.
   • fix(codegen): ... when only a newer apiroute changed the generated code, which produces a patch release.
3. Release (release-please) then updates its release PR. Merging that PR publishes a new version to PyPI.

CI checks every push. It lints, runs the tests on Python 3.10 to 3.14, and regenerates from the committed specs to confirm the committed code matches them exactly.

Because specs/ is committed, git log -p specs/ shows exactly what eBay changed and when.

Development

uv sync
uv run python scripts/generate.py --fetch      # download the latest specs, regenerate everything
uv run python scripts/generate.py --only trading   # regenerate one API from its committed spec
uv run pytest
uv run ruff check . && uv run ruff format --check .

To add an API, add an entry to apis.yaml, run scripts/generate.py --fetch, then commit the spec and the generated code. The table above updates itself. Auth lives in src/ebay_apiroute/auth.py, which the generated clients extend.

License

MIT