SDK Reference
Python SDK
Ultra high-performance Python SDK for the Linkit API — asyncio, httpx, dataclasses, pip distribution.
Python SDK
Package
linkit-sdk · Python 3.10+ · httpx · asyncio · dataclasses · pip / PyPI
Installation
pip install linkit-sdkpoetry add linkit-sdkpdm add linkit-sdkQuick Start
Initialize the Client
from linkit import LinkitClient
client = LinkitClient.quick_setup("https://linkit.works/api/v1", "your-jwt-token")Create a SKU with the Fluent Builder
from linkit.builders import SkuCreateBuilder
sku = await client.skus.create(
SkuCreateBuilder()
.with_iv_id("SKU-001")
.in_branch("BR-RYD")
.for_product("PROD-001")
.with_price(29.99)
.with_qty(500)
.build()
)List Products
products = await client.products.list(
ProductListRequest(page=1, limit=25, enabled=True, search="widget")
)
for p in products.data:
print(f"{p.name_en} — {p.average_price}")Context Manager (Recommended)
async with LinkitClient.quick_setup("https://linkit.works/api/v1", "token") as client:
health = await client.health.check()
print(f"Status: {health.status}")Configuration
from linkit import LinkitClient, LinkitConfiguration
config = LinkitConfiguration(
base_url="https://linkit.works/api/v1",
jwt_token="your-jwt-token",
timeout_ms=30_000,
max_retries=3,
retry_base_delay_ms=1_000,
retry_max_delay_ms=30_000,
circuit_breaker_threshold=5,
circuit_breaker_recovery_ms=60_000,
max_concurrent_requests=10,
)
client = LinkitClient.create(config)Services Reference
| Service | Methods | Description |
|---|---|---|
client.skus | create(), get_by_id(), update(), update_stock(), delete_by_id(), list() | Per-branch inventory |
client.products | create(), get_by_id(), update(), delete_by_id(), list() | Product catalog |
client.branches | create(), get_by_id(), update(), delete_by_id(), list() | Physical locations |
client.customers | create(), get_by_id(), update(), delete_by_id(), list(), lookup_by_email(), lookup_by_phone(), search(), create_address(), update_address(), delete_address(), create_group(), list_groups() | Customer profiles |
client.orders | get(), list(), update_status() | Order management |
client.offers | create(), get(), update(), update_status(), delete(), list(), bulk_upsert() | Promotions & discounts |
client.brands | create(), get_by_id(), update(), delete_by_id() | Brand management |
client.categories | create(), get_by_id(), update(), delete_by_id() | Product categories |
client.generics | create(), get_by_id(), update(), delete_by_id() | Generic entities |
client.health | check(), ping() | System health |
client.integrations | list(), get(), execute(), enable(), disable() | Platform connections |
Builders
SkuCreateBuilder
request = (
SkuCreateBuilder()
.with_iv_id("SKU-001")
.in_branch("BR-RYD")
.for_product("PROD-001")
.with_barcode("5901234123457")
.with_price(29.99)
.with_qty(500)
.with_available(True)
.with_amazon_sku("AMZ-W001")
.build() # raises LinkitValidationError if invalid
)ProductCreateBuilder
request = (
ProductCreateBuilder()
.with_iv_id("PROD-001")
.with_name_en("Premium Widget")
.with_name_ar("ودجت فاخر")
.with_average_price(149.99)
.with_enabled(True)
.build()
)Error Handling
from linkit.exceptions import (
LinkitNotFoundError,
LinkitRateLimitError,
LinkitValidationError,
LinkitApiError,
)
try:
sku = await client.skus.get_by_id("nonexistent")
except LinkitNotFoundError as e:
print(f"Not found: {e.resource_type}")
except LinkitRateLimitError as e:
print(f"Rate limited — retry after {e.retry_after_ms}ms")
except LinkitValidationError as e:
for error in e.validation_errors:
print(f" {error.field}: {error.message}")
except LinkitApiError as e:
print(f"API error {e.status_code}: {e.user_friendly_message}")Exception Hierarchy
| Exception | Status | Description |
|---|---|---|
LinkitError | — | Base exception |
LinkitInitializationError | — | Bad configuration |
LinkitApiError | Any | API error response |
LinkitAuthenticationError | 401 | Invalid credentials |
LinkitAuthorizationError | 403 | Insufficient permissions |
LinkitNotFoundError | 404 | Resource not found |
LinkitValidationError | 400 | Validation failed |
LinkitConflictError | 409 | State conflict |
LinkitRateLimitError | 429 | Rate limit exceeded |
LinkitServerError | 5xx | Server-side error |
LinkitSerializationError | — | JSON parse failure |
Performance Notes
Async-First Architecture
The Python SDK is built on httpx.AsyncClient with connection pooling. All service methods are async. The __slots__ optimization is used on all dataclasses for minimal memory footprint. The circuit breaker uses asyncio.Lock for thread safety in concurrent scenarios.
httpx ≥ 0.27
HTTP/2 support, connection pooling, automatic retries baked in.
Zero Reflection
Pure dataclass serialization — no pydantic, no attrs, no runtime introspection.
Minimal Dependencies
Only httpx — everything else is stdlib.