Quickstart

Use REST, MCP, CLI, and webhooks to create enriched catalog data, evaluate agentic readiness, sync commercial fields, and monitor AI Shelf Share.

Prerequisites

An OmniCommerce organization
An API key from organization settings (omni_sk_...)
Base URL https://omnicommerce.sg (or your local/dev host)

Authenticate

Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

API keys are bound to a single organization. You do not need to send organizationId for API-key requests. Session-authenticated browser calls must include organizationId in the query or body. Full details: Authentication.

Core workflow

1. Create or upsert a product

curl -X POST "https://omnicommerce.sg/api/v1/products" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "sku": "SKU-100",
      "title": "Sample product",
      "price": 29.9,
      "currency": "SGD",
      "images": ["https://cdn.example.com/product.jpg"]
    }
  }'

product.images accepts only an array of HTTP(S) URL strings. workflow.enrich, workflow.autoAssignMarketplaceTaxonomy, and workflow.aco all default to false, including when workflow is omitted. Product creation does not start ACO generation unless workflow.aco is true. To enrich the product and assign marketplace categories, brands, and attributes automatically, send both switches as true:

{
  "product": {
    "sku": "LAMP-100",
    "title": "Adjustable LED desk lamp",
    "description": "An adjustable LED desk lamp with three brightness levels.",
    "brand": "Acme",
    "price": 29.9,
    "currency": "SGD",
    "images": ["https://cdn.example.com/lamp.jpg"],
    "marketplaces": {
      "shopee": {
        "enabled": true,
        "country": "sg",
        "storeId": "YOUR_CONNECTED_SHOPEE_STORE_ID"
      }
    }
  },
  "targetMarketplaces": ["shopee"],
  "targetCountries": ["sg"],
  "workflow": {
    "enrich": true,
    "autoAssignMarketplaceTaxonomy": true
  }
}

Replace the image URL with your product image. Retrieve connected stores with GET /api/v1/marketplaces/connected, then copy storeId from the matching entry in connectedMarketplaces into product.marketplaces.<platform>.storeId. Marketplace and country targets can also be inferred from product.marketplaces when the top-level target arrays are omitted. Each platform stores one store and country assignment on the product: its product.marketplaces country takes precedence, otherwise the first target country is used. Both product.marketplaces.<platform>.country and targetCountries[] use the ISO 3166-1 alpha-2 country-code enum, for example sg, my, or us. Codes are trimmed and normalized to lowercase. Country names such as Singapore, custom values, and global return HTTP 400. Country is not inferred from storeId. This runs asynchronously without human approval prompts. Omni saves the enriched product draft and resolved marketplace taxonomy together. On SKU upserts, existing assigned categories, brands, and attributes are preserved; automatic assignment fills missing values. The taxonomy switch takes effect during enrichment, so enable both switches for automatic assignment. Low-confidence matches are applied with warnings. If no category match is found or required attributes are missing, the draft is still saved and the job reports warnings. Review result.warnings and proposal.marketplaces from the job status response before publishing. Product creation does not publish the listing to the marketplace.

2. Poll async jobs

Many write paths return a job ID. Poll:

GET /api/v1/jobs/{jobId}

Product creation, image ingestion, enrichment, and automatic taxonomy assignment run in the same product workflow job. Taxonomy assignment does not require a second job. ACO generation is a separate asynchronous job and stays off unless workflow.aco is true. When that job is queued, poll result.geoJobId using the same job status endpoint. An existing active ACO job can be reused. To queue ACO with enrichment, send:

{
  "workflow": {
    "enrich": true,
    "autoAssignMarketplaceTaxonomy": true,
    "aco": true
  }
}

Optional workflow.enableMannequinRemoval: true can queue additional image-processing jobs. The product workflow reports their IDs in result.imageProcessing.ghostMannequinQueuedJobIds. Cancel with:

POST /api/v1/jobs/{jobId}/cancel

3. Publish, delist, and sync

POST /api/v1/products/{productId}/publish
GET  /api/v1/products/{productId}/listings
POST /api/v1/products/{productId}/delist
POST /api/v1/sync

After publishing, poll GET /api/v1/products/{productId}/listings. Each marketplace shows whether the listing is live, its buyer-facing URL, and the latest publish attempt with any rejection details from the marketplace. Delist removes marketplace listings. It does not delete the OmniCommerce product. Omit marketplaces to delist every channel that already has a listing, or name a subset. Shopee, Lazada, TikTok Shop, Shopify, WhatsApp, Zalora, Amazon, and eBay use the same endpoint. A named marketplace with no listing is rejected. The response jobId is polled with GET /api/v1/jobs/{jobId} until data.status is succeeded, partial, or failed. 202 means the job was queued.

curl --request POST \
  --url "https://omnicommerce.sg/api/v1/products/PRODUCT_UUID/delist" \
  --header "Authorization: Bearer $OMNI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "marketplaces": ["shopee", "lazada"] }'

API products

Product	What it does	Start here
Products	Create/upsert, variants, price, cost, inventory, publish, delist	API · Catalog updates · Bulk import
Orders	List workspace orders; create/patch agentic orders	Orders guide
Uploads	Knowledge base documents and product gallery images (multipart)	Knowledge base · Product images
Fulfillment	Ship, cancel, shipping labels, and tracking for marketplace orders	Order fulfillment guide
Reviews	Read reviews, reply to buyers, draft replies with AI	Reviews guide
Analytics	One route per dashboard: growth, traffic, products, ads, profit	Analytics guide
Promotions	Central promos, product assignment, marketplace sync	Promotions guide
Campaigns	Briefs, offer windows, and marketplace campaign runs	Campaigns guide
Price books	Channel list-price markup without changing canonical prices	Price books guide
Looks	AI-styled product sets and preview jobs	API reference
Evaluate	Score SKU readiness for agentic commerce	`POST /api/v1/evaluate`
Ghost mannequin	Remove mannequins from product photos	Guide
Agentic checkout	Merchant-fulfilled checkout sessions	`POST /api/v1/checkout-sessions`
UCP	Universal Commerce Protocol shopping	`POST /ucp/v1/checkout-sessions`
Monitor	AI Shelf Share monitoring and replay	`POST /api/v1/monitor`
Webhooks	Product, order, return, settlement, and look delivery	Webhook guide · `GET/POST /api/v1/webhooks`
AOPs	Execute saved agent operating procedures	AOP guide · `POST /api/v1/aop/{aopId}/execute`
Omni agent	Wait for the general agent, or start a run and poll it	Agent guide · `POST /api/v1/agents/general/invoke`

MCP tools

Public catalog discovery tools for tool-calling agents:

omni_search_catalog
omni_match_intent
omni_discover_geo

Seller evaluate/sync/monitor stay on authenticated REST. See MCP.

TypeScript SDK

import { OmniClient } from "@omni-commerce/sdk";

const client = new OmniClient({ apiKey: process.env.OMNI_API_KEY });
const products = await client.products.list({ q: "lamp" });

See TypeScript SDK.

Python SDK

import os
from omnicommerce import Omni

client = Omni(api_key=os.environ["OMNI_API_KEY"])
products = client.products.list(q="lamp")

See Python SDK.

CLI

npm install -g @omni-commerce/cli
omni auth login --api-key "$OMNI_API_KEY"
omni products list --q lamp

See Omni CLI. The in-repo helper yarn omni evaluate --product-id PRODUCT_ID remains for local developer-platform scripts.

Next steps

Interactive API reference

Try endpoints with the Mintlify playground.

Orders guide

Filters, agentic create, and pricing fields.

MCP reference

JSON-RPC methods and tool contracts.

Authentication

Scopes, OAuth, and session rules.

Webhooks

Subscribe to product, order, return, settlement, and look events.

AOP API

Execute saved operating procedures and poll thread status.

Get started

Guides

SDK

CLI

Webhooks

MCP

Prerequisites

Authenticate

Core workflow

1. Create or upsert a product

2. Poll async jobs

3. Publish, delist, and sync

API products

MCP tools

TypeScript SDK

Python SDK

CLI

Next steps

Interactive API reference

Orders guide

MCP reference

Authentication

Webhooks

AOP API

​Prerequisites

​Authenticate

​Core workflow

​1. Create or upsert a product

​2. Poll async jobs

​3. Publish, delist, and sync

​API products

​MCP tools

​TypeScript SDK

​Python SDK

​CLI

​Next steps

Interactive API reference

Orders guide

MCP reference

Authentication

Webhooks

AOP API

Prerequisites

Authenticate

Core workflow

1. Create or upsert a product

2. Poll async jobs

3. Publish, delist, and sync

API products

MCP tools

TypeScript SDK

Python SDK

CLI

Next steps