# OmniCommerce

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

- [OmniCommerce Docs](https://docs.omnicommerce.ai/index.md): Developer documentation for OmniCommerce REST APIs, MCP tools, and agent integrations.
- [Quickstart](https://docs.omnicommerce.ai/quickstart.md): Build on OmniCommerce marketplace-PIM rails with REST, MCP, CLI, and webhooks.
- [Authentication](https://docs.omnicommerce.ai/authentication.md): API keys, OAuth client credentials, scopes, and session auth for OmniCommerce APIs.
- [Catalog price, cost, and inventory](https://docs.omnicommerce.ai/guides/catalog-updates.md): Update OmniCommerce catalog selling prices, source-currency cost, and inventory. Price and inventory can optionally sync to marketplaces; cost never does.
- [Storefront product discovery](https://docs.omnicommerce.ai/guides/storefront-product-discovery.md): Search new catalog additions, budgets, imported ratings, availability, and product options in storefront chat and public search.
- [Product image uploads](https://docs.omnicommerce.ai/guides/product-images.md): Upload image files straight into a product's or variant's gallery.
- [Knowledge base uploads](https://docs.omnicommerce.ai/guides/knowledge-base.md): Upload documents to the organization knowledge base that agents and enrichment search.
- [Orders API](https://docs.omnicommerce.ai/guides/orders.md): List, retrieve, create, and patch workspace and agentic orders.
- [Order fulfillment API](https://docs.omnicommerce.ai/guides/order-fulfillment.md): Ship, cancel, print shipping labels, and update tracking for marketplace orders.
- [Reviews API](https://docs.omnicommerce.ai/guides/reviews.md): Read marketplace product reviews, send replies, or generate replies with AI.
- [Analytics API](https://docs.omnicommerce.ai/guides/analytics.md): One route per workspace analytics dashboard: growth, traffic, products, pricing, ads, orders, video, profit, AI traffic, stores, and reports.
- [Settlements API](https://docs.omnicommerce.ai/guides/settlements.md): Read normalized settlement outcomes or apply marketplace finance evidence.
- [Promotions API](https://docs.omnicommerce.ai/guides/promotions.md): Manage central promotions, product assignments, and marketplace delivery.
- [Campaigns API](https://docs.omnicommerce.ai/guides/campaigns.md): Create, revise, and run marketplace campaign plans.
- [Price Books API](https://docs.omnicommerce.ai/guides/price-books.md): Manage marketplace channel list-price rules: buyer formulas or markup percent.
- [Bulk Product Import API](https://docs.omnicommerce.ai/guides/bulk-product-import.md): Import JSON or CSV products asynchronously, then review generated changes.
- [Import and queue product enrichment](https://docs.omnicommerce.ai/guides/import-and-enrich.md): Import selected Zalora products and queue AI enrichment over the developer API without an AOP.
- [Ghost Mannequin API](https://docs.omnicommerce.ai/guides/ghost-mannequin.md): Remove mannequins from product photos via the image API.
- [AOP API](https://docs.omnicommerce.ai/guides/aops.md): Create, configure, execute, retry, and poll Agent Operating Procedures over REST.
- [Omni agent API](https://docs.omnicommerce.ai/guides/agent.md): Call the general Omni agent synchronously, or start a run and poll it.
- [Run Windmill scripts](https://docs.omnicommerce.ai/guides/scripts.md): Run scripts directly over HTTP, pass large product ID lists without an AOP, and track job results.
- [TypeScript SDK](https://docs.omnicommerce.ai/sdk/typescript.md): Typed JavaScript/TypeScript client for every OmniCommerce REST endpoint.
- [Embedded assistant chat](https://docs.omnicommerce.ai/sdk/chat.md): Use OmniCommerce chat inside React applications and websites.
- [Python SDK](https://docs.omnicommerce.ai/sdk/python.md): Sync and async Python client for every OmniCommerce REST endpoint.
- [SDK errors](https://docs.omnicommerce.ai/sdk/errors.md): Typed HTTP errors thrown by the TypeScript SDK, the Python SDK, and the Omni CLI.
- [TypeScript SDK](https://docs.omnicommerce.ai/guides/js-sdk.md): Typed JavaScript/TypeScript client for every OmniCommerce REST endpoint.
- [Omni CLI](https://docs.omnicommerce.ai/cli/omni-cli.md): Terminal client for every OmniCommerce REST operation, generated from OpenAPI.
- [CLI reference](https://docs.omnicommerce.ai/cli/reference.md): Every Omni CLI command generated from the public OpenAPI spec.
- [Webhooks](https://docs.omnicommerce.ai/webhooks/overview.md): Consume product, order, return, settlement, look, and review events from OmniCommerce.
- [Webhook event catalog](https://docs.omnicommerce.ai/webhooks/event-catalog.md): Every event accepted by an OmniCommerce developer webhook subscription.
- [Product webhooks](https://docs.omnicommerce.ai/webhooks/products.md): Catalog lifecycle, delist, price, and inventory event payloads.
- [Order webhooks](https://docs.omnicommerce.ai/webhooks/orders.md): The unified OmniCommerce order event contract.
- [Return webhooks](https://docs.omnicommerce.ai/webhooks/returns.md): PII-free marketplace return and refund outcomes with SKU-level lines.
- [Settlement webhooks](https://docs.omnicommerce.ai/webhooks/settlements.md): Receive normalized marketplace fees, net settlement, and reconciliation changes independently from order lifecycle events.
- [Account statement webhooks](https://docs.omnicommerce.ai/webhooks/account-statements.md): Statement changes, reconciliation and sync outcomes across marketplaces.
- [Look webhooks](https://docs.omnicommerce.ai/webhooks/looks.md): Shoppable-look creation and deletion event payloads.
- [Review webhooks](https://docs.omnicommerce.ai/webhooks/reviews.md): Marketplace product review lifecycle events.
- [Marketplace order mapping](https://docs.omnicommerce.ai/webhooks/marketplace-mapping.md): How marketplace pushes map to unified order and settlement contracts.
- [MCP server](https://docs.omnicommerce.ai/guides/mcp.md): OmniCommerce Model Context Protocol server: transport, JSON-RPC methods, and tool contracts.
- [API Reference](https://docs.omnicommerce.ai/api-reference.md): Interactive OpenAPI reference for OmniCommerce public and authenticated developer APIs.
- [Invoke the Omni agent](https://docs.omnicommerce.ai/api-reference/agents/invoke-the-omni-agent.md): Run the general Omni agent and wait until it completes, pauses for approval, or fails. Requires `agents:invoke`.
- [Start an Omni agent run](https://docs.omnicommerce.ai/api-reference/agents/start-an-omni-agent-run.md): Queue the general Omni agent and return immediately with the run in `queued` state. Poll the URL in the `Location` header (`GET /api/v1/agents/general/runs/{runId}`), honoring `Retry-After`. Requires `agents:invoke`. The request body matches invoke.
- [Get an Omni agent run](https://docs.omnicommerce.ai/api-reference/agents/get-an-omni-agent-run.md): Read a queued, running, completed, paused, or failed Omni agent run. Requires `agents:invoke`.
- [Get Ads Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-ads-analytics.md): Ad spend, attributed sales, ROAS, and ACOS over the last 28 days, and per-product sales and ad metrics for today, yesterday, 7-day and 28-day averages, and the same day one and four weeks ago. Matches the Ads page. Requires `analytics:read`.
- [Get AI Traffic Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-ai-traffic-analytics.md): Visits and crawls from AI assistants and search engines: totals, a daily trend, breakdowns by source, route, country, and product, and recent events. Matches the AI Traffic page. Requires `analytics:read`.
- [Get Video and LIVE Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-video-and-live-analytics.md): Views, product clicks, orders, and GMV from shoppable videos and LIVE streams, by day, by content type, and per video. Matches the Video / LIVE page. Requires `analytics:read`.
- [Get Order Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-order-analytics.md): Order KPIs with their change against the previous period, a daily trend, sales by order status and by marketplace, and the top products by net sales. Repeat buyers are counted but not listed. Matches the Orders analysis page. Requires `analytics:read`.
- [Get Growth Overview](https://docs.omnicommerce.ai/api-reference/analytics/get-growth-overview.md): Sales, traffic, and profit KPIs with their change against the previous period, a daily trend, the traffic funnel, sales by channel, top and lagging products, and ranked next actions. Matches the Growth Intelligence overview page. Requires `analytics:read`.
- [Get Pricing Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-pricing-analytics.md): Selling products with their margin, velocity, stock cover, prices, competitor median, and a pricing recommendation. Matches the Pricing page. Requires `analytics:read`.
- [Get Product Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-product-analytics.md): Per-product sales, traffic, price, stock, profit, and ad performance, ranked by net sales, with ranked insights. Pass `productId` for specific products, for example on a product page. Matches the Products page. Requires `analytics:read`.
- [Get Profit Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-profit-analytics.md): Revenue, costs, fees, and profit with a waterfall, cost breakdowns, a daily trend, the most and least profitable products, and products missing a cost price. Session members also need finance access. Matches the P&L Analysis page. Requires `analytics:read`.
- [Get Business Report](https://docs.omnicommerce.ai/api-reference/analytics/get-business-report.md): The management summary: headline KPIs, top products, sales by marketplace, alerts, settlement totals, and data quality. Matches the Business Reports page. Requires `analytics:read`.
- [Get Store Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-store-analytics.md): Seller Centre shop metrics: visitors, page views, followers, the placed, paid, and confirmed buyer funnel, a daily trend, and the app and web split. Matches the Analytics (Seller Centre) page. Requires `analytics:read`.
- [Get Traffic Analytics](https://docs.omnicommerce.ai/api-reference/analytics/get-traffic-analytics.md): Impressions, page views, visitors, add-to-cart, and conversion, with the funnel, a daily trend, products ranked by lost conversion, diagnostics, and the videos that drive traffic. Matches the Traffic page. Requires `analytics:read`.
- [Get AOP configuration](https://docs.omnicommerce.ai/api-reference/aops/get-aop-configuration.md): Retrieve prompt, agent, structured inputs/output, and notification settings. Requires `aops:read`.
- [Overwrite AOP configuration](https://docs.omnicommerce.ai/api-reference/aops/overwrite-aop-configuration.md): Updates AOP configuration. Omitted fields keep their current values. Send `user_notification_configs: null` to clear notification overrides. Requires `aops:write`.
- [Execute an AOP](https://docs.omnicommerce.ai/api-reference/aops/execute-an-aop.md): Start an AOP run and return immediately with a `thread_id`. Poll `GET /api/v1/threads/{thread_id}/status`. Requires `aops:write`.
- [Create AOP](https://docs.omnicommerce.ai/api-reference/aops/create-aop.md): Create an organization-scoped AOP. Use `[[ placeholder ]]` in the prompt for user inputs supplied at execution time. Requires `aops:write`.
- [Retry a failed AOP execution](https://docs.omnicommerce.ai/api-reference/aops/retry-a-failed-aop-execution.md): Looks up a failed AOP thread, then enqueues a new run. Requires `aops:write`.
- [Get Thread Status](https://docs.omnicommerce.ai/api-reference/aops/get-thread-status.md): Poll an AOP execution started by `POST /api/v1/aop/{aopId}/execute`. Requires `aops:read`. Status values are `running`, `completed`, or `failed`.
- [Import BrandsGateway Products](https://docs.omnicommerce.ai/api-reference/developer-platform/import-brandsgateway-products.md): Requires catalog:write and a connected BrandsGateway account. Uses the same parameters and import service as the import_brandsgateway_products tool.
- [Evaluate SKU Readiness](https://docs.omnicommerce.ai/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.ai/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.ai/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, price comparison jobs, and sync jobs.
- [Cancel Developer Job](https://docs.omnicommerce.ai/api-reference/developer-platform/cancel-developer-job.md): Request cancellation for a running or pending developer job.
- [Recommend Marketplace Product Categories](https://docs.omnicommerce.ai/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.ai/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.ai/api-reference/developer-platform/run-ai-shelf-share-monitor.md): Queue AI Shelf Share replay/monitoring for a product, query, or organization catalog.
- [Sync Product Commercial Fields](https://docs.omnicommerce.ai/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 Webhook Events](https://docs.omnicommerce.ai/api-reference/developer-platform/list-webhook-events.md): Pull immutable webhook events for recovery or scheduled reconciliation. Requires `webhooks:manage`. Results are organization-scoped and ordered oldest first; continue with the opaque cursor. This is the pull fallback for a receiver that missed push deliveries.
- [List Developer Webhooks](https://docs.omnicommerce.ai/api-reference/developer-platform/list-developer-webhooks.md): List configured developer webhook subscriptions for the authenticated organization.
- [Create Developer Webhook](https://docs.omnicommerce.ai/api-reference/developer-platform/create-developer-webhook.md): Create a developer webhook subscription for the authenticated organization. The signing secret is returned only once.
- [Get Selected Zalora Import Status](https://docs.omnicommerce.ai/api-reference/developer-platform/get-selected-zalora-import-status.md): Requires catalog:read. Follow the unchanged links.job URL returned by POST. Reads current state once without waiting.
- [Import Selected Zalora Products](https://docs.omnicommerce.ai/api-reference/developer-platform/import-selected-zalora-products.md): Requires catalog:write. Queue an exact import of 1–25 Zalora productSetIds from a connected store. Omit storeId only when one store or one default store is unambiguous.
- [List Campaigns](https://docs.omnicommerce.ai/api-reference/campaigns/list-campaigns.md): List campaigns for the authenticated organization. `stage=all` is the workspace working set: draft and running. Requires `promotions:read`.
- [Create Campaign](https://docs.omnicommerce.ai/api-reference/campaigns/create-campaign.md): Create a draft campaign. `ownerId` and `approverId` must be members of the organization, and every store must already be connected. Requires `promotions:write`.
- [Get Campaign](https://docs.omnicommerce.ai/api-reference/campaigns/get-campaign.md): Read one campaign, including its plan, executions, audit, schedule, and progress. Requires `promotions:read`.
- [Update Campaign](https://docs.omnicommerce.ai/api-reference/campaigns/update-campaign.md): Replace a draft or approved plan, or propose one change to a running plan. Send `expectedRevision` from the last read. Requires `promotions:write`.
- [Act on Campaign](https://docs.omnicommerce.ai/api-reference/campaigns/act-on-campaign.md): Approve, start, end, resume, retry, or decide a proposed live change. Approve, run, resume, and approving a change must be called by the named approver. Requires `promotions:write`.
- [Archive Campaigns](https://docs.omnicommerce.ai/api-reference/campaigns/archive-campaigns.md): Archive campaigns, or restore archived campaigns by id or by the current archived list filters. Requires `promotions:write`.
- [Delete Campaigns](https://docs.omnicommerce.ai/api-reference/campaigns/delete-campaigns.md): Permanently delete archived campaigns by explicit id or by archived list filters. Requires `promotions:write`.
- [Get Campaign Options](https://docs.omnicommerce.ai/api-reference/campaigns/get-campaign-options.md): List the organization members and connected stores a campaign plan can name. Use a member `id` for `ownerId` and `approverId`. Requires `promotions:write`.
- [Export Catalog Items](https://docs.omnicommerce.ai/api-reference/products/export-catalog-items.md): Cursor-page the authenticated organization's product and variant catalog for pricing systems. Requires `catalog:read`.
- [List Products](https://docs.omnicommerce.ai/api-reference/products/list-products.md): List products for the authenticated organization with optional filters and pagination. Authenticate with an API key or OAuth bearer token. The organization is taken from that credential; do not send `organizationId`.
- [Create Product](https://docs.omnicommerce.ai/api-reference/products/create-product.md): Queue a single-product create workflow for the authenticated organization. Product enrichment is disabled by default; set `workflow.enrich` to `true` to enable it.
- [Get Product](https://docs.omnicommerce.ai/api-reference/products/get-product.md): Retrieve a single product by ID for the authenticated organization.
- [Delete Product](https://docs.omnicommerce.ai/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.ai/api-reference/products/update-product.md): Update an existing product by ID. Only provided fields will be updated. Supports API key Bearer token authentication.
- [Update Product Cost](https://docs.omnicommerce.ai/api-reference/products/update-product-cost.md): Set catalog cost for one simple product or variant UUID. Cost is Omni-only and never syncs to marketplaces. Prefer `POST /api/v1/products/cost` for Windmill or other bulk jobs.
- [Delist Product](https://docs.omnicommerce.ai/api-reference/products/delist-product.md): Queue delist for one product on the marketplaces you name. `marketplaces` accepts one or more of shopee, lazada, tiktok, shopify, whatsapp, zalora, amazon, and ebay. Each named marketplace must already have a listing; other channels are left untouched. Omit `marketplaces` to delist every existing li…
- [Upload Product Image](https://docs.omnicommerce.ai/api-reference/products/upload-product-image.md): Upload one image to a product's or variant's gallery as multipart/form-data. Requires `catalog:write`.
- [Update Product Inventory](https://docs.omnicommerce.ai/api-reference/products/update-product-inventory.md): Update canonical on-hand inventory for a simple product or variant UUID. Multi-variant parent products must be updated through their variant IDs. A successful quantity change emits `product.inventory.changed` to matching developer webhook subscriptions.
- [Get Product Listings](https://docs.omnicommerce.ai/api-reference/products/get-product-listings.md): Where a product is listed: each marketplace's store, live or delisted state, item id, buyer-facing URL, and the latest publish attempt with any rejection details. Requires `catalog:read`.
- [Update Product Price](https://docs.omnicommerce.ai/api-reference/products/update-product-price.md): Update the canonical catalog price for a simple product or variant UUID. Multi-variant parent products must be updated through their variant IDs. A successful change emits `product.price.changed` to matching developer webhook subscriptions.
- [Publish Product](https://docs.omnicommerce.ai/api-reference/products/publish-product.md): ### Publishing
- [Bulk Import Products from JSON or CSV](https://docs.omnicommerce.ai/api-reference/products/bulk-import-products-from-json-or-csv.md): Queue a bulk product import for the authenticated organization.
- [Compare Product Market Prices](https://docs.omnicommerce.ai/api-reference/products/compare-product-market-prices.md): Research market offers for a batch of OmniCommerce simple product or variant UUIDs using the same BigGo API and Serper Shopping fallback as pricing strategy. Read-only; no prices are changed.
- [Get Product Price Comparison](https://docs.omnicommerce.ai/api-reference/products/get-product-price-comparison.md): Read durable batch progress and ordered per-product results. Requires catalog:read and the job's organization.
- [Batch Update Product Cost](https://docs.omnicommerce.ai/api-reference/products/batch-update-product-cost.md): Set catalog cost price and currency for one or more products. Cost is Omni-only and never syncs to marketplaces.
- [Queue Product Enrichment](https://docs.omnicommerce.ai/api-reference/products/queue-product-enrichment.md): Requires catalog:enrich. Queue content enrichment for 1–1,000 existing Omni product IDs across all supported marketplaces. Returns 202 after queue submission without awaiting AI completion or publishing.
- [Create Agentic Checkout Session](https://docs.omnicommerce.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.
- [Upload Document](https://docs.omnicommerce.ai/api-reference/documents/upload-document.md): Upload one file to the knowledge base as multipart/form-data. Requires `documents:write`.
- [Get Document](https://docs.omnicommerce.ai/api-reference/documents/get-document.md): Read one knowledge base document and its indexing status. Requires `documents:read`.
- [List Looks](https://docs.omnicommerce.ai/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.ai/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.ai/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.ai/api-reference/oauth/revoke-access-token.md): Revoke an OAuth bearer access token using client_secret_post authentication.
- [Get Access Token](https://docs.omnicommerce.ai/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.ai/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.ai/api-reference/orders/create-order.md): Create a native `agentic` order with line items. This operation uses the same upsert path as agentic checkout completion.
- [Get Order](https://docs.omnicommerce.ai/api-reference/orders/get-order.md): Get one order by its OmniCommerce UUID for the authenticated organization.
- [Update Order](https://docs.omnicommerce.ai/api-reference/orders/update-order.md): Update a native **agentic** order.
- [Get Order Action Options](https://docs.omnicommerce.ai/api-reference/orders/get-order-action-options.md): Ask the marketplace which choices an action needs, such as pickup or drop-off for `ship`. Requires `orders:write`.
- [List Order Actions](https://docs.omnicommerce.ai/api-reference/orders/list-order-actions.md): The order's 20 most recent action jobs, newest first, plus its latest successful label job. Requires `orders:read`.
- [Queue Order Action](https://docs.omnicommerce.ai/api-reference/orders/queue-order-action.md): Ship, cancel, generate shipping labels for, or update tracking on a marketplace order. Requires `orders:write`.
- [Create Organization](https://docs.omnicommerce.ai/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.ai/api-reference/price-books/list-price-book-rules.md): List marketplace price book rules for the authenticated organization. A rule applies either a buyer formula or a markup percent to the catalog price at publish time, by platform and optional store/country. Requires `price_books:read`.
- [Create Price Book Rule](https://docs.omnicommerce.ai/api-reference/price-books/create-price-book-rule.md): Create a marketplace price book rule for a platform (optional store and country). Does not change Omni product prices. Requires `price_books:write`.
- [Get Price Book Rule](https://docs.omnicommerce.ai/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.ai/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.ai/api-reference/price-books/update-price-book-rule.md): Update store, country, markup, buyer formula, 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.ai/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 Promotions](https://docs.omnicommerce.ai/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.ai/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.ai/api-reference/promotions/get-promotion.md): Fetch one promotion by ID, including effective status. Requires `promotions:read`.
- [Delete Promotion](https://docs.omnicommerce.ai/api-reference/promotions/delete-promotion.md): Delete a promotion by ID. Requires `promotions:write`.
- [Update Promotion](https://docs.omnicommerce.ai/api-reference/promotions/update-promotion.md): Update promotion fields (name, discount, schedule, status, stores). Requires `promotions:write`.
- [List Promotion Assignments](https://docs.omnicommerce.ai/api-reference/promotions/list-promotion-assignments.md): List products assigned to a promotion. Requires `promotions:read`.
- [Assign Products to Promotion](https://docs.omnicommerce.ai/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.ai/api-reference/promotions/unassign-products-from-promotion.md): Remove product assignments and queue marketplace teardown. Requires `promotions:write`.
- [Retry Marketplace Delivery](https://docs.omnicommerce.ai/api-reference/promotions/retry-marketplace-delivery.md): Run marketplace delivery again after a failure, for example once a store is reconnected. Requires `promotions:write`.
- [List Returns](https://docs.omnicommerce.ai/api-reference/returns/list-returns.md): List normalized, PII-free marketplace returns with SKU-level lines. Requires `returns:read`. Use updatedSince and cursor for bootstrap/recovery alongside return webhooks.
- [Get Return](https://docs.omnicommerce.ai/api-reference/returns/get-return.md): Get one normalized, PII-free return by OmniCommerce UUID. Requires `returns:read`; another organization's return returns 404.
- [List Reviews](https://docs.omnicommerce.ai/api-reference/reviews/list-reviews.md): List marketplace product reviews, newest first unless `sortBy` says otherwise. Requires `reviews:read`.
- [Get Review](https://docs.omnicommerce.ai/api-reference/reviews/get-review.md): Read one review by its OmniCommerce UUID. Requires `reviews:read`.
- [Reply to Review](https://docs.omnicommerce.ai/api-reference/reviews/reply-to-review.md): Reply to one review identified by its OmniCommerce UUID in the URL. Requires `reviews:write`. Supply `reply` or set `generateWithAi: true`. `submit` defaults to true; set false with AI generation to return a draft without posting. Optional `instructions` guide AI writing. AI generation uses organiza…
- [List Settlements](https://docs.omnicommerce.ai/api-reference/settlements/list-settlements.md): List the latest normalized order-settlement snapshots created by finance ingestion. Requires `settlements:read`. Use updatedSince and cursor for recovery; money remains partitioned by currency.
- [Apply Settlements](https://docs.omnicommerce.ai/api-reference/settlements/apply-settlements.md): Apply marketplace-agnostic settlement lines to existing orders.
- [Get Settlement](https://docs.omnicommerce.ai/api-reference/settlements/get-settlement.md): Get the latest normalized settlement snapshot by stable settlement ID. Requires `settlements:read`.
- [Create UCP Checkout Session](https://docs.omnicommerce.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.
- [Product created](https://docs.omnicommerce.ai/webhooks/reference/product-created.md): Delivered when an OmniCommerce catalog product is created.
- [Product updated](https://docs.omnicommerce.ai/webhooks/reference/product-updated.md): Delivered when public OmniCommerce catalog product data changes.
- [Product deleted](https://docs.omnicommerce.ai/webhooks/reference/product-deleted.md): Delivered when an OmniCommerce catalog product is deleted.
- [Product delisted](https://docs.omnicommerce.ai/webhooks/reference/product-delisted.md): Delivered when a product listing is removed from one or more marketplaces.
- [Product price changed](https://docs.omnicommerce.ai/webhooks/reference/product-price-changed.md): Delivered when catalog price inputs change.
- [Product inventory changed](https://docs.omnicommerce.ai/webhooks/reference/product-inventory-changed.md): Delivered when catalog inventory quantity changes.
- [Order created](https://docs.omnicommerce.ai/webhooks/reference/order-created.md): Delivered after a complete order aggregate is first committed.
- [Order updated](https://docs.omnicommerce.ai/webhooks/reference/order-updated.md): Delivered when public non-status order fields change.
- [Order status changed](https://docs.omnicommerce.ai/webhooks/reference/order-status-changed.md): Delivered when an order's provider-neutral status changes.
- [Order deleted](https://docs.omnicommerce.ai/webhooks/reference/order-deleted.md): Delivered when a stored order is explicitly deleted or purged.
- [Look created](https://docs.omnicommerce.ai/webhooks/reference/look-created.md): Delivered when a shoppable look is created.
- [Look deleted](https://docs.omnicommerce.ai/webhooks/reference/look-deleted.md): Delivered when a shoppable look is deleted.
- [Review created](https://docs.omnicommerce.ai/webhooks/reference/review-created.md): Delivered when a marketplace product review is first stored.
- [Review updated](https://docs.omnicommerce.ai/webhooks/reference/review-updated.md): Delivered when tracked marketplace review content changes without a status change.
- [Review status changed](https://docs.omnicommerce.ai/webhooks/reference/review-status-changed.md): Delivered when a marketplace product review status changes.
- [Settlement created](https://docs.omnicommerce.ai/webhooks/reference/settlement-created.md): Reference for the settlement.created webhook.
- [Settlement updated](https://docs.omnicommerce.ai/webhooks/reference/settlement-updated.md): Reference for the settlement.updated webhook.
- [Settlement status changed](https://docs.omnicommerce.ai/webhooks/reference/settlement-status-changed.md): Reference for the settlement.status.changed webhook.
- [Return created](https://docs.omnicommerce.ai/webhooks/reference/return-created.md): Reference for the return.created webhook.
- [Return updated](https://docs.omnicommerce.ai/webhooks/reference/return-updated.md): Reference for the return.updated webhook.
- [Return status changed](https://docs.omnicommerce.ai/webhooks/reference/return-status-changed.md): Reference for the return.status.changed webhook.
- [Changelog](https://docs.omnicommerce.ai/changelog.md): Product and API updates for OmniCommerce.

## OpenAPI Specs

- [openapi](/openapi.json)


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