omnicommerce

Python client for the OmniCommerce API.

The client is generated from the public OpenAPI spec, the same operation map as @omni-commerce/sdk. Sync and async clients take snake_case keyword arguments. Responses are parsed JSON.

Install

Install from PyPI:

python3 -m pip install omnicommerce

Python 3.10+.

Usage

import os
from omnicommerce import Omni

with Omni(api_key=os.environ["OMNI_API_KEY"]) as client:
    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"],
        }
    )
    created = client.jobs.wait(job_id=job["jobId"])

API keys are organization-scoped. Do not send organization_id on API-key requests.

from omnicommerce import AsyncOmni, Omni, OmniEnvironment

client = Omni(
    api_key="omni_sk_...",
    environment=OmniEnvironment.LOCAL,  # http://localhost:3000
    timeout_in_seconds=60,
    max_retries=2,
)

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

client.with_raw_response.products.get(product_id="prod_123") returns data, status_code, headers, and url.

Review actions

Use client.reviews.reply(review_id="review-uuid", reply="Thank you!") to submit supplied text. Set generate_with_ai=True instead of reply for an AI-generated response; submit=False returns a draft, while submit=True sends it. Optional instructions guide the AI. The review ID goes in the URL; inspect data.submitted for confirmation. Both sync and async clients use this endpoint; the separate draft_reply and actions methods are removed.

Batch market price comparison

Version 0.6.1 adds sync and async products.compare_prices and products.get_price_comparison. Submit up to 50 simple product or variant IDs with a catalog:read credential:

queued = client.products.compare_prices(
    product_ids=["cc87d195-097a-4a5a-8229-cd989ce98d0f"],
)
client.jobs.wait(job_id=queued["jobId"], timeout_in_seconds=1800)
completed = client.products.get_price_comparison(job_id=queued["jobId"])
print(completed["result"]["success"], completed["result"]["results"])

Omit gl to compare all recorded listing markets; gl="sg" restricts research to Singapore. Global Zalora prices stay separate by country/currency. An India Shopify store selling in SGD is researched in Singapore. Read each product's markets array for price evidence, research, comparison, and errors. Missing published price evidence is an explicit failure; a catalog fallback is never a verified listing price. A wait timeout leaves the durable job running. Full comparison guide.

Resources

Every other documented tag is exposed the same way.

Errors

from omnicommerce import NotFoundError, Omni, OmniError

try:
    client.products.get(product_id="missing")
except NotFoundError:
    pass
except OmniError as error:
    print(error.status_code, error.body)

Webhooks

from omnicommerce import construct_event

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

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

Regenerate from OpenAPI

From the monorepo root:

yarn sdk:generate

That refreshes src/omnicommerce/_generated/resources.py from docs/openapi.json.