# OmniCommerce

> Developer documentation for OmniCommerce REST APIs, MCP tools, and agent integrations.

- [OmniCommerce Docs](https://docs.omnicommerce.sg/index.md): Developer documentation for OmniCommerce REST APIs, MCP tools, and agent integrations.
- [Quickstart](https://docs.omnicommerce.sg/quickstart.md): Build on OmniCommerce marketplace-PIM rails with REST, MCP, CLI, and webhooks.
- [Authentication](https://docs.omnicommerce.sg/authentication.md): API keys, OAuth client credentials, scopes, and session auth for OmniCommerce APIs.
- [Orders API](https://docs.omnicommerce.sg/guides/orders.md): List, create, and patch workspace and agentic orders.
- [Settlements API](https://docs.omnicommerce.sg/guides/settlements.md): Apply marketplace fees, credits, settlement status, and order-level finance evidence.
- [Promotions API](https://docs.omnicommerce.sg/guides/promotions.md): Manage central promotions, product assignments, and marketplace sync.
- [Price Books API](https://docs.omnicommerce.sg/guides/price-books.md): Manage marketplace channel list-price markup rules.
- [Bulk Product Import API](https://docs.omnicommerce.sg/guides/bulk-product-import.md): Queue CSV bulk product imports and poll job status.
- [Ghost Mannequin API](https://docs.omnicommerce.sg/guides/ghost-mannequin.md): Remove mannequins from product photos via the image API.
- [MCP](https://docs.omnicommerce.sg/mcp.md): OmniCommerce Model Context Protocol server: transport, JSON-RPC methods, and tool contracts.
- [API Reference](https://docs.omnicommerce.sg/api-reference.md): Interactive OpenAPI reference for OmniCommerce public and authenticated developer APIs.
- [API Root](https://docs.omnicommerce.sg/api-reference/commerce/api-root.md): Public API discovery root. Merchant payments are handled by organization-scoped checkout session endpoints.
- [API v1 Root](https://docs.omnicommerce.sg/api-reference/commerce/api-v1-root.md): Public API v1 discovery root. Merchant payments are handled by organization-scoped checkout session endpoints.
- [Create Agentic Checkout Session](https://docs.omnicommerce.sg/api-reference/agentic-checkout/create-agentic-checkout-session.md): Create a merchant-fulfilled checkout session, reserve inventory, and return rail-specific payment requirements. Requires an OAuth client token with `checkout:write`.
- [Get Agentic Checkout Session](https://docs.omnicommerce.sg/api-reference/agentic-checkout/get-agentic-checkout-session.md): Fetch the current checkout session, cart items, totals, payment requirements, and linked order when completed.
- [Replace Agentic Checkout Session Fields](https://docs.omnicommerce.sg/api-reference/agentic-checkout/replace-agentic-checkout-session-fields.md): UCP-compatible update method for cart/contact fields. The current implementation applies provided fields and leaves omitted fields unchanged. Requires `checkout:write`.
- [Update Agentic Checkout Session](https://docs.omnicommerce.sg/api-reference/agentic-checkout/update-agentic-checkout-session.md): Update cart/contact fields, recompute totals, and refresh inventory reservations before payment. Requires `checkout:write`.
- [Cancel Agentic Checkout Session](https://docs.omnicommerce.sg/api-reference/agentic-checkout/cancel-agentic-checkout-session.md): Cancel a ready-for-payment checkout session and release reserved inventory. This operation is exposed for UCP REST clients and requires `checkout:write`.
- [Complete Agentic Checkout Session](https://docs.omnicommerce.sg/api-reference/agentic-checkout/complete-agentic-checkout-session.md): Settle the selected rail and create a native `agentic` order. Settlement failures return 402 and leave the session in `ready_for_payment`.
- [Compare Public Products](https://docs.omnicommerce.sg/api-reference/public-agent/compare-public-products.md): Compare 2 to 10 public products side-by-side across price, ACO readiness, marketplace coverage, and inventory.
- [List Public Merchants](https://docs.omnicommerce.sg/api-reference/public-agent/list-public-merchants.md): Discover merchants with public products available through OmniCommerce's public agent APIs.
- [Get Merchant LLM Feed](https://docs.omnicommerce.sg/api-reference/public-agent/get-merchant-llm-feed.md): Return a plain-text, LLM-optimized merchant feed keyed by website domain.
- [Get Public Merchant Manifest](https://docs.omnicommerce.sg/api-reference/public-agent/get-public-merchant-manifest.md): Return machine-readable capability and endpoint metadata for a single public merchant.
- [List Public Merchant Products](https://docs.omnicommerce.sg/api-reference/public-agent/list-public-merchant-products.md): Browse a single merchant's public product feed with optional marketplace and localization filters.
- [Search Within Public Merchant Catalog](https://docs.omnicommerce.sg/api-reference/public-agent/search-within-public-merchant-catalog.md): Search within a single merchant's public product feed using the same filter model as the cross-merchant search API.
- [Search Public Merchant Products](https://docs.omnicommerce.sg/api-reference/public-agent/search-public-merchant-products.md): Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.
- [Search Public Merchant Products](https://docs.omnicommerce.sg/api-reference/public-agent/search-public-merchant-products-1.md): Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.
- [Evaluate SKU Readiness](https://docs.omnicommerce.sg/api-reference/developer-platform/evaluate-sku-readiness.md): Score a persisted product or inline SKU payload for agentic commerce readiness, engine eligibility, and recommended fixes.
- [Generate Ghost Mannequin Image](https://docs.omnicommerce.sg/api-reference/developer-platform/generate-ghost-mannequin-image.md): Remove the visible mannequin from a product photo and return the generated image URL. The source image must be an HTTP(S) URL; data URIs are rejected. Authenticate with an OmniCommerce API key that has the `catalog:enrich` scope.
- [Get Developer Job Status](https://docs.omnicommerce.sg/api-reference/developer-platform/get-developer-job-status.md): Fetch shared async status for developer-platform operations, including product workflow jobs, bulk CSV import jobs, Look generation jobs, import jobs, enrichment jobs, and sync jobs.
- [Cancel Developer Job](https://docs.omnicommerce.sg/api-reference/developer-platform/cancel-developer-job.md): Request cancellation for a running or pending developer job. Supports product workflow jobs returned by POST /api/v1/products, bulk CSV import jobs returned by POST /api/v1/products/bulk-import, and Look generation jobs returned by POST /api/v1/looks. Completed or failed jobs are returned with their…
- [Recommend Marketplace Product Categories](https://docs.omnicommerce.sg/api-reference/developer-platform/recommend-marketplace-product-categories.md): Suggest best-fit marketplace categories and category attribute values for a persisted product using semantic taxonomy search. Authenticate with an OmniCommerce API key as `Authorization: Bearer omni_sk_...`.
- [List Connected Marketplaces](https://docs.omnicommerce.sg/api-reference/developer-platform/list-connected-marketplaces.md): List connected marketplace stores for the authenticated organization. Results are scoped to the API key organization unless `organizationId` is supplied for session-authenticated calls.
- [Run AI Shelf Share Monitor](https://docs.omnicommerce.sg/api-reference/developer-platform/run-ai-shelf-share-monitor.md): Queue AI Shelf Share replay/monitoring for a product, query, or organization catalog.
- [Publish Product](https://docs.omnicommerce.sg/api-reference/developer-platform/publish-product.md): Queue marketplace publish jobs for a product by productId. OmniCommerce publishes to the marketplaces already enabled on the product and uses the product's store selection or a single/default connected store.
- [Sync Product Commercial Fields](https://docs.omnicommerce.sg/api-reference/developer-platform/sync-product-commercial-fields.md): Update price, sale price, or stock quantity in OmniCommerce and queue marketplace sync workers where applicable.
- [List Developer Webhooks](https://docs.omnicommerce.sg/api-reference/developer-platform/list-developer-webhooks.md): List configured developer webhook subscriptions for the authenticated organization.
- [Create Developer Webhook](https://docs.omnicommerce.sg/api-reference/developer-platform/create-developer-webhook.md): Create a developer webhook subscription for product, order, look, and related commerce events.
- [List Looks](https://docs.omnicommerce.sg/api-reference/looks/list-looks.md): List AI-styled product Looks for the authenticated organization, newest first. Use query parameters for search, status filtering, and pagination.
- [Create Look](https://docs.omnicommerce.sg/api-reference/looks/create-look.md): Create a Look from existing catalog products and queue AI image generation for a fast preview. The response is asynchronous: poll `GET /api/v1/jobs/{jobId}?organizationId={organizationId}` until the `look_...` job completes, then fetch the generated Look with `GET /api/v1/looks/{lookId}`.
- [Get Look](https://docs.omnicommerce.sg/api-reference/looks/get-look.md): Fetch a single Look by ID, including the generated hero image URL and the shoppable product cards used in the Look.
- [Revoke Access Token](https://docs.omnicommerce.sg/api-reference/oauth/revoke-access-token.md): Revoke an OAuth bearer access token using client_secret_post authentication.
- [Get Access Token](https://docs.omnicommerce.sg/api-reference/oauth/get-access-token.md): Exchange client credentials for an access token using OAuth 2.0 client_credentials grant. Tokens are valid for 1 hour.
- [List Orders](https://docs.omnicommerce.sg/api-reference/orders/list-orders.md): List orders for the authenticated organization using the same filters, sorting, and pagination semantics as the workspace Orders listing page. Requires `orders:read`.
- [Create Order](https://docs.omnicommerce.sg/api-reference/orders/create-order.md): Create a native `agentic` order with line items. Supports `status`, `currency`, `country`, `totalAmount`, and per-line `price` / `unitPrice` / `paidPrice` / `costPrice`. When `productId` is provided, missing price/currency may resolve from the product catalog; explicit `costPrice` upserts `product_d…
- [Update Order](https://docs.omnicommerce.sg/api-reference/orders/update-order.md): Update a native **agentic** order. Supports external order identifiers, status, currency, country, totalAmount, shippingFee, discountAmount, metadata, orderCreatedAt, and line-item upserts (externalOrderItemId, price / unitPrice / paidPrice / costPrice / currency / status / quantity). Matching exter…
- [Create Organization](https://docs.omnicommerce.sg/api-reference/organizations/create-organization.md): Create a new organization for the signed-in user. This endpoint uses first-party session authentication because API keys are scoped to an existing organization.
- [List Price Book Rules](https://docs.omnicommerce.sg/api-reference/price-books/list-price-book-rules.md): List marketplace price book rules for the authenticated organization. Rules apply markup percent to canonical list price at publish/catalog time by platform (and optional store/country). Requires `price_books:read`.
- [Create Price Book Rule](https://docs.omnicommerce.sg/api-reference/price-books/create-price-book-rule.md): Create a marketplace price book rule that marks up canonical list price for a platform (optional store/country). Does not change Omni product prices. Requires `price_books:write`.
- [Get Price Book Rule](https://docs.omnicommerce.sg/api-reference/price-books/get-price-book-rule.md): Fetch one marketplace price book rule by ID. Requires `price_books:read`.
- [Delete Price Book Rule](https://docs.omnicommerce.sg/api-reference/price-books/delete-price-book-rule.md): Delete a marketplace price book rule by ID. Requires `price_books:write`.
- [Update Price Book Rule](https://docs.omnicommerce.sg/api-reference/price-books/update-price-book-rule.md): Update store, country, markup, rounding, currency, or enabled flag for a price book rule. Platform cannot be changed; create a new rule instead. Requires `price_books:write`.
- [Preview Channel List Price](https://docs.omnicommerce.sg/api-reference/price-books/preview-channel-list-price.md): Compute channel list price from a canonical list price using matching enabled rules (or a forced ruleId). Requires `price_books:read`.
- [List Products](https://docs.omnicommerce.sg/api-reference/products/list-products.md): List products for the authenticated organization with optional filters and pagination. Supports API key Bearer token authentication.
- [Create and Enrich Product](https://docs.omnicommerce.sg/api-reference/products/create-and-enrich-product.md): Queue a single-product create/enrich workflow for the authenticated organization. The request mirrors bulk product import for one product: `product` contains developer-supplied fields, arbitrary extra fields are preserved for enrichment context, SKU is the unique upsert identifier, externally hosted…
- [Get Product](https://docs.omnicommerce.sg/api-reference/products/get-product.md): Retrieve a single product by ID for the authenticated organization. Supports API key Bearer token authentication. The response includes generated Agentic Commerce Optimization (ACO) profile metadata, FAQs, localization content, intent queries, cultural notes, signals, sources, and claims when presen…
- [Delete Product](https://docs.omnicommerce.sg/api-reference/products/delete-product.md): Soft-delete a product by ID. The product will be marked as deleted but not permanently removed. Call again on a deleted product to permanently delete it. Supports API key Bearer token authentication.
- [Update Product](https://docs.omnicommerce.sg/api-reference/products/update-product.md): Update an existing product by ID. Only provided fields will be updated. Supports API key Bearer token authentication.
- [Bulk Import Products from CSV](https://docs.omnicommerce.sg/api-reference/products/bulk-import-products-from-csv.md): Queue a bulk CSV product import for the authenticated organization. Upload a CSV file with multipart/form-data or send JSON with inline `csvText` or a stored `documentId`. The API creates import rows, queues enrichment and product writes through Inngest, and returns a `bulk_...` job ID to poll with…
- [List Promotions](https://docs.omnicommerce.sg/api-reference/promotions/list-promotions.md): List central promotions for the authenticated organization with filters and offset pagination matching the workspace Promotions listing. Requires `promotions:read`.
- [Create Promotion](https://docs.omnicommerce.sg/api-reference/promotions/create-promotion.md): Create a central promotion targeting connected stores. Requires `promotions:write`. Fixed-amount discounts resolve currency from the selected store countries.
- [Get Promotion](https://docs.omnicommerce.sg/api-reference/promotions/get-promotion.md): Fetch one promotion by ID, including effective status. Requires `promotions:read`.
- [Delete Promotion](https://docs.omnicommerce.sg/api-reference/promotions/delete-promotion.md): Delete a promotion by ID. Requires `promotions:write`.
- [Update Promotion](https://docs.omnicommerce.sg/api-reference/promotions/update-promotion.md): Update promotion fields (name, discount, schedule, status, stores). Requires `promotions:write`.
- [List Promotion Assignments](https://docs.omnicommerce.sg/api-reference/promotions/list-promotion-assignments.md): List products assigned to a promotion. Requires `promotions:read`.
- [Assign Products to Promotion](https://docs.omnicommerce.sg/api-reference/promotions/assign-products-to-promotion.md): Assign one or more products to a promotion. Creates pending marketplace sync rows; call sync after assign. Requires `promotions:write`.
- [Unassign Products from Promotion](https://docs.omnicommerce.sg/api-reference/promotions/unassign-products-from-promotion.md): Remove product assignments and queue marketplace teardown. Requires `promotions:write`.
- [Sync Promotion to Marketplaces](https://docs.omnicommerce.sg/api-reference/promotions/sync-promotion-to-marketplaces.md): Queue marketplace push for assigned products (Shopee discount, Lazada voucher, TikTok activity, Shopify automatic discount). Requires `promotions:write`.
- [Apply Settlements](https://docs.omnicommerce.sg/api-reference/settlements/apply-settlements.md): Apply marketplace-agnostic settlement lines to existing orders. Writes marketplace financial evidence, projects **settled** rows into the order finance ledger, and recomputes Payment received when a marketplace formula exists (Zalora today). Pending, reversed, and voided rows stay on evidence only a…
- [Create UCP Checkout Session](https://docs.omnicommerce.sg/api-reference/ucp/create-ucp-checkout-session.md): Create a UCP shopping checkout session against the authenticated organization. The facade translates UCP line items to native agentic checkout sessions, reserves inventory, and returns a UCP checkout resource. Requires `UCP-Agent` and OAuth `checkout:write`.
- [Get UCP Checkout Session](https://docs.omnicommerce.sg/api-reference/ucp/get-ucp-checkout-session.md): Fetch the current UCP checkout resource for a native agentic checkout session. Requires `UCP-Agent` and bearer authentication.
- [Replace UCP Checkout Session Fields](https://docs.omnicommerce.sg/api-reference/ucp/replace-ucp-checkout-session-fields.md): UCP-compatible update method. Current behavior matches PATCH: provided fields are applied and omitted fields remain unchanged. Requires `UCP-Agent` and OAuth `checkout:write`.
- [Update UCP Checkout Session](https://docs.omnicommerce.sg/api-reference/ucp/update-ucp-checkout-session.md): Update UCP cart, buyer, fulfillment, or payment rail fields. Provided fields are applied to the native checkout session and inventory reservations are refreshed when line items change. Requires `UCP-Agent` and OAuth `checkout:write`.
- [Cancel UCP Checkout Session](https://docs.omnicommerce.sg/api-reference/ucp/cancel-ucp-checkout-session.md): Cancel a ready-for-payment UCP checkout session and release reserved inventory. Requires `UCP-Agent` and OAuth `checkout:write`.
- [Complete UCP Checkout Session](https://docs.omnicommerce.sg/api-reference/ucp/complete-ucp-checkout-session.md): Settle the selected rail and create a native `agentic` order. Settlement failures return HTTP 402 with the checkout still ready for payment. Requires `UCP-Agent` and OAuth `checkout:write`.
- [Get UCP Order](https://docs.omnicommerce.sg/api-reference/ucp/get-ucp-order.md): Fetch the native OmniCommerce order created by a completed UCP checkout session. Only `agentic` orders are exposed through this facade.
- [Changelog](https://docs.omnicommerce.sg/changelog.md): Product and API updates for OmniCommerce.

## OpenAPI Specs

- [openapi](/openapi.json)