Python SDK

The Python SDK (omnicommerce) is generated from the same public OpenAPI spec as the TypeScript SDK. Every documented REST operation is a resource method. Responses are parsed JSON: objects are dicts, arrays are lists, and an empty body is None.

Install

Install the SDK from PyPI:

python3 -m pip install omnicommerce

Requires Python 3.10+.

import os
from omnicommerce import AsyncOmni, Omni

Authenticate

Use an organization API key (omni_sk_...) as a bearer token. Do not send organization_id on API-key requests.

client = Omni(api_key=os.environ["OMNI_API_KEY"])

Omit api_key to read OMNI_API_KEY. Override the host with base_url or environment (https://omnicommerce.sg by default). OmniEnvironment.LOCAL is http://localhost:3000. See Authentication.

from omnicommerce import Omni, OmniEnvironment

client = Omni(
    api_key=os.environ["OMNI_API_KEY"],
    environment=OmniEnvironment.LOCAL,
    timeout_in_seconds=60,
    max_retries=2,
)

Use the client as a context manager so the HTTP connection closes. AsyncOmni is the async client and uses async with.

Resource clients

Each call takes keyword arguments. Path, query, and JSON fields keep their wire names in snake_case: productId is product_id, minPrice is min_price.

products = client.products.list(q="lamp")

job = client.products.create(
    product={
        "sku": "SKU-100",
        "title": "Sample product",
        "price": 29.9,
        "currency": "SGD",
        "images": ["https://cdn.example.com/product.jpg"],
    }
)
client.jobs.wait(job_id=job["jobId"])

publish = client.products.publish(product_id="prod_123", visibility="live")
client.jobs.wait(job_id=publish["jobId"])

delist = client.products.delist(
    product_id="prod_123",
    marketplaces=["shopee", "lazada"],
)
client.jobs.wait(job_id=delist["jobId"])

Per-request overrides:

from omnicommerce import RequestOptions

client.orders.get(
    order_id="ord_123",
    request_options=RequestOptions(timeout_in_seconds=15),
)

client.with_raw_response.orders.get(...) returns data, status_code, headers, and url.

async with AsyncOmni(api_key=os.environ["OMNI_API_KEY"]) as client:
    products = await client.products.list(q="lamp")

Product inventory

Response keys keep their API casing even though method arguments use snake_case. Read page["items"] and each row’s stockQuantity, hasVariants, and variantCount.

page = client.products.list(q="lamp")
for product in page["items"]:
    quantity = product.get("stockQuantity")
    print(product["id"], "Unknown stock" if quantity is None else quantity)

stockQuantity is catalog stock, matching the Products page. Parent rows already aggregate their variants; virtual bundles already account for component stock and any manual cap. Preserve null or missing values as unknown. Do not read inventoryQuantity, inventory.quantity, or stock_quantity, and do not sum a missing variants array. See Product inventory for quantity semantics.

Coverage

Client	Examples
`client.products`	`list`, `create`, `get`, `update`, `delete`, `publish`, `delist`, `bulk_import`, `enrich`
`client.orders`	`list`, `create`, `get`, `update`
`client.promotions`	`list`, `create`, `get`, `update`, `delete`, `sync`
`client.price_books`	`list`, `create`, `get`, `update`, `delete`, `preview`
`client.aop`	`create`, `execute`, `get_config`, `update_config`, `retry`
`client.jobs`	`get`, `cancel`, `wait`
`client.webhooks`	`list`, `create`
`client.checkout_sessions`	`create`, `get`, `update`, `complete`, `cancel`
`client.ucp`	`checkout_sessions`, `orders`
`client.oauth`	`token`, `revoke`

Looks, returns, settlements, marketplaces, search, evaluate, monitor, sync, Zalora, and the remaining documented tags follow the same pattern.

Errors

Non-2xx responses raise OmniError subclasses. See SDK errors. GET, HEAD, OPTIONS, PUT, and DELETE retry on 5xx and network failures. 408 and 429 retry for every method. POST and PATCH are not retried on 5xx.

Webhooks

from omnicommerce import construct_event

event = construct_event(raw_body, request.headers, os.environ["OMNI_WEBHOOK_SECRET"])

HMAC-SHA256 over {timestamp}.{raw_body} compared to X-Omni-Signature. See Webhooks.

Regenerate

From this repository:

yarn sdk:generate

Get started

Guides

SDK

CLI

Webhooks

MCP

Install

Authenticate

Resource clients

Product inventory

Coverage

Errors

Webhooks

Regenerate

​Install

​Authenticate

​Resource clients

​Product inventory

​Coverage

​Errors

​Webhooks

​Regenerate

Install

Authenticate

Resource clients

Product inventory

Coverage

Errors

Webhooks

Regenerate