eBay REST Client

This workspace contains a REST-first Python client for the newer eBay APIs backed by:

• a shared OAuth 2.0 core
• a shared HTTP transport layer
• handwritten public wrappers per API domain
• isolated OpenAPI-generated Pydantic models per contract

Implemented API domains:

• Notification
• Inventory
• Fulfillment
• Account
• Feed
• Media

The public entry point is EbayClient, which wires all six wrappers behind one shared transport and one shared token store.

Project Layout

• ebay_client/client.py: top-level EbayClient facade
• ebay_client/<api>/client.py: handwritten wrapper layer for each API
• ebay_client/generated/<api>/models.py: generated Pydantic models for that contract
• ebay_client/core/auth/: OAuth configuration, token model, token store, and OAuth client
• ebay_client/core/http/: shared transport and error handling
• examples/: runnable examples for media workflows and FastAPI notification webhooks

Quick Start

Install the package from the project root:

& .\.venv\Scripts\python.exe -m pip install -e .

Install development dependencies when you want tests and code generation tooling:

& .\.venv\Scripts\python.exe -m pip install -e .[dev]

Create a client with your eBay credentials:

from ebay_client import EbayClient
from ebay_client.core.auth.models import EbayOAuthConfig

oauth_config = EbayOAuthConfig(
	client_id="your-client-id",
	client_secret="your-client-secret",
	default_scopes=[
		"https://api.ebay.com/oauth/api_scope/sell.inventory",
	],
)

client = EbayClient(oauth_config)

inventory_page = client.inventory.get_inventory_items(limit=25)
orders_page = client.fulfillment.get_orders(limit=25)

EbayClient exposes these wrappers:

• client.notification
• client.inventory
• client.fulfillment
• client.account
• client.feed
• client.media

Authentication

The client uses a custom OAuth implementation in ebay_client.core.auth.oauth.EbayOAuthClient. There is no dependency on eBay's official OAuth client.

Important behavior:

• EbayClient creates an internal EbayOAuthClient and uses it automatically for API calls.
• The default token store is InMemoryTokenStore, so tokens are not persisted across process restarts.
• If you want persistent tokens, provide your own TokenStore implementation to EbayClient.
• redirect_uri is only required when you use the authorization-code flow.
• For plain wrapper usage, the transport can obtain client-credentials tokens automatically.

If you need interactive OAuth flows, build and use EbayOAuthClient directly with the same token store you pass to EbayClient:

from ebay_client import EbayClient
from ebay_client.core.auth.models import EbayOAuthConfig
from ebay_client.core.auth.oauth import EbayOAuthClient
from ebay_client.core.auth.store import InMemoryTokenStore

store = InMemoryTokenStore()

oauth_config = EbayOAuthConfig(
	client_id="your-client-id",
	client_secret="your-client-secret",
	redirect_uri="https://your-app.example/callback",
	default_scopes=[
		"https://api.ebay.com/oauth/api_scope",
		"https://api.ebay.com/oauth/api_scope/commerce.notification.subscription",
	],
)

oauth = EbayOAuthClient(oauth_config, token_store=store)
authorization_url = oauth.build_authorization_url(state="csrf-token")

client = EbayClient(oauth_config, token_store=store)

Authentication Caveats

The wrappers handle scope selection for you, but a few behaviors are worth calling out explicitly.

• Read methods often accept either a readonly scope or the broader write scope. Internally, the wrappers express this through scope_options, so an already-cached broader token is reused instead of forcing a narrower re-auth.
• Write methods request the stronger write scope directly.
• If the current token is missing required scopes, the OAuth layer requests a new token with the needed scope set.
• default_scopes matter most when you explicitly use build_authorization_url(), exchange_code(), or refresh_access_token() without passing scopes.
• Notification inbound webhooks are not authenticated with bearer tokens. They are validated through the X-EBAY-SIGNATURE header and eBay's public-key lookup flow.

Known endpoint-specific caveats:

• FulfillmentClient.issue_refund() uses https://api.ebay.com/oauth/api_scope/sell.finances, not the normal fulfillment scope.
• Payment-dispute methods use https://api.ebay.com/oauth/api_scope/sell.payment.dispute and target https://apiz.ebay.com/sell/fulfillment/v1/.... The shared transport already supports this alternate host.
• Some Inventory write endpoints require a Content-Language header. Those wrapper methods require content_language=... explicitly.
• eBay documents additional Digital Signatures requirements for some refund scenarios, especially for some EU and UK sellers. That signing flow is not implemented in this client yet, so refund support is limited to the normal OAuth-backed request path.

Implemented Functionality

This section is intended as the quick capability map for the handwritten wrappers. For payload and response shapes, use the generated models in ebay_client/generated/<api>/models.py.

Notification

Management and subscription features:

• config: get_config(), update_config()
• topics: get_topics(), get_topic()
• destinations: get_destinations(), create_destination(), get_destination(), update_destination(), delete_destination()
• subscriptions: get_subscriptions(), create_subscription(), get_subscription(), update_subscription(), delete_subscription()
• subscription state actions: disable_subscription(), enable_subscription(), test_subscription()
• filters: create_subscription_filter(), get_subscription_filter(), delete_subscription_filter()
• public-key lookup: get_public_key()

Webhook helpers in ebay_client.notification.webhook cover:

• challenge responses
• signature-header parsing
• signature verification against eBay public keys
• normalized event envelopes
• framework-neutral request handling

See examples/fastapi_notification_webhook.py for a concrete FastAPI integration.

Inventory

Inventory wrapper coverage includes:

• inventory items: get_inventory_item(), get_inventory_items(), create_or_replace_inventory_item(), delete_inventory_item()
• bulk item workflows: bulk_get_inventory_item(), bulk_create_or_replace_inventory_item()
• price and quantity updates: bulk_update_price_quantity()
• product compatibility: get_product_compatibility(), create_or_replace_product_compatibility(), delete_product_compatibility()
• inventory item groups: get_inventory_item_group(), create_or_replace_inventory_item_group(), delete_inventory_item_group()
• offers: get_offer(), get_offers(), create_offer(), bulk_create_offer(), update_offer(), delete_offer()
• listing publication: publish_offer(), bulk_publish_offer(), publish_offer_by_inventory_item_group()
• listing withdrawal: withdraw_offer(), withdraw_offer_by_inventory_item_group()
• fees: get_listing_fees()
• locations: get_inventory_location(), get_inventory_locations(), create_inventory_location(), update_inventory_location(), delete_inventory_location(), enable_inventory_location(), disable_inventory_location()
• migration and mapping: bulk_migrate_listing(), get_sku_location_mapping(), create_or_replace_sku_location_mapping(), delete_sku_location_mapping()

Fulfillment

Fulfillment wrapper coverage includes:

• orders: get_order(), get_orders()
• refunds: issue_refund()
• shipping fulfillments: get_shipping_fulfillments(), get_shipping_fulfillment(), create_shipping_fulfillment()
• payment disputes: get_payment_dispute(), get_payment_dispute_summaries(), get_payment_dispute_activities(), contest_payment_dispute(), accept_payment_dispute()
• dispute evidence: upload_evidence_file(), add_evidence(), update_evidence(), fetch_evidence_content()
• helper types: CreatedShippingFulfillment, EvidenceFileDownload, extract_fulfillment_id()

Account

Account wrapper coverage includes:

• fulfillment policies: list, get, create, update, delete, and get_fulfillment_policy_by_name()
• payment policies: list, get, create, update, delete, and get_payment_policy_by_name()
• return policies: list, get, create, update, delete, and get_return_policy_by_name()
• seller capabilities: get_privileges(), get_opted_in_programs()

Feed

Feed wrapper coverage includes:

• tasks: get_tasks(), create_task(), get_task()
• task files: upload_file(), get_input_file(), get_result_file(), get_latest_result_file()
• schedule templates: get_schedule_templates(), get_schedule_template()
• schedules: get_schedules(), create_schedule(), get_schedule(), update_schedule(), delete_schedule()
• helper types: CreatedFeedResource, FeedFileDownload, extract_feed_resource_id()

Media

Media wrapper coverage includes raw API methods plus higher-level workflow helpers.

Core operations:

• images: create_image_from_file(), create_image_from_path(), create_image_from_url(), get_image()
• videos: create_video(), upload_video(), get_video(), wait_for_video()
• documents: create_document(), create_document_from_url(), upload_document(), upload_document_from_path(), get_document(), wait_for_document()

Workflow helpers:

• create_upload_and_wait_video()
• create_upload_and_wait_video_from_path()
• create_upload_and_wait_document()
• create_upload_and_wait_document_from_path()
• create_document_from_url_and_wait()
• extract_resource_id()
• guess_media_content_type()
• result types: VideoWorkflowResult, DocumentWorkflowResult

See examples/media_workflows.py for end-to-end examples.

Working With Generated Models

The wrapper layer is intentionally thin. For request bodies and typed responses, import the generated models for the relevant API package.

Example:

from ebay_client import EbayClient
from ebay_client.core.auth.models import EbayOAuthConfig
from ebay_client.generated.media.models import CreateDocumentRequest

client = EbayClient(
	EbayOAuthConfig(
		client_id="your-client-id",
		client_secret="your-client-secret",
		default_scopes=["https://api.ebay.com/oauth/api_scope/sell.inventory"],
	)
)

result = client.media.create_upload_and_wait_document_from_path(
	CreateDocumentRequest(
		documentType="USER_GUIDE_OR_MANUAL",
		languages=["en-US"],
	),
	"./manual.pdf",
)

Webhook Usage

For Notification inbound events, the recommended flow is:

• handle the eBay challenge request with WebhookRequestHandler.handle_challenge()
• resolve the notification public key through WebhookPublicKeyResolver
• validate X-EBAY-SIGNATURE with WebhookSignatureValidator
• dispatch the verified event envelope returned by WebhookRequestHandler.handle_notification()

The FastAPI example in examples/fastapi_notification_webhook.py shows the complete GET challenge and POST notification flow.

Code Generation

The project uses a dedicated code generation environment because the main runtime is currently on Python 3.14 while datamodel-code-generator is run from the separate codegen environment.

Generate all API model packages from the project root:

& .\.venv\Scripts\python.exe .\scripts\generate_clients.py

Generate only one API package:

& .\.venv\Scripts\python.exe .\scripts\generate_clients.py --api notification

Generated output is written to ebay_client/generated/<api>/models.py.

Validation

Run the test suite from the project root:

& .\.venv\Scripts\python.exe -m pytest