> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build on OmniCommerce marketplace-PIM rails with REST, MCP, CLI, and webhooks.

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

## Prerequisites

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

## Authenticate

```http theme={null}
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](https://docs.omnicommerce.ai/authentication.md).

## Core workflow

```mermaid theme={null}
flowchart LR
  A[Create / upsert product] --> B[Enrich / evaluate]
  B --> C[Publish / sync]
  C --> D[Monitor AI Shelf Share]
  D --> E[Webhooks / jobs]
```

### 1. Create or upsert a product

```bash theme={null}
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`:

```json theme={null}
{
  "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`](https://docs.omnicommerce.ai/api-reference/developer-platform/list-connected-marketplaces), 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:

```http theme={null}
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:

```json theme={null}
{
  "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:

```http theme={null}
POST /api/v1/jobs/{jobId}/cancel
```

### 3. Publish, delist, and sync

```http theme={null}
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.

```bash theme={null}
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](https://docs.omnicommerce.ai/api-reference.md) · [Catalog updates](https://docs.omnicommerce.ai/guides/catalog-updates.md) · [Bulk import](https://docs.omnicommerce.ai/guides/bulk-product-import.md) |
| Orders | List workspace orders; create/patch agentic orders | [Orders guide](https://docs.omnicommerce.ai/guides/orders.md) |
| Uploads | Knowledge base documents and product gallery images (multipart) | [Knowledge base](https://docs.omnicommerce.ai/guides/knowledge-base.md) · [Product images](https://docs.omnicommerce.ai/guides/product-images.md) |
| Fulfillment | Ship, cancel, shipping labels, and tracking for marketplace orders | [Order fulfillment guide](https://docs.omnicommerce.ai/guides/order-fulfillment.md) |
| Reviews | Read reviews, reply to buyers, draft replies with AI | [Reviews guide](https://docs.omnicommerce.ai/guides/reviews.md) |
| Analytics | One route per dashboard: growth, traffic, products, ads, profit | [Analytics guide](https://docs.omnicommerce.ai/guides/analytics.md) |
| Promotions | Central promos, product assignment, marketplace sync | [Promotions guide](https://docs.omnicommerce.ai/guides/promotions.md) |
| Campaigns | Briefs, offer windows, and marketplace campaign runs | [Campaigns guide](https://docs.omnicommerce.ai/guides/campaigns.md) |
| Price books | Channel list-price markup without changing canonical prices | [Price books guide](https://docs.omnicommerce.ai/guides/price-books.md) |
| Looks | AI-styled product sets and preview jobs | [API reference](https://docs.omnicommerce.ai/api-reference.md) |
| Evaluate | Score SKU readiness for agentic commerce | `POST /api/v1/evaluate` |
| Ghost mannequin | Remove mannequins from product photos | [Guide](https://docs.omnicommerce.ai/guides/ghost-mannequin.md) |
| 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](https://docs.omnicommerce.ai/webhooks/overview.md) · `GET/POST /api/v1/webhooks` |
| AOPs | Execute saved agent operating procedures | [AOP guide](https://docs.omnicommerce.ai/guides/aops.md) · `POST /api/v1/aop/{aopId}/execute` |
| Omni agent | Wait for the general agent, or start a run and poll it | [Agent guide](https://docs.omnicommerce.ai/guides/agent.md) · `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](https://docs.omnicommerce.ai/guides/mcp.md).

## TypeScript SDK

```ts theme={null}
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](https://docs.omnicommerce.ai/sdk/typescript.md).

## Python SDK

```python theme={null}
import os
from omnicommerce import Omni

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

See [Python SDK](https://docs.omnicommerce.ai/sdk/python.md).

## CLI

```bash theme={null}
npm install -g @omni-commerce/cli
omni auth login --api-key "$OMNI_API_KEY"
omni products list --q lamp
```

See [Omni CLI](https://docs.omnicommerce.ai/cli/omni-cli.md). The in-repo helper `yarn omni evaluate --product-id PRODUCT_ID` remains for local developer-platform scripts.

## Next steps

> **[Interactive API reference](https://docs.omnicommerce.ai/api-reference.md)**
>
> Try endpoints with the Mintlify playground.

> **[Orders guide](https://docs.omnicommerce.ai/guides/orders.md)**
>
> Filters, agentic create, and pricing fields.

> **[MCP reference](https://docs.omnicommerce.ai/guides/mcp.md)**
>
> JSON-RPC methods and tool contracts.

> **[Authentication](https://docs.omnicommerce.ai/authentication.md)**
>
> Scopes, OAuth, and session rules.

> **[Webhooks](https://docs.omnicommerce.ai/webhooks/overview.md)**
>
> Subscribe to product, order, return, settlement, and look events.

> **[AOP API](https://docs.omnicommerce.ai/guides/aops.md)**
>
> Execute saved operating procedures and poll thread status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.