Developer Reference
OmniCommerce API Documentation
Server-rendered API reference generated from our OpenAPI contract. This page is crawlable and agent-readable without client-side docs generators.
Base URL
https://omnicommerce.sg
OpenAPI Source
Raw machine-readable schema used for this reference.
Coverage
64 operations across 12 API domains.
Redocly Reference
Interactive OpenAPI reference with schema navigation.
Quick Navigation
Protocol docs and discovery endpoints for developers and agents.
Endpoints
Jump directly to an endpoint in the reference below.
Agentic Checkout
Create Agentic Checkout Session
Create a merchant-fulfilled checkout session, reserve inventory, and return rail-specific payment requirements. Requires an OAuth client token with `checkout:write`.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; paymentRail?: acp_stripe | x402; items: { productId: string; quantity: integer }[]; buyer?: { name?: string; email?: string; phone?: string }, ... }
Responses
Get Agentic Checkout Session
Fetch the current checkout session, cart items, totals, payment requirements, and linked order when completed.
Parameters
Responses
Replace Agentic Checkout Session Fields
UCP-compatible update method for cart/contact fields. The current implementation applies provided fields and leaves omitted fields unchanged. Requires `checkout:write`.
Parameters
Request Body
application/json
Required: Yes
{ paymentRail?: acp_stripe | x402; items?: { productId: string; quantity: integer }[]; buyer?: { name?: string; email?: string; phone?: string }; shippingAddress?: { name?: string; line1?: string; line2?: string; city?: string, ... }, ... }
Responses
Update Agentic Checkout Session
Update cart/contact fields, recompute totals, and refresh inventory reservations before payment. Requires `checkout:write`.
Parameters
Request Body
application/json
Required: Yes
{ paymentRail?: acp_stripe | x402; items?: { productId: string; quantity: integer }[]; buyer?: { name?: string; email?: string; phone?: string }; shippingAddress?: { name?: string; line1?: string; line2?: string; city?: string, ... }, ... }
Responses
Cancel Agentic Checkout Session
Cancel a ready-for-payment checkout session and release reserved inventory. This operation is exposed for UCP REST clients and requires `checkout:write`.
Parameters
Responses
Complete Agentic Checkout Session
Settle the selected rail and create a native `agentic` order. Settlement failures return 402 and leave the session in `ready_for_payment`.
Parameters
Request Body
application/json
Required: Yes
{ idempotencyKey?: string; paymentProof: object }
Responses
Commerce
API Root
Public API discovery root. Merchant payments are handled by organization-scoped checkout session endpoints.
Responses
API v1 Root
Public API v1 discovery root. Merchant payments are handled by organization-scoped checkout session endpoints.
Responses
Developer Platform
Evaluate SKU Readiness
Score a persisted product or inline SKU payload for agentic commerce readiness, engine eligibility, and recommended fixes.
Responses
Generate Ghost Mannequin Image
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.
Request Body
application/json
Required: Yes
{ imageUrl: string; productTitle?: string; categoryName?: string; categoryId?: string }
Responses
Get Developer Job Status
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.
Parameters
Responses
Cancel Developer Job
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 current terminal status.
Parameters
Request Body
application/json
Required: No
{ organizationId?: string }
Responses
Recommend Marketplace Product Categories
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_...`.
Request Body
application/json
Required: Yes
{ organizationId?: string; productId: string; targets: { marketplace: string; country?: string }[]; query?: string, ... }
Responses
List Connected Marketplaces
List connected marketplace stores for the authenticated organization. Results are scoped to the API key organization unless `organizationId` is supplied for session-authenticated calls.
Parameters
Responses
Run AI Shelf Share Monitor
Queue AI Shelf Share replay/monitoring for a product, query, or organization catalog.
Responses
Publish Product
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.
Parameters
Request Body
application/json
Required: No
{ organizationId?: string; visibility?: live | draft }
Responses
Sync Product Commercial Fields
Update price, sale price, or stock quantity in OmniCommerce and queue marketplace sync workers where applicable.
Responses
List Developer Webhooks
List configured developer webhook subscriptions for the authenticated organization.
Responses
Create Developer Webhook
Create a developer webhook subscription for product, order, look, and related commerce events.
Responses
Looks
List Looks
List AI-styled product Looks for the authenticated organization, newest first. Use query parameters for search, status filtering, and pagination.
Parameters
Responses
Create Look
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}`.
Request Body
application/json
Required: Yes
{ organizationId?: string; title?: string; productIds: string[]; subject?: string, ... }
Responses
Get Look
Fetch a single Look by ID, including the generated hero image URL and the shoppable product cards used in the Look.
Parameters
Responses
Oauth
Revoke Access Token
Revoke an OAuth bearer access token using client_secret_post authentication.
Request Body
application/x-www-form-urlencoded
Required: Yes
{ token: string; token_type_hint?: access_token; client_id: string; client_secret: string }
application/json
Required: Yes
{ token: string; token_type_hint?: access_token; client_id: string; client_secret: string }
Responses
Get Access Token
Exchange client credentials for an access token using OAuth 2.0 client_credentials grant. Tokens are valid for 1 hour.
Request Body
application/x-www-form-urlencoded
Required: Yes
{ grant_type: client_credentials; client_id: string; client_secret: string }
application/json
Required: Yes
{ grant_type: client_credentials; client_id: string; client_secret: string }
Responses
Orders
List Orders
List orders for the authenticated organization using the same filters, sorting, and pagination semantics as the workspace Orders listing page. Requires `orders:read`.
Parameters
Responses
Create Order
Create a native `agentic` order with line items. Supports `status`, `currency`, `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_data.costPrice` and is snapshotted on the line. Omitted `costPrice` never clears existing product cost. Reuses the same upsert path as agentic checkout completion. Requires `orders:write`. Re-posting the same `externalOrderId` updates the existing order instead of creating a duplicate.
Request Body
application/json
Required: Yes
{ organizationId?: string; externalOrderId?: string; externalOrderNumber?: string; platform?: agentic, ... }
Responses
Update Order
Update a native **agentic** order. Supports external order identifiers, status, currency, totalAmount, shippingFee, discountAmount, metadata, and partial line items (including externalOrderItemId, price / unitPrice / paidPrice / costPrice / currency / status / quantity). Requires `orders:write`. Marketplace orders (Shopee, Lazada, TikTok, Shopify) are rejected with HTTP 409 — those fields are marketplace-owned. Emits `order.status.changed` when status changes and `order.updated` for other field changes.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; externalOrderId?: string; externalOrderNumber?: string; status?: pending | to_ship | shipped | completed | return | canceled, ... }
Responses
Organizations
Create Organization
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.
Request Body
application/json
Required: Yes
{ name: string; keepCurrentActiveOrganization?: boolean }
Responses
Price Books
List Price Book Rules
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`.
Parameters
Responses
Create Price Book Rule
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`.
Request Body
application/json
Required: Yes
{ organizationId?: string; platform: shopee | lazada | tiktok | shopify | whatsapp; storeId?: string | null; country?: string | null, ... }
Responses
Get Price Book Rule
Fetch one marketplace price book rule by ID. Requires `price_books:read`.
Parameters
Responses
Update Price Book Rule
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`.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; storeId?: string | null; country?: string | null; marginValue?: number, ... }
Responses
Delete Price Book Rule
Delete a marketplace price book rule by ID. Requires `price_books:write`.
Parameters
Responses
Preview Channel List Price
Compute channel list price from a canonical list price using matching enabled rules (or a forced ruleId). Requires `price_books:read`.
Request Body
application/json
Required: Yes
{ organizationId?: string; platform: shopee | lazada | tiktok | shopify | whatsapp; listPrice: number; storeId?: string | null, ... }
Responses
Products
List Products
List products for the authenticated organization with optional filters and pagination. Supports API key Bearer token authentication.
Parameters
Responses
Create and Enrich Product
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 HTTP(S) images are mirrored to managed R2 storage, and the API returns a job ID to poll with GET /api/v1/jobs/{jobId}. `targetMarketplaces` and `targetCountries` are optional; product creation and enrichment can run without marketplace publishing targets.
Request Body
application/json
Required: Yes
{ product: { id?: string; sku: string; title: string; name?: string, ... }; variants?: { sku?: string; price?: object; inventory?: object; variationAttributes?: object, ... }[]; variationSchema?: object; targetMarketplaces?: shopee | lazada | tiktok[], ... }
Responses
Get Product
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 present.
Parameters
Responses
Update Product
Update an existing product by ID. Only provided fields will be updated. Supports API key Bearer token authentication.
Parameters
Request Body
application/json
Required: Yes
{ name?: string; description?: string; sku?: string; brand?: string, ... }
Responses
Delete Product
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.
Parameters
Responses
Bulk Import Products from CSV
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 GET /api/v1/jobs/{jobId}. Cancel in-flight imports with POST /api/v1/jobs/{jobId}/cancel.
Request Body
multipart/form-data
Required: Yes
{ file: string; organizationId?: string; fileName?: string; targetMarketplaces: string | string[], ... }
application/json
Required: Yes
{ organizationId?: string; csvText?: string; documentId?: string; fileName?: string, ... }
Responses
Promotions
List Promotions
List central promotions for the authenticated organization with filters and offset pagination matching the workspace Promotions listing. Requires `promotions:read`.
Parameters
Responses
Create Promotion
Create a central promotion targeting connected stores. Requires `promotions:write`. Fixed-amount discounts resolve currency from the selected store countries.
Request Body
application/json
Required: Yes
{ organizationId?: string; name: string; description?: string | null; discountType: percentage | fixed_amount, ... }
Responses
Get Promotion
Fetch one promotion by ID, including effective status. Requires `promotions:read`.
Parameters
Responses
Update Promotion
Update promotion fields (name, discount, schedule, status, stores). Requires `promotions:write`.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; name?: string; description?: string | null; discountType?: percentage | fixed_amount, ... }
Responses
Delete Promotion
Delete a promotion by ID. Requires `promotions:write`.
Parameters
Responses
List Promotion Assignments
List products assigned to a promotion. Requires `promotions:read`.
Parameters
Responses
Assign Products to Promotion
Assign one or more products to a promotion. Creates pending marketplace sync rows; call sync after assign. Requires `promotions:write`.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; productIds: string[]; variantSku?: string | null; priority?: integer }
Responses
Unassign Products from Promotion
Remove product assignments and queue marketplace teardown. Requires `promotions:write`.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; productIds: string[]; variantSku?: string | null }
Responses
Sync Promotion to Marketplaces
Queue marketplace push for assigned products (Shopee discount, Lazada voucher, TikTok activity, Shopify automatic discount). Requires `promotions:write`.
Parameters
Request Body
application/json
Required: Yes
{ organizationId?: string; marketplace?: shopee | lazada | tiktok | shopify; productIds?: string[] }
Responses
Public Agent
Compare Public Products
Compare 2 to 10 public products side-by-side across price, ACO readiness, marketplace coverage, and inventory.
Parameters
Responses
List Public Merchants
Discover merchants with public products available through OmniCommerce's public agent APIs.
Responses
Get Merchant LLM Feed
Return a plain-text, LLM-optimized merchant feed keyed by website domain.
Parameters
Responses
Get Public Merchant Manifest
Return machine-readable capability and endpoint metadata for a single public merchant.
Parameters
Responses
List Public Merchant Products
Browse a single merchant's public product feed with optional marketplace and localization filters.
Parameters
Responses
Search Within Public Merchant Catalog
Search within a single merchant's public product feed using the same filter model as the cross-merchant search API.
Parameters
Responses
Search Public Merchant Products
Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.
Parameters
Responses
Search Public Merchant Products
Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.
Parameters
Responses
Ucp
Create UCP Checkout Session
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`.
Parameters
Request Body
application/json
Required: Yes
{ line_items: { item: object; quantity: integer }[]; buyer?: object; fulfillment?: object; payment?: object, ... }
Responses
Get UCP Checkout Session
Fetch the current UCP checkout resource for a native agentic checkout session. Requires `UCP-Agent` and bearer authentication.
Parameters
Responses
Replace UCP Checkout Session Fields
UCP-compatible update method. Current behavior matches PATCH: provided fields are applied and omitted fields remain unchanged. Requires `UCP-Agent` and OAuth `checkout:write`.
Parameters
Request Body
application/json
Required: Yes
{ line_items?: { item: object; quantity: integer }[]; buyer?: object; fulfillment?: object; payment?: object, ... }
Responses
Update UCP Checkout Session
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`.
Parameters
Request Body
application/json
Required: Yes
{ line_items?: { item: object; quantity: integer }[]; buyer?: object; fulfillment?: object; payment?: object, ... }
Responses
Cancel UCP Checkout Session
Cancel a ready-for-payment UCP checkout session and release reserved inventory. Requires `UCP-Agent` and OAuth `checkout:write`.
Parameters
Responses
Complete UCP Checkout Session
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`.
Parameters
Request Body
application/json
Required: Yes
{ idempotency_key?: string; paymentProof?: object; payment?: object }
Responses
Get UCP Order
Fetch the native OmniCommerce order created by a completed UCP checkout session. Only `agentic` orders are exposed through this facade.