Skip to main content
The TypeScript SDK (@omni-commerce/sdk) is generated from the public OpenAPI spec, so every documented REST operation is a typed resource method. The command-line client uses the same spec — see Omni CLI. The unscoped npm name omnicommerce is reserved. The public org is @omni-commerce.

Install

Requires Node 18+ (global fetch). Named export only:

Authenticate

Use an organization API key (omni_sk_...) as a bearer token. Do not send organizationId on API-key requests.
Omit apiKey to read OMNI_API_KEY. Override the host with baseUrl or environment (https://omnicommerce.sg by default). See Authentication.

Resource clients

Each call takes one request object (path params, query, and JSON body together), then optional request options:
Per-request overrides:
await request.withRawResponse() returns { data, rawResponse } with status and headers.

Publish selected fields

Pass marketplaces to choose where to publish/update. Omit it to use every enabled or already listed marketplace. Pass updateFields to publish only those saved product fields, matching the publish popover. Selected-field updates require an existing listing and assigned store; other fields and listing visibility stay unchanged. Omit fields for a full publish.
Check ok and every target result: valid marketplaces can queue while another fails. Price and inventory selections return their durable jobs in the same results. Queued work is not proof of a live marketplace change. See the API reference for supported fields and marketplace capability limits.

Product inventory

products.list() returns rows in page.items. Read catalog stock from stockQuantity, matching the Products page. Parent rows already aggregate their variants; virtual bundles already account for component stock and any manual cap. The list response does not embed a variants array: a row with variantCount above 0 has variants, and products.get() returns them in variants.
Only 0 means zero stock. Preserve null or missing values as unknown; do not default them to zero. inventoryQuantity and inventory.quantity are not product-list fields. stockQuantity is catalog stock, not a sum of marketplace inventory mirrors or a per-location available-to-promise balance.

Market price comparison

Compare up to 50 OmniCommerce simple product or variant IDs using the shopping APIs behind pricing strategy. This read-only operation requires catalog:read and returns a durable job.
Omit gl to compare every recorded listing market; pass gl: "sg" to restrict research to Singapore. Global Zalora uses each recorded country price and currency, including Hong Kong and Taiwan. A Shopify store based in India but selling in SGD is researched in Singapore. Use variant IDs for products with variants. Inspect completed.result.success, each market’s success, priceSource, priceAsOf, and errors. Marketplace snapshots and acknowledged writes are persisted evidence, not a live listing refresh. Missing published prices produce explicit failures, with catalog research where available. Unlisted products use catalog pricing. Currencies stay separate; verify shopping variants and pack sizes before using results. A client wait timeout leaves the durable job running. See the API reference for the canonical contract.

Coverage

Looks, returns, settlements, marketplaces, search, evaluate, monitor, sync, Zalora, and the remaining documented tags follow the same pattern. The generator covers every REST operation in the API reference. client.agents.general.invoke waits for the Omni agent. Pass { timeoutInSeconds: 780 } on that call. start returns immediately and getRun({ runId }) polls the run. See Omni agent API.

File uploads

Upload methods (documents.upload, products.uploadImage) send multipart/form-data. Pass the file as a File (or Blob with a type); the other fields are sent as form fields.

Errors

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

Webhooks

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

Regenerate

From this repository: