Wildberries Python SDK

Professional, contract-oriented Python client for Wildberries API.

Features

• Async/Sync support - Works with both async and synchronous code using httpx
• Type-safe - Full Pydantic V2 models with validation
• Rate limiting - Intelligent token-based rate limiting with category isolation
• Error handling - Typed exception hierarchy for all API errors
• Registry-based - YAML configuration for easy endpoint extension
• Sandbox/Production - Support for both WB environments
• Pagination - Built-in async/sync page iterators

Installation

pip install wildberries-python-sdk

Or with development dependencies:

pip install wildberries-python-sdk[dev]

Quick Start

Async Client

import asyncio
from wildberries_python_sdk import BaseClient, Registry, RateLimiter, GeneralService

async def main():
    registry = Registry("config/endpoints")
    ratelimiter = RateLimiter()

    client = BaseClient(
        token="your-api-token",
        registry=registry,
        ratelimiter=ratelimiter
    )

    service = GeneralService(client)
    info = await service.get_seller_info()
    print(f"Seller: {info.name}")

    await client.close()

asyncio.run(main())

Sync Client

from wildberries_python_sdk import SyncClient, Registry, RateLimiter, GeneralService

with SyncClient("token", registry, ratelimiter) as client:
    service = GeneralService(client)
    info = service.get_seller_info()
    print(info.name)

Services

Service	Description
GeneralService	Connection check, news, seller info, user management
ProductsService	Categories, product cards, tags
WarehouseService	Seller warehouses management
InventoryService	Stock management
PricesService	Prices and discounts
MediaService	Media files upload

Products API Example

from wildberries_python_sdk import ProductsService

service = ProductsService(client)

# Get categories
categories = await service.get_parent_categories()
for cat in categories.data:
    print(f"{cat.id}: {cat.name}")

# Get product cards
cards = await service.get_cards_list(
    settings={"cursor": {"limit": 100}}
)

Error Handling

from wildberries_python_sdk import WBAPIError, TooManyRequestsError

try:
    result = await service.get_data()
except TooManyRequestsError as e:
    print(f"Rate limited! {e.detail}")
except WBAPIError as e:
    print(f"API Error {e.status}: {e.detail}")

Configuration

from wildberries_python_sdk import Config, DomainType, set_default_locale

# Set global configuration
set_default_locale("en")

# Or use Config class
config = Config(locale="en", domain=DomainType.SANDBOX)

Development

# Clone and install
git clone https://github.com/wildberries/wildberries-python-sdk
cd wildberries-python-sdk
pip install -e ".[dev]"

# Run tests
pytest tests/

# Type checking
mypy src/

# Linting
ruff check src/

License

MIT License - see LICENSE file for details.