plentymarkets-api-client 0.5.1.dev15

Async Python client for the PlentyMarkets REST API

pyPlentyAPI

Async Python client for the PlentyMarkets REST API.

Features

• Async-first: Built on httpx.AsyncClient for high-performance async/await support.
• Lazy-loaded modules: Access orders, items, stock, contacts, and pim as properties of PlentyClient.
• Auto-refreshing auth: Tokens are refreshed automatically when within 60 seconds of expiry.
• Comprehensive error handling: Custom exceptions for HTTP status codes (e.g., NotFoundError, RateLimitError).
• Pagination support: Async generators for iterating across all pages of results.
• Type hints: Full type annotations for IDE support and static analysis.

Installation

pip install plentymarkets-api-client

Or with uv:

uv add plentymarkets-api-client

Quickstart

import asyncio
from plentymarkets import PlentyClient

async def main():
    async with PlentyClient(
        base_url="https://your-shop.plentymarkets.com",
        username="your_username",
        password="your_password",
    ) as client:
        # Fetch an order by ID
        order = await client.orders.get(123)
        print(order)
        
        # List all items (paginated)
        async for item in client.items.paginate_items():
            print(item)

asyncio.run(main())

Modules

Module	Description	Key Methods
Orders	Manage orders, order items, item transactions, serial numbers, and reorders.	get(), create(), update_status(), search(), paginate_search(), delete(), cancel(), list_order_items(), search_item_transactions(), create_order_transactions()
Items	Manage items and item variants.	get(), list(), create(), update(), paginate_items()
Stock	Manage stock, warehouses, storage locations, and stock movements.	get_by_warehouse(), correct(), list_warehouses(), book_incoming_items(), book_outgoing_items(), redistribute_stock(), paginate_stock()
Contacts	Manage customer and supplier data.	get(), list(), create(), update(), paginate_contacts()
Pim	Product Information Management — variations, attributes, categories, sales prices, barcodes, and more.	client.pim.* (80+ methods)

API Coverage

Endpoint totals are counted against the PlentyMarkets OpenAPI spec, grouped by its own tags.

Module	Endpoints	Status
Pim	80 / 80	✅ Complete
Stock	17 / 17	✅ Complete
Order	84 + 30 deprecated / 307	Lifecycle, items, transactions & core metadata
Item	4 / 294	Core operations
Account	4 / 151	Core operations
Total	219 / 1837 (11.9%)	Across all 53 API tags in the spec

Only tags with at least one implemented or deprecated endpoint get their own row above; the other 48 API tags (988 endpoints) are 0/N and not yet started — see ROADMAP.md for the full tag-by-tag breakdown.

Deprecated endpoints count toward the Total row since they're permanently out of scope rather than pending work.

Authentication

1. Initialize PlentyClient with your PlentyMarkets username and password.
2. The client automatically logs in and manages the accessToken lifecycle.
3. Tokens are sent as Authorization: Bearer <token> in all requests.
4. If a 401 error occurs, the client attempts to re-login once before failing.

Error Handling

Custom exceptions are raised for HTTP errors:

• AuthError: 401 Unauthorized
• NotFoundError: 404 Not Found
• RateLimitError: 429 Too Many Requests
• ServerError: 5xx Server Errors
• ConnectionError: Network failures

Example:

try:
    order = await client.orders.get(99999)
except plentymarkets.NotFoundError:
    print("Order not found")
except plentymarkets.RateLimitError:
    print("Rate limit exceeded")

Pagination

Use async generators to iterate across all pages:

async for order in client.orders.paginate_search():
    print(order)

Development

Setup

uv sync --extra dev
uv run pre-commit install --hook-type commit-msg

Running Tests

uv run pytest                        # Unit tests
uv run pytest -m integration         # Integration tests (requires live credentials)

License

MIT