{ "openapi": "3.1.0", "info": { "title": "OmniCommerce API", "version": "1.0.0", "license": { "name": "Proprietary", "url": "https://omnicommerce.sg/terms" }, "description": "OmniCommerce API surface for agents and developer integrations. Includes public endpoints (merchant discovery, product search, compare, catalog, ACO retrieval) and authenticated endpoints (product management via API key Bearer tokens)." }, "servers": [ { "url": "https://omnicommerce.sg", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local development" } ], "tags": [ { "name": "agentic-checkout", "description": "Merchant-fulfilled agentic checkout", "x-group": "Agentic Checkout" }, { "name": "agents", "description": "agents", "x-group": "Agents" }, { "name": "analytics", "description": "Sales performance across marketplaces", "x-group": "Analytics" }, { "name": "aops", "description": "Agent operating procedures", "x-group": "AOPs" }, { "name": "campaigns", "description": "Campaign briefs, offer windows, and marketplace runs", "x-group": "Campaigns" }, { "name": "developer-platform", "description": "Authenticated developer platform APIs", "x-group": "Developer Platform" }, { "name": "documents", "description": "Knowledge base document uploads", "x-group": "Knowledge Base" }, { "name": "looks", "description": "AI-styled product looks", "x-group": "Looks" }, { "name": "oauth", "description": "OAuth token endpoints", "x-group": "OAuth" }, { "name": "orders", "description": "Workspace and agentic orders", "x-group": "Orders" }, { "name": "organizations", "description": "Organization management", "x-group": "Organizations" }, { "name": "price-books", "description": "Marketplace list-price markup rules", "x-group": "Price Books" }, { "name": "products", "description": "Product CRUD, bulk import, enrichment, publish, and delist", "x-group": "Products" }, { "name": "promotions", "description": "Central promotions and marketplace sync", "x-group": "Promotions" }, { "name": "public-agent", "description": "Public agent discovery and catalog APIs", "x-group": "Public Agent" }, { "name": "returns", "description": "returns", "x-group": "Returns" }, { "name": "reviews", "description": "Marketplace product reviews and seller replies", "x-group": "Reviews" }, { "name": "settlements", "description": "settlements", "x-group": "Settlements" }, { "name": "ucp", "description": "Universal Commerce Protocol", "x-group": "UCP" } ], "paths": { "/api/v1/agents/general/invoke": { "post": { "operationId": "post_v1_agents_general_invoke", "summary": "Invoke the Omni agent", "description": "Run the general Omni agent and wait until it completes, pauses for approval, or fails. Requires `agents:invoke`.\n\nA waiting call can take several minutes; raise the client timeout. Send `decisions` with the same `thread_id` to approve or reject a paused run. Omit `config.enabled_tools` to use the organization's agent tools. Attach images on the latest user message as `{ type: \"image\", url }` HTTP(S) URLs.", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "thread_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "channel": { "type": "string", "minLength": 1, "maxLength": 64 }, "messages": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100000 }, { "minItems": 1, "maxItems": 20, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type", "url" ], "additionalProperties": false } ] } } ] }, "id": { "type": "string", "maxLength": 200 }, "name": { "type": "string", "maxLength": 200 } }, "required": [ "content" ], "additionalProperties": false } }, "config": { "type": "object", "properties": { "enabled_tools": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "model": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "system_prompt": { "type": "string", "maxLength": 20000 }, "structured_output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false }, "decisions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "action" ], "additionalProperties": false } } }, "additionalProperties": false }, "example": { "messages": [ { "role": "user", "content": "How many products are missing a price?" } ] } } } }, "responses": { "200": { "description": "The agent finished or is waiting for approval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "thread_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "awaiting_approval", "failed" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "ai", "tool", "system" ] }, "role": { "type": "string", "enum": [ "user", "assistant", "tool", "system" ] }, "content": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": {} }, "required": [ "name", "args" ] } }, "tool_call_id": { "type": "string" } }, "required": [ "type", "role", "content" ] } }, "structured_output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "approvals": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "interrupt_instance_id": { "type": "string" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_args": {}, "message": { "type": "string" } }, "required": [ "interrupt_instance_id", "tool_name", "tool_args", "message" ] } }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "run_id", "thread_id", "status", "messages", "structured_output", "approvals", "error" ] } } } }, "400": { "description": "Invalid agent request, unknown tool or model, or a decision count that does not match the pending approvals" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Missing agents:invoke scope or Assistant access" }, "409": { "description": "The thread already has an active run, or decisions were sent for a thread with no run awaiting approval" }, "500": { "description": "The agent run failed. `data.run_id` identifies the stored run" }, "504": { "description": "The agent run timed out. `data.run_id` identifies the stored run" } } } }, "/api/v1/agents/general/runs": { "post": { "operationId": "post_v1_agents_general_runs", "summary": "Start an Omni agent run", "description": "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.", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "thread_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "channel": { "type": "string", "minLength": 1, "maxLength": 64 }, "messages": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100000 }, { "minItems": 1, "maxItems": 20, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type", "url" ], "additionalProperties": false } ] } } ] }, "id": { "type": "string", "maxLength": 200 }, "name": { "type": "string", "maxLength": 200 } }, "required": [ "content" ], "additionalProperties": false } }, "config": { "type": "object", "properties": { "enabled_tools": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "model": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "system_prompt": { "type": "string", "maxLength": 20000 }, "structured_output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false }, "decisions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "action" ], "additionalProperties": false } } }, "additionalProperties": false }, "example": { "messages": [ { "role": "user", "content": "Summarize orders placed today." } ] } } } }, "responses": { "202": { "description": "The agent run was queued.", "headers": { "Location": { "description": "The run to poll.", "schema": { "type": "string", "format": "uri-reference" } }, "Retry-After": { "description": "Seconds to wait before polling again. Sent while the run is queued or running.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "thread_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "awaiting_approval", "failed" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "ai", "tool", "system" ] }, "role": { "type": "string", "enum": [ "user", "assistant", "tool", "system" ] }, "content": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": {} }, "required": [ "name", "args" ] } }, "tool_call_id": { "type": "string" } }, "required": [ "type", "role", "content" ] } }, "structured_output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "approvals": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "interrupt_instance_id": { "type": "string" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_args": {}, "message": { "type": "string" } }, "required": [ "interrupt_instance_id", "tool_name", "tool_args", "message" ] } }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "run_id", "thread_id", "status", "messages", "structured_output", "approvals", "error" ] } } } }, "400": { "description": "Invalid agent request, unknown tool or model, or a decision count that does not match the pending approvals" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Missing agents:invoke scope or Assistant access" }, "409": { "description": "The thread already has an active run, or decisions were sent for a thread with no run awaiting approval" }, "500": { "description": "The agent run failed. `data.run_id` identifies the stored run" } } } }, "/api/v1/agents/general/runs/{runId}": { "get": { "operationId": "get_v1_agents_general_runs_by_runid", "summary": "Get an Omni agent run", "description": "Read a queued, running, completed, paused, or failed Omni agent run. Requires `agents:invoke`.", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. Optional for API keys, which already belong to one organization.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "The agent run.", "headers": { "Retry-After": { "description": "Seconds to wait before polling again. Sent while the run is queued or running.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "thread_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "awaiting_approval", "failed" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "ai", "tool", "system" ] }, "role": { "type": "string", "enum": [ "user", "assistant", "tool", "system" ] }, "content": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": {} }, "required": [ "name", "args" ] } }, "tool_call_id": { "type": "string" } }, "required": [ "type", "role", "content" ] } }, "structured_output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "approvals": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "interrupt_instance_id": { "type": "string" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_args": {}, "message": { "type": "string" } }, "required": [ "interrupt_instance_id", "tool_name", "tool_args", "message" ] } }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "run_id", "thread_id", "status", "messages", "structured_output", "approvals", "error" ] } } } }, "400": { "description": "Invalid agent request, unknown tool or model, or a decision count that does not match the pending approvals" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing agents:invoke scope or Assistant access" }, "404": { "description": "Agent run not found" } } } }, "/api/v1/analytics/ads": { "get": { "operationId": "get_v1_analytics_ads", "summary": "Get Ads Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. The periods count back from the end of the range.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Ads Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "anchorDate": { "type": "string", "description": "The last day the periods count back from." }, "kpiDateRange": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "description": "The 28 days the KPI totals cover." }, "kpis": { "type": "object", "properties": { "spend": { "type": "number" }, "attributedGmv": { "type": "number" }, "attributedOrders": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "acos": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "productCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productsWithAds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "spend", "attributedGmv", "attributedOrders", "impressions", "clicks", "roas", "acos", "productCount", "productsWithAds" ] }, "coverage": { "type": "object", "properties": { "ads": { "type": "boolean" }, "productLevelAds": { "type": "boolean" }, "feeLineOnly": { "type": "boolean", "description": "Only ad fee lines are known, not per-product ad data." } }, "required": [ "ads", "productLevelAds", "feeLineOnly" ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last28Totals": { "type": "object", "properties": { "revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "orders": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "qtySold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgUnitPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adSpend": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adRevenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adOrders": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adQtySold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adRoas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "hasSales": { "type": "boolean" }, "hasAds": { "type": "boolean" } }, "required": [ "revenue", "orders", "qtySold", "avgUnitPrice", "adSpend", "adRevenue", "adOrders", "adQtySold", "adRoas", "hasSales", "hasAds" ] }, "periods": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "today", "yesterday", "avg_7", "d7", "avg_28", "d28" ] }, "label": { "type": "string" }, "isAverage": { "type": "boolean" }, "revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "orders": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "qtySold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgUnitPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adSpend": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adRevenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adOrders": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adQtySold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adRoas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "hasSales": { "type": "boolean" }, "hasAds": { "type": "boolean" } }, "required": [ "period", "label", "isAverage", "revenue", "orders", "qtySold", "avgUnitPrice", "adSpend", "adRevenue", "adOrders", "adQtySold", "adRoas", "hasSales", "hasAds" ] } } }, "required": [ "productId", "productName", "thumbnailUrl", "platform", "accountId", "sku", "externalProductId", "last28Totals", "periods" ] } } }, "required": [ "filters", "anchorDate", "kpiDateRange", "kpis", "coverage", "message", "products" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/ai-traffic": { "get": { "operationId": "get_v1_analytics_ai_traffic", "summary": "Get AI Traffic Analytics", "description": "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`.\n\nA range covers at most 365 days; a longer one is shortened to the last 365 days. Read the applied range from `data.filters`.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "source", "in": "query", "required": false, "description": "One AI source id from `data.filterOptions.sources`.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "trafficType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "indexing", "click_through", "page_view", "assistant" ] } }, { "name": "route", "in": "query", "required": false, "description": "One route key from `data.filterOptions.routes`.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "country", "in": "query", "required": false, "description": "ISO country code of the visit.", "schema": { "type": "string", "maxLength": 8 } } ], "responses": { "200": { "description": "Get AI Traffic Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "source": { "type": "string" }, "trafficType": { "type": "string" }, "route": { "type": "string" }, "country": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "source", "trafficType", "route", "country", "timeZone" ] }, "filterOptions": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "routes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "countries": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "sources", "routes", "countries" ] }, "summary": { "type": "object", "properties": { "totalEvents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalHits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageViews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productPageViews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productsViewed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "referredSessions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "indexingHits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "assistantHits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clickThroughs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productsRequested": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productsWithReferrals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attributableHits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "uniqueSources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "uniqueRoutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "uniqueProducts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "topSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "topRoute": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "topCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSeenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "totalEvents", "totalHits", "pageViews", "productPageViews", "productsViewed", "referredSessions", "indexingHits", "assistantHits", "clickThroughs", "productsRequested", "productsWithReferrals", "attributableHits", "uniqueSources", "uniqueRoutes", "uniqueProducts", "topSource", "topRoute", "topCountry", "lastSeenAt" ] }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "label": { "type": "string" }, "hits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attributableHits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "uniqueSources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "date", "label", "hits", "attributableHits", "uniqueSources" ] } }, "sourceBreakdown": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "value", "label", "count" ] } }, "routeBreakdown": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "value", "label", "count" ] } }, "countryBreakdown": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "value", "label", "count" ] } }, "productBreakdown": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "productId", "productName", "count" ] } }, "recentEvents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "occurredAt": { "type": "string" }, "sourceLabel": { "type": "string" }, "trafficType": { "type": "string" }, "operator": { "type": "string" }, "routeLabel": { "type": "string" }, "path": { "type": "string" }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inferredKeyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inferredIntent": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "source": { "type": "string" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "label", "source", "confidence" ] }, { "type": "null" } ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "occurredAt", "sourceLabel", "trafficType", "operator", "routeLabel", "path", "countryCode", "referrer", "inferredKeyword", "inferredIntent", "productId", "productName" ] } }, "dataFreshness": { "type": "object", "properties": { "metricsAvailable": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "metricsAvailable", "notes" ] } }, "required": [ "filters", "filterOptions", "summary", "trend", "sourceBreakdown", "routeBreakdown", "countryBreakdown", "productBreakdown", "recentEvents", "dataFreshness" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/content": { "get": { "operationId": "get_v1_analytics_content", "summary": "Get Video and LIVE Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Video and LIVE Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "coverage": { "type": "object", "properties": { "content": { "type": "boolean" } }, "required": [ "content" ] }, "kpis": { "type": "object", "properties": { "views": { "type": "number" }, "productClicks": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gmv": { "type": "number" }, "contentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clickRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "views", "productClicks", "orders", "gmv", "contentCount", "clickRate" ] }, "dailyTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "views": { "type": "number" }, "productClicks": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gmv": { "type": "number" } }, "required": [ "date", "views", "productClicks", "orders", "gmv" ] } }, "byType": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string" }, "views": { "type": "number" }, "gmv": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "number" } }, "required": [ "contentType", "views", "gmv", "orders", "clicks" ] } }, "items": { "type": "array", "items": { "type": "object", "properties": { "externalContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentType": { "type": "string", "description": "For example `video` or `live`." }, "title": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public link to the video." }, "views": { "type": "number" }, "productClicks": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gmv": { "type": "number" }, "clickRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "orderRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "externalContentId", "contentType", "title", "platform", "accountId", "productId", "externalProductId", "productName", "productThumbnailUrl", "contentUrl", "views", "productClicks", "orders", "gmv", "clickRate", "orderRate" ] } }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "filters", "coverage", "kpis", "dailyTrend", "byType", "items", "message" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/orders": { "get": { "operationId": "get_v1_analytics_orders", "summary": "Get Order Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Order Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "previousFrom": { "type": "string" }, "previousTo": { "type": "string" }, "kpis": { "type": "object", "properties": { "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netSales": { "type": "number" }, "aov": { "type": "number", "description": "Average order value." }, "unitsSold": { "type": "number" }, "unitsPerOrder": { "type": "number" }, "returnedOrders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "returnRate": { "type": "number", "description": "Share of orders returned, 0 to 1." }, "ordersChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "netSalesChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "aovChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "unitsChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "returnRateChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "identifiedBuyers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "repeatBuyers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "repeatRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cancelledOrders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cancelRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "orders", "netSales", "aov", "unitsSold", "unitsPerOrder", "returnedOrders", "returnRate", "ordersChangePercent", "netSalesChangePercent", "aovChangePercent", "unitsChangePercent", "returnRateChangePercent", "identifiedBuyers", "repeatBuyers", "repeatRate", "cancelledOrders", "cancelRate" ] }, "statusMix": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netSales": { "type": "number" } }, "required": [ "status", "orders", "netSales" ] } }, "platformMix": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netSales": { "type": "number" } }, "required": [ "platform", "orders", "netSales" ] } }, "dailyTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "previousDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netSales": { "type": "number" }, "previousOrders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "previousNetSales": { "type": "number" } }, "required": [ "date", "previousDate", "orders", "netSales", "previousOrders", "previousNetSales" ] } }, "topProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitsSold": { "type": "number" }, "netSales": { "type": "number" } }, "required": [ "productId", "productName", "platform", "accountId", "externalProductId", "sku", "thumbnailUrl", "orders", "unitsSold", "netSales" ] }, "description": "Up to 40 products ranked by net sales." } }, "required": [ "filters", "previousFrom", "previousTo", "kpis", "statusMix", "platformMix", "dailyTrend", "topProducts" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/overview": { "get": { "operationId": "get_v1_analytics_overview", "summary": "Get Growth Overview", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Growth Overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "previousFrom": { "type": "string" }, "previousTo": { "type": "string" }, "marketplaceScope": { "type": "string", "description": "`all`, or the single marketplace reported. With one marketplace, `channelMix` is split by store." }, "kpis": { "type": "object", "properties": { "grossSales": { "type": "number" }, "grossSalesChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "netSales": { "type": "number" }, "netSalesChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ordersChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "unitsSold": { "type": "number" }, "unitsChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "aov": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "aovChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "unitsPerOrder": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unitsPerOrderChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "visitors": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pageviews": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "atcUsers": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Visitors who added to cart." }, "viewToOrderCvr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contributionProfit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adsSpend": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "grossSales", "grossSalesChangePercent", "netSales", "netSalesChangePercent", "orders", "ordersChangePercent", "unitsSold", "unitsChangePercent", "aov", "aovChangePercent", "unitsPerOrder", "unitsPerOrderChangePercent", "visitors", "pageviews", "atcUsers", "viewToOrderCvr", "contributionProfit", "adsSpend" ] }, "dailyTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "grossSales": { "type": "number" }, "netSales": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitsSold": { "type": "number" }, "aov": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unitsPerOrder": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitors": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pageviews": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "date", "grossSales", "netSales", "orders", "unitsSold", "aov", "unitsPerOrder", "visitors", "pageviews" ] } }, "funnel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "covered": { "type": "boolean" } }, "required": [ "id", "label", "value", "covered" ] } }, "channelMix": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "type": "string" }, "netSales": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitsSold": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." } }, "required": [ "platform", "accountId", "label", "netSales", "orders", "unitsSold", "changePercent" ] } }, "topProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "netSales": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitsSold": { "type": "number" }, "revenueShare": { "type": "number", "description": "Share of net sales, 0 to 1." }, "gmvChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." } }, "required": [ "productId", "variantId", "sku", "productName", "thumbnailUrl", "platform", "accountId", "externalProductId", "netSales", "orders", "unitsSold", "revenueShare", "gmvChangePercent" ] } }, "laggingProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "netSales": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitsSold": { "type": "number" }, "revenueShare": { "type": "number", "description": "Share of net sales, 0 to 1." }, "gmvChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." } }, "required": [ "productId", "variantId", "sku", "productName", "thumbnailUrl", "platform", "accountId", "externalProductId", "netSales", "orders", "unitsSold", "revenueShare", "gmvChangePercent" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warn", "critical", "opportunity" ] }, "category": { "type": "string", "enum": [ "conversion", "profit", "inventory", "ads", "growth", "data", "market", "pricing" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "impactLabel": { "type": "string" }, "impactScore": { "type": "number", "description": "0 to 100, higher first." }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "severity", "category", "title", "summary", "impactLabel", "impactScore", "productId", "productName" ] }, "description": "Ranked next actions." }, "coverage": { "type": "object", "properties": { "sales": { "type": "boolean" }, "traffic": { "type": "boolean" }, "ads": { "type": "boolean" }, "content": { "type": "boolean" }, "inventory": { "type": "boolean" }, "profit": { "type": "boolean" }, "market": { "type": "boolean" } }, "required": [ "sales", "traffic", "ads", "content", "inventory", "profit", "market" ], "description": "Which data sources have data for this range." }, "syncFreshness": { "type": "array", "items": { "type": "object", "properties": { "jobType": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rowsUpserted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "jobType", "platform", "accountId", "status", "completedAt", "rowsUpserted" ] } } }, "required": [ "filters", "previousFrom", "previousTo", "marketplaceScope", "kpis", "dailyTrend", "funnel", "channelMix", "topProducts", "laggingProducts", "insights", "coverage", "syncFreshness" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/pricing": { "get": { "operationId": "get_v1_analytics_pricing", "summary": "Get Pricing Analytics", "description": "Selling products with their margin, velocity, stock cover, prices, competitor median, and a pricing recommendation. Matches the Pricing page. Requires `analytics:read`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Pricing Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "netSales": { "type": "number" }, "unitsSold": { "type": "number" }, "velocity": { "type": "number" }, "contributionMargin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "daysOfCover": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "catalogCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "salePrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "discountPct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "peerPriceP50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recommendation": { "type": "string" } }, "required": [ "productId", "productName", "sku", "netSales", "unitsSold", "velocity", "contributionMargin", "daysOfCover", "catalogCurrency", "listPrice", "salePrice", "discountPct", "peerPriceP50", "recommendation" ] }, "description": "Selling products from the top 30 by net sales." } }, "required": [ "filters", "products" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/products": { "get": { "operationId": "get_v1_analytics_products", "summary": "Get Product Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } }, { "name": "q", "in": "query", "required": false, "description": "Search product name or SKU.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "productId", "in": "query", "required": false, "description": "Comma-separated product or variant UUIDs, up to 50, to report only those products.", "schema": { "type": "string", "maxLength": 2000 } }, { "name": "limit", "in": "query", "required": false, "description": "Products to return, ranked by net sales.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Get Product Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" }, "q": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone", "q" ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gmv": { "type": "number" }, "netSales": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitsSold": { "type": "number" }, "revenueShare": { "type": "number" }, "velocity": { "type": "number", "description": "Units sold per day." }, "gmvChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "impressions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pageviews": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitors": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "clicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "atcUsers": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "atcUnits": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewToOrderCvr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitorValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "listingStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "channelsLive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "catalogCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of listPrice and salePrice, which can differ from the report currency." }, "marketPrices": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "minLength": 1 }, "storeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "storeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sellerSku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "price": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "salePrice": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "saleStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "saleEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "marketplace", "storeId", "storeName", "productId", "sellerSku", "variation", "country", "currency", "price", "salePrice", "saleStartDate", "saleEndDate", "status" ] } }, "listPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "salePrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "discountPct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "promoLift": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Units per day during promotions against outside them, as a ratio change." }, "completenessScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastPublishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "available": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "daysOfCover": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "stockoutRisk": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cogs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cogsCoverage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Share of sold units with a cost price, 0 to 1." }, "platformFees": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adsFees": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contributionProfit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contributionMargin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "returnRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "refundAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adsSpend": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adsRoas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adsAcos": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contentGmv": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "peerPriceP50": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Median competitor price." }, "searchRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warn", "critical" ] }, "message": { "type": "string" } }, "required": [ "code", "severity", "message" ] } } }, "required": [ "productId", "variantId", "sku", "productName", "thumbnailUrl", "platform", "accountId", "externalProductId", "gmv", "netSales", "orders", "unitsSold", "revenueShare", "velocity", "gmvChangePercent", "impressions", "pageviews", "visitors", "clicks", "atcUsers", "atcUnits", "viewToOrderCvr", "visitorValue", "listingStatus", "channelsLive", "catalogCurrency", "marketPrices", "listPrice", "salePrice", "discountPct", "promoLift", "completenessScore", "lastPublishedAt", "available", "daysOfCover", "stockoutRisk", "cogs", "cogsCoverage", "platformFees", "adsFees", "contributionProfit", "contributionMargin", "returnRate", "refundAmount", "adsSpend", "adsRoas", "adsAcos", "contentGmv", "peerPriceP50", "searchRank", "alerts" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warn", "critical", "opportunity" ] }, "category": { "type": "string", "enum": [ "conversion", "profit", "inventory", "ads", "growth", "data", "market", "pricing" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "impactLabel": { "type": "string" }, "impactScore": { "type": "number", "description": "0 to 100, higher first." }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "severity", "category", "title", "summary", "impactLabel", "impactScore", "productId", "productName" ] } }, "coverage": { "type": "object", "properties": { "sales": { "type": "boolean" }, "traffic": { "type": "boolean" }, "ads": { "type": "boolean" }, "content": { "type": "boolean" }, "inventory": { "type": "boolean" }, "profit": { "type": "boolean" }, "market": { "type": "boolean" } }, "required": [ "sales", "traffic", "ads", "content", "inventory", "profit", "market" ], "description": "Which data sources have data for this range." } }, "required": [ "filters", "products", "insights", "coverage" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/profit": { "get": { "operationId": "get_v1_analytics_profit", "summary": "Get Profit Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } }, { "name": "sku", "in": "query", "required": false, "description": "Comma-separated SKUs to report only those products.", "schema": { "type": "string", "maxLength": 1000 } } ], "responses": { "200": { "description": "Get Profit Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone", "sku" ] }, "reportingBasis": { "type": "string", "enum": [ "earnings", "profit" ], "description": "`profit` when cost prices cover sales, otherwise `earnings` (revenue after fees)." }, "currentRange": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "previousRange": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "metricCards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "net_revenue", "total_costs", "net_profit", "net_margin", "marketplace_costs", "earnings_after_fees", "earnings_rate" ] }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string", "enum": [ "currency", "percent" ] }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." } }, "required": [ "id", "label", "value", "unit", "changePercent" ] } }, "dailyTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "netRevenue": { "type": "number" }, "netProfit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "earningsAfterFees": { "type": "number" } }, "required": [ "date", "netRevenue", "netProfit", "earningsAfterFees" ] } }, "waterfall": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "gross_sales", "discounts", "returns", "platform_fees", "cogs", "fulfillment", "operating", "net_profit", "earnings_after_fees" ] }, "label": { "type": "string" }, "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "positive", "negative", "result" ] } }, "required": [ "id", "label", "amount", "kind" ] } }, "breakdownSections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "revenue", "platform_fees", "cogs", "fulfillment", "operating" ] }, "title": { "type": "string" }, "total": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "unit": { "type": "string", "enum": [ "currency", "percent" ] } }, "required": [ "id", "label", "amount", "unit" ] } } }, "required": [ "id", "title", "total", "rows" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tone": { "type": "string", "enum": [ "positive", "warning", "neutral" ] } }, "required": [ "id", "title", "description", "tone" ] } }, "profitabilitySnapshot": { "type": "object", "properties": { "marketplaceCosts": { "type": "number" }, "earningsAfterFees": { "type": "number" }, "earningsRate": { "type": "number" }, "totalKnownCosts": { "type": "number" }, "ordersInRange": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "costRatio": { "type": "number" }, "shippingRatio": { "type": "number" }, "uncostedUnits": { "type": "number" } }, "required": [ "marketplaceCosts", "earningsAfterFees", "earningsRate", "totalKnownCosts", "ordersInRange", "costRatio", "shippingRatio", "uncostedUnits" ] }, "missingCostProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "variantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "soldUnits": { "type": "number" }, "marketplaces": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } } }, "required": [ "productId", "variantId", "name", "variantName", "thumbnailUrl", "sku", "soldUnits", "marketplaces", "countries" ] }, "description": "Sold products without a cost price." }, "topProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "variantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitsSold": { "type": "number" }, "totalRevenue": { "type": "number" }, "totalCogs": { "type": "number" }, "totalFees": { "type": "number", "description": "Marketplace and fulfillment fees allocated to the product." }, "earningsAfterFees": { "type": "number" }, "earningsRate": { "type": "number" }, "totalProfit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Null until every sold unit has a cost price." }, "profitMargin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "knownCostProfit": { "type": "number", "description": "Profit counting only units with a cost price." }, "knownCostMargin": { "type": "number" }, "costCoverage": { "type": "number", "description": "Share of sold units with a cost price, 0 to 1." }, "marketplaces": { "type": "array", "items": { "type": "string" } } }, "required": [ "productId", "variantId", "name", "variantName", "thumbnailUrl", "sku", "unitsSold", "totalRevenue", "totalCogs", "totalFees", "earningsAfterFees", "earningsRate", "totalProfit", "profitMargin", "knownCostProfit", "knownCostMargin", "costCoverage", "marketplaces" ] } }, "underperformingProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "variantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitsSold": { "type": "number" }, "totalRevenue": { "type": "number" }, "totalCogs": { "type": "number" }, "totalFees": { "type": "number", "description": "Marketplace and fulfillment fees allocated to the product." }, "earningsAfterFees": { "type": "number" }, "earningsRate": { "type": "number" }, "totalProfit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Null until every sold unit has a cost price." }, "profitMargin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "knownCostProfit": { "type": "number", "description": "Profit counting only units with a cost price." }, "knownCostMargin": { "type": "number" }, "costCoverage": { "type": "number", "description": "Share of sold units with a cost price, 0 to 1." }, "marketplaces": { "type": "array", "items": { "type": "string" } } }, "required": [ "productId", "variantId", "name", "variantName", "thumbnailUrl", "sku", "unitsSold", "totalRevenue", "totalCogs", "totalFees", "earningsAfterFees", "earningsRate", "totalProfit", "profitMargin", "knownCostProfit", "knownCostMargin", "costCoverage", "marketplaces" ] } }, "retailUplift": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string" }, "soldUnits": { "type": "number" }, "coveredUnits": { "type": "number" }, "missingBaselineUnits": { "type": "number" }, "priceBookRecordedUnits": { "type": "number" }, "retailValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "salesValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "upliftAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "markupRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "currency", "soldUnits", "coveredUnits", "missingBaselineUnits", "priceBookRecordedUnits", "retailValue", "salesValue", "upliftAmount", "markupRate" ] }, { "type": "null" } ], "description": "Sales against the historical retail price, when price books record one." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "filters", "reportingBasis", "currentRange", "previousRange", "metricCards", "dailyTrend", "waterfall", "breakdownSections", "insights", "profitabilitySnapshot", "missingCostProducts", "topProducts", "underperformingProducts", "retailUplift", "notes" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/reports": { "get": { "operationId": "get_v1_analytics_reports", "summary": "Get Business Report", "description": "The management summary: headline KPIs, top products, sales by marketplace, alerts, settlement totals, and data quality. Matches the Business Reports page. Requires `analytics:read`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Business Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "kpis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previous": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string", "enum": [ "currency", "number", "percent" ] }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." } }, "required": [ "id", "label", "value", "previous", "unit", "changePercent" ] } }, "topProducts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "variantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalRevenue": { "type": "number" } }, "required": [ "productId", "variantId", "name", "variantName", "sku", "thumbnailUrl", "totalRevenue" ] } }, "marketplaceBreakdown": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revenue": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "share": { "type": "number" } }, "required": [ "platform", "country", "revenue", "orders", "share" ] } }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tone": { "type": "string", "enum": [ "warning", "neutral", "positive" ] } }, "required": [ "id", "title", "description", "tone" ] } }, "settlements": { "type": "object", "properties": { "ordersCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "withFinanceCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "missingFinanceCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "grossSales": { "type": "number" }, "netSettlement": { "type": "number" }, "platformFees": { "type": "number" }, "fulfillmentFees": { "type": "number" } }, "required": [ "ordersCount", "withFinanceCount", "missingFinanceCount", "grossSales", "netSettlement", "platformFees", "fulfillmentFees" ] }, "dataQuality": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "lastOrderUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastFinanceEventAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "financeCoverage": { "type": "number" }, "costCoverage": { "type": "number" }, "profitComplete": { "type": "boolean" } }, "required": [ "generatedAt", "lastOrderUpdatedAt", "lastFinanceEventAt", "financeCoverage", "costCoverage", "profitComplete" ] } }, "required": [ "filters", "kpis", "topProducts", "marketplaceBreakdown", "alerts", "settlements", "dataQuality" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/stores": { "get": { "operationId": "get_v1_analytics_stores", "summary": "Get Store Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Store Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "hasData": { "type": "boolean" }, "totals": { "type": "object", "properties": { "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "newVisitors": { "type": "number" }, "returningVisitors": { "type": "number" }, "newFollowers": { "type": "number" }, "averagePageViews": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "averageStaySeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "placedBuyers": { "type": "number" }, "placedUnits": { "type": "number" }, "placedOrders": { "type": "number" }, "placedSales": { "type": "number" }, "paidBuyers": { "type": "number" }, "paidUnits": { "type": "number" }, "paidOrders": { "type": "number" }, "paidSales": { "type": "number" }, "confirmedBuyers": { "type": "number" }, "confirmedUnits": { "type": "number" }, "confirmedOrders": { "type": "number" }, "confirmedSales": { "type": "number" }, "bounceRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitorToPlacedRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitorToPaidRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitorToConfirmedRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "placedToPaidRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "placedToConfirmedRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "visitors", "pageViews", "newVisitors", "returningVisitors", "newFollowers", "averagePageViews", "averageStaySeconds", "placedBuyers", "placedUnits", "placedOrders", "placedSales", "paidBuyers", "paidUnits", "paidOrders", "paidSales", "confirmedBuyers", "confirmedUnits", "confirmedOrders", "confirmedSales", "bounceRate", "visitorToPlacedRate", "visitorToPaidRate", "visitorToConfirmedRate", "placedToPaidRate", "placedToConfirmedRate" ] }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "paidOrders": { "type": "number" }, "paidSales": { "type": "number" } }, "required": [ "date", "visitors", "pageViews", "paidOrders", "paidSales" ] } }, "deviceBreakdown": { "type": "array", "items": { "type": "object", "properties": { "device": { "type": "string", "enum": [ "app", "pc" ] }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "newVisitors": { "type": "number" }, "returningVisitors": { "type": "number" }, "bounceRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "device", "visitors", "pageViews", "newVisitors", "returningVisitors", "bounceRate" ] } }, "coverage": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } }, "firstDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "platforms", "sources", "firstDate", "lastDate" ] } }, "required": [ "filters", "hasData", "totals", "trend", "deviceBreakdown", "coverage" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/analytics/traffic": { "get": { "operationId": "get_v1_analytics_traffic", "summary": "Get Traffic Analytics", "description": "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`.\n\nAmounts are in `data.filters.currency`. Only orders in that currency are counted; nothing is converted. A range covers at most 366 days.", "tags": [ "analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "from", "in": "query", "required": false, "description": "First day of the range (YYYY-MM-DD). Defaults to 29 days before `to`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, inclusive (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "timeZone", "in": "query", "required": false, "description": "IANA time zone that defines each day, for example `Asia/Kuala_Lumpur`. Defaults to Asia/Singapore.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated countries. One country selects its currency.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency. Only orders in this currency are counted; amounts are not converted. Defaults to the single country's currency, otherwise SGD.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Get Traffic Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "marketplace": { "type": "string" }, "country": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "description": "Currency of every amount in the response." }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "marketplace", "country", "store", "currency", "timeZone" ] }, "previousFrom": { "type": "string" }, "previousTo": { "type": "string" }, "kpis": { "type": "object", "properties": { "impressions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "pageviews": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pageviewsChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "visitors": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitorsChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "clicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "atcUsers": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Visitors who added to cart." }, "atcUsersChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ordersChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "netSales": { "type": "number" }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewToOrderCvr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewToOrderCvrChangePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change against the previous period of equal length. Null without a baseline." }, "visitToAtc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenuePerVisitor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "paidTrafficShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Share of traffic from ads, 0 to 1." }, "funnelMode": { "description": "`click` when unique visitors are unavailable and conversion uses clicks or page views.", "type": "string", "enum": [ "visit", "click" ] }, "cvrDenominatorLabel": { "type": "string" } }, "required": [ "impressions", "impressionsChangePercent", "pageviews", "pageviewsChangePercent", "visitors", "visitorsChangePercent", "clicks", "atcUsers", "atcUsersChangePercent", "orders", "ordersChangePercent", "netSales", "ctr", "viewToOrderCvr", "viewToOrderCvrChangePercent", "visitToAtc", "revenuePerVisitor", "paidTrafficShare" ] }, "funnel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "covered": { "type": "boolean" }, "rateFromPrevious": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rateLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "label", "value", "covered" ] }, "description": "Page views, visitors, potential buyers, buyers." }, "dailyTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "impressions": { "type": "number" }, "pageviews": { "type": "number" }, "visitors": { "type": "number" }, "atcUsers": { "type": "number" }, "clicks": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "date", "impressions", "pageviews", "visitors", "atcUsers", "clicks", "orders" ] } }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "impressions": { "type": "number" }, "pageviews": { "type": "number" }, "visitors": { "type": "number" }, "clicks": { "type": "number" }, "atcUsers": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netSales": { "type": "number" }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewToOrderCvr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitToAtc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewToOrder": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "netSalesPerVisitor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "diagnosis": { "type": "string" }, "opportunityScore": { "type": "number", "description": "Higher means fix first." }, "leak": { "type": "string", "enum": [ "high_traffic_low_cvr", "zero_orders", "healthy", "no_traffic" ] } }, "required": [ "productId", "variantId", "productName", "platform", "externalProductId", "sku", "thumbnailUrl", "impressions", "pageviews", "visitors", "clicks", "atcUsers", "orders", "netSales", "ctr", "viewToOrderCvr", "visitToAtc", "viewToOrder", "netSalesPerVisitor", "diagnosis", "opportunityScore", "leak" ] } }, "diagnostics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warn", "critical", "opportunity" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "metricLabel": { "type": "string" }, "metricValue": { "type": "string" } }, "required": [ "id", "severity", "title", "summary", "metricLabel", "metricValue" ] } }, "contentDrivers": { "type": "array", "items": { "type": "object", "properties": { "externalContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentType": { "type": "string" }, "title": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalProductId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "views": { "type": "number" }, "productClicks": { "type": "number" }, "orders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gmv": { "type": "number" }, "clickRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "orderRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "externalContentId", "contentType", "title", "platform", "productId", "externalProductId", "productName", "productThumbnailUrl", "views", "productClicks", "orders", "gmv", "clickRate", "orderRate" ] } }, "leakCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "coverage": { "type": "object", "properties": { "sales": { "type": "boolean" }, "traffic": { "type": "boolean" }, "ads": { "type": "boolean" }, "content": { "type": "boolean" }, "inventory": { "type": "boolean" }, "profit": { "type": "boolean" }, "market": { "type": "boolean" } }, "required": [ "sales", "traffic", "ads", "content", "inventory", "profit", "market" ], "description": "Which data sources have data for this range." } }, "required": [ "filters", "previousFrom", "previousTo", "kpis", "funnel", "dailyTrend", "products", "diagnostics", "contentDrivers", "leakCount", "coverage" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `analytics:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/aop/{aopId}/config": { "get": { "operationId": "get_v1_aop_by_aopid_config", "summary": "Get AOP configuration", "description": "Retrieve prompt, agent, structured inputs/output, and notification settings. Requires `aops:read`.", "tags": [ "aops" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "aopId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120, "description": "Required for session auth. Optional for API keys." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "aop_id" ], "properties": { "aop_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "prompt": { "type": "string" }, "description": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "icon": { "type": "string", "default": "ListTodo" }, "section": { "type": "string" }, "structured_output": { "type": [ "object", "null" ], "additionalProperties": true }, "structured_inputs": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Computed JSON Schema for user_inputs, derived from [[ placeholder ]] tokens and declared variables." }, "agent_config": { "type": [ "object", "null" ], "additionalProperties": true }, "user_notification_configs": { "type": [ "object", "null" ], "additionalProperties": true } } } } } }, "400": { "description": "Invalid AOP configuration or request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Forbidden. Missing OAuth scope." }, "404": { "description": "AOP or thread not found" }, "500": { "description": "Internal server error" } } }, "put": { "operationId": "put_v1_aop_by_aopid_config", "summary": "Overwrite AOP configuration", "description": "Updates AOP configuration. Omitted fields keep their current values. Send `user_notification_configs: null` to clear notification overrides. Requires `aops:write`.", "tags": [ "aops" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "aopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "prompt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "agentId": { "type": [ "string", "null" ] }, "agent_config": { "type": [ "object", "null" ], "additionalProperties": true }, "icon": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "structured_output": { "type": [ "object", "null" ], "additionalProperties": true }, "user_notification_configs": { "type": [ "object", "null" ], "additionalProperties": true }, "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth. Optional for API keys." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "aop_id" ], "properties": { "aop_id": { "type": "string" }, "status": { "type": "string", "default": "updated" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid AOP configuration or request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Forbidden. Missing OAuth scope." }, "404": { "description": "AOP or thread not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/aop/{aopId}/execute": { "post": { "operationId": "post_v1_aop_by_aopid_execute", "summary": "Execute an AOP", "description": "Start an AOP run and return immediately with a `thread_id`. Poll `GET /api/v1/threads/{thread_id}/status`. Requires `aops:write`.", "tags": [ "aops" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "aopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dry_run": { "type": "boolean", "default": false, "description": "Execute as a Test run: the agent uses its real prompt, config, and read-only tools, but side-effectful tool calls are captured instead of executed." }, "user_inputs": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Optional user inputs appended to the AOP prompt as key-value pairs." }, "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth. Optional for API keys." } } }, "example": { "user_inputs": { "company": "Acme Corp", "quarter": "Q1 2024" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "thread_id", "trigger_type", "aop_id", "aop_title", "base_prompt", "final_prompt", "aop_config" ], "properties": { "status": { "type": "string", "example": "started" }, "thread_id": { "type": "string" }, "trigger_type": { "type": "string", "const": "api" }, "message": { "type": "string" }, "aop_id": { "type": "string" }, "aop_title": { "type": "string" }, "base_prompt": { "type": "string" }, "final_prompt": { "type": "string" }, "aop_config": { "type": "object", "additionalProperties": true }, "conversation": { "type": "object", "additionalProperties": true } } }, "example": { "status": "started", "thread_id": "agent-aop-run_1", "trigger_type": "api", "message": "Task execution started successfully. Use the thread_id to track progress.", "aop_id": "aop_1", "aop_title": "Market Research Report Generator", "base_prompt": "Generate a comprehensive market research report", "final_prompt": "Generate a comprehensive market research report\n\n--- User Inputs ---\ncompany: Acme Corp\n", "aop_config": { "agentId": "research" } } } } }, "400": { "description": "Invalid AOP configuration or request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Forbidden. Missing OAuth scope." }, "404": { "description": "AOP or thread not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/aop/create": { "post": { "operationId": "post_v1_aop_create", "summary": "Create AOP", "description": "Create an organization-scoped AOP. Use `[[ placeholder ]]` in the prompt for user inputs supplied at execution time. Requires `aops:write`.", "tags": [ "aops" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": [ "string", "null" ] }, "prompt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "agentId": { "type": [ "string", "null" ] }, "agent_config": { "type": [ "object", "null" ], "additionalProperties": true }, "icon": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "structured_output": { "type": [ "object", "null" ], "additionalProperties": true }, "user_notification_configs": { "type": [ "object", "null" ], "additionalProperties": true }, "parent_folder_id": { "type": [ "string", "null" ], "description": "Optional workstream ID." }, "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth. Optional for API keys." } } }, "example": { "title": "Market Research Report", "prompt": "Generate a comprehensive market research report for [[ company ]]", "agentId": "research" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "aop_id", "title" ], "properties": { "aop_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "default": "created" }, "message": { "type": "string" }, "parent_folder_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid AOP configuration or request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Forbidden. Missing OAuth scope." }, "404": { "description": "AOP or thread not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/aop/retry": { "post": { "operationId": "post_v1_aop_retry", "summary": "Retry a failed AOP execution", "description": "Looks up a failed AOP thread, then enqueues a new run. Requires `aops:write`.", "tags": [ "aops" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "thread_id" ], "properties": { "thread_id": { "type": "string", "description": "Thread ID of the failed AOP execution to retry." }, "user_inputs": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Optional user inputs appended to the AOP prompt as key-value pairs." }, "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth. Optional for API keys." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "new_thread_id", "message" ], "properties": { "status": { "type": "string", "const": "started" }, "new_thread_id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid AOP configuration or request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Forbidden. Missing OAuth scope." }, "404": { "description": "AOP or thread not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/brandsgateway/import": { "post": { "operationId": "post_v1_brandsgateway_import", "summary": "Import BrandsGateway Products", "description": "Requires catalog:write and a connected BrandsGateway account. Uses the same parameters and import service as the import_brandsgateway_products tool.\n\n### Selection\n\nChoose catalogProductIds or importAllMatching with filters. maxProducts limits new imports to 1–50 across pages (default 50); already imported products are skipped. Numeric brandIds, vendorIds (supplier warehouses), categoryIds, and conditionIds arrays match any value within each field and all supplied fields together. Omit a field for no restriction; empty arrays and legacy singular/string filters are rejected. Brands accept at most 500 IDs; other filter arrays accept at most 50 each. Broad combinations may exceed the supplier request budget and return a failure asking you to narrow the filters.\n\n### Updated dates and enrichment\n\nupdatedAtMin and updatedAtMax map to the supplier updated_at_min and updated_at_max filters; dates use midnight UTC. There is no creation-date sorting. Products import as drafts. Connected marketplace selections and country apply to the entire import. Enrichment and taxonomy are queued according to the organization's BrandsGateway preferences; any AI usage is billed to that organization. This endpoint does not publish listings.\n\n### Result\n\nReturns HTTP 200 when the import attempt finishes, including partial failures. Inspect ok, data.success, counts, results, and data.error; failed or partial imports have ok=false and status=failed. Enrichment may still be running when data.enrichmentQueued=true.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "catalogProductIds": { "description": "BrandsGateway catalog product IDs (supplier numbers, not Omni product IDs). Trimmed and de-duplicated while preserving order. Max 50.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "importAllMatching": { "description": "Import up to maxProducts products matching filters instead of an explicit catalogProductIds list (defaults to 50).", "type": "boolean" }, "maxProducts": { "description": "Maximum products to import in this call (1–50, defaults to 50). Applied across all matching catalog pages. An explicit catalogProductIds selection cannot exceed this limit after deduplication.", "type": "integer", "minimum": 1, "maximum": 50 }, "excludedProductIds": { "description": "Catalog product IDs to skip when importAllMatching is true.", "maxItems": 2000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "filters": { "description": "Listing filters when importAllMatching is true. Numeric ID arrays match any ID within each field, and all supplied fields must match. Omit a field to leave it unrestricted.", "type": "object", "properties": { "q": { "type": "string", "maxLength": 120 }, "brandIds": { "description": "Numeric brand IDs. Match any selected brand. Max 500; duplicates removed in first-requested order.", "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "vendorIds": { "description": "Numeric warehouse/vendor IDs. Match any selected warehouse. Max 50; duplicates removed in first-requested order.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "categoryIds": { "description": "Numeric category IDs. Match any selected category. Max 50; duplicates removed in first-requested order.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "conditionIds": { "description": "Numeric product-condition IDs. Match any selected condition. Max 50; duplicates removed in first-requested order.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "stock": { "type": "string", "const": "instock" }, "priceMin": { "type": "string", "maxLength": 12 }, "priceMax": { "type": "string", "maxLength": 12 }, "imported": { "type": "string", "enum": [ "not_imported", "imported", "all" ] }, "updatedAtMin": { "description": "Supplier updated_at_min: only products last updated after this ISO date or date-time. Date-only values mean midnight UTC; offset date-times are converted to UTC.", "type": "string" }, "updatedAtMax": { "description": "Supplier updated_at_max: only products last updated before this ISO date or date-time. Date-only values mean midnight UTC; offset date-times are converted to UTC.", "type": "string" } }, "additionalProperties": false }, "targetMarketplaces": { "description": "Connected marketplaces to assign on import. Taxonomy enrichment uses taxonomy-capable stores from this list.", "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "marketplaceStoreSelections": { "description": "Connected store ID keyed by marketplace.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 255 } }, "country": { "description": "Shared country for the selected import stores.", "type": "string", "minLength": 2, "maxLength": 80 }, "organizationId": { "description": "Required for session auth; derived from the credential for bearer auth.", "type": "string", "minLength": 1, "maxLength": 255 } }, "additionalProperties": false }, "example": { "importAllMatching": true, "maxProducts": 10, "filters": { "categoryIds": [ 71816 ], "vendorIds": [ 73680 ], "brandIds": [ 68571, 615 ], "updatedAtMin": "2026-10-01" } } } } }, "responses": { "200": { "description": "Import attempt finished. Inspect success and per-product results, including partial failures.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "apiVersion", "operationId", "status", "data" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean" }, "catalogProductIds": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "importedProductIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "importAllMatching": { "type": "boolean" }, "succeededCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skippedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "catalogProductId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "productId": { "type": "string", "minLength": 1 }, "success": { "type": "boolean" }, "skipped": { "type": "boolean" }, "error": { "type": "string", "minLength": 1 } }, "required": [ "success" ], "additionalProperties": false } }, "runEnrichment": { "type": "boolean" }, "enrichmentQueued": { "type": "boolean", "description": "True when this import queued listing enrichment and taxonomy for importedProductIds. Do not call product_enrichment_tool again for those ids." }, "taxonomyAssignments": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "minLength": 1 }, "storeId": { "type": "string", "minLength": 1 }, "storeName": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 1 } }, "required": [ "marketplace", "storeId", "storeName", "country" ], "additionalProperties": false } }, "error": { "type": "string", "minLength": 1 } }, "required": [ "success", "catalogProductIds", "importedProductIds", "importAllMatching", "succeededCount", "failedCount", "skippedCount", "results", "runEnrichment", "enrichmentQueued", "taxonomyAssignments" ], "additionalProperties": false }, "error": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request, including nonnumeric IDs or an invalid quantity." }, "401": { "description": "Missing or invalid credentials." }, "403": { "description": "Missing catalog:write scope, insufficient permission, organization mismatch, or inactive organization." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Unexpected import failure." } } } }, "/api/v1/campaigns": { "get": { "operationId": "get_v1_campaigns", "summary": "List Campaigns", "description": "List campaigns for the authenticated organization. `stage=all` is the workspace working set: draft and running. Requires `promotions:read`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Search campaign name.", "schema": { "default": "", "type": "string", "maxLength": 160 } }, { "name": "stage", "in": "query", "required": false, "description": "`all` lists draft and running campaigns. Any other value lists that stage only.", "schema": { "default": "all", "type": "string", "enum": [ "all", "draft", "approved", "running", "ending", "completed", "archived" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort by creation or last update date.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "updatedAt" ] } }, { "name": "sortDir", "in": "query", "required": false, "description": "Sort direction; newest first by default.", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Campaign page and stage summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stage": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "approval": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "userId": { "type": "string" }, "approvedAt": { "type": "string" } }, "required": [ "revision", "userId", "approvedAt" ] }, { "type": "null" } ] }, "runId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "storeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "windowCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "offerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cleanupFailed": { "type": "boolean" } }, "required": [ "id", "organizationId", "revision", "stage", "approval", "runId", "startedAt", "endedAt", "createdAt", "updatedAt", "name", "brand", "storeCount", "windowCount", "offerCount" ] } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "summary": { "type": "object", "properties": { "totalCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Draft and running campaigns matching `q`." }, "stageCounts": { "type": "object", "propertyNames": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "totalCount", "stageCounts" ] }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "maxLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "defaultLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "offset", "limit", "total", "hasMore", "nextOffset", "maxLimit", "defaultLimit" ] } }, "required": [ "campaigns", "total", "hasMore", "nextOffset", "summary", "pagination" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:read` scope, or a session member without organization-wide access" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_campaigns", "summary": "Create Campaign", "description": "Create a draft campaign. `ownerId` and `approverId` must be members of the organization, and every store must already be connected. Requires `promotions:write`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "description": "Required for session auth. Optional for an API key, which already identifies the organization.", "type": "string", "minLength": 1, "maxLength": 120 }, "plan": { "type": "object", "properties": { "brief": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "objective": { "default": "", "type": "string", "maxLength": 8000 }, "brand": { "default": "", "type": "string", "maxLength": 160 }, "ownerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "approverId": { "type": "string", "minLength": 1, "maxLength": 160 }, "timezone": { "type": "string" }, "stores": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "marketplace", "country", "storeId" ], "additionalProperties": false } }, "serviceRequest": { "default": "", "type": "string", "maxLength": 300 }, "priority": { "default": "standard", "type": "string", "enum": [ "standard", "priority", "super_priority" ] }, "documentIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "reviewDueAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sourceCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceMarketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "sourceCountry": { "type": "string", "maxLength": 80 }, "cleanupNotes": { "default": "", "type": "string", "maxLength": 8000 } }, "required": [ "name", "ownerId", "approverId", "timezone" ], "additionalProperties": false }, "windows": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "preparesAt": { "default": null, "description": "Preparation time: publish promotions with the future live start/end. Must be at or before startsAt.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "reviewNotes": { "default": "", "type": "string", "maxLength": 8000 } }, "required": [ "id", "name", "startsAt", "endsAt" ], "additionalProperties": false } }, "offers": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "windowId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotionId": { "description": "Existing draft promotion attached to this window; the campaign controls its live dates.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "promotion": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "kind": { "description": "Canonical OmniCommerce promotion mechanic: product discount, flash sale, voucher, gift with purchase, Buy-X-Get-Y, bundle deal, or Lazada-only free shipping and early bird price.", "type": "string", "enum": [ "product_discount", "flash_sale", "voucher", "gift_with_purchase", "buy_x_get_y", "bundle_deal", "free_shipping", "early_bird_price" ] }, "salesChannels": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "pdp", "live" ] } }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0 }, "storeDiscounts": { "description": "Patch discount terms for exact target store keys; unnamed stores remain unchanged. Null discountValue restores shared campaign terms for that store.", "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "storeKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "storeKey", "discountType", "discountValue" ], "additionalProperties": false } }, "targetStores": { "description": "Up to 100 connected stores for create (required) or update. Copy marketplace, country, and storeId from get_promotions targetStores or find_products marketplaceDetails. Do not concatenate a storeKeys string.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "marketplace", "country", "storeId" ], "additionalProperties": false } }, "minSalePrice": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxDiscountAmount": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minSpend": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "voucherCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "claimStartsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "totalUsageLimit": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "perBuyerLimit": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "mechanicConfig": { "type": "object", "properties": { "voucherType": { "description": "Voucher subtype from get_promotions capabilities.voucherTypes. Browser AOP types (delivery=browser_aop) are writable Seller Center vouchers. Omit browserAutomation.aopId to use the built-in marketplace AOP.", "anyOf": [ { "type": "string", "enum": [ "shopee_shop", "shopee_product", "shopee_private", "shopee_live", "shopee_video", "shopee_new_buyer", "shopee_repeat_buyer", "shopee_campaign", "shopee_follow_prize", "shopee_exclusive_streamer", "shopee_welcome", "shopee_member_repeat_buyer", "shopee_exclusive", "shopee_redemption", "shopee_exclusive_creator", "lazada_store_follower", "lazada_regular", "lazada_store_new_buyer", "lazada_live", "lazada_offline", "lazada_co_funded", "lazada_welcome", "lazada_linked_member", "lazada_new_member", "lazada_member_exclusive", "lazada_points_redeemable", "tiktok_seller_coupon", "shopify_discount_code", "amazon_promotion_code", "zalora_seller_voucher", "ebay_coded_coupon" ] }, { "type": "null" } ] }, "voucherCampaign": { "description": "Campaign voucher targeting: exact campaignId/sessionId from Seller Center and termsAccepted only after the seller reviewed participation obligations. Required for shopee_campaign; nomination creates a draft awaiting marketplace review.", "type": "object", "properties": { "campaignId": { "type": "string", "pattern": "^[1-9]\\d{0,39}$" }, "sessionId": { "type": "string", "pattern": "^[1-9]\\d{0,39}$" }, "termsAccepted": { "type": "boolean" } }, "required": [ "campaignId", "sessionId", "termsAccepted" ], "additionalProperties": false }, "browserAutomation": { "anyOf": [ { "type": "object", "properties": { "aopId": { "type": "string", "minLength": 1, "maxLength": 160 }, "variableValues": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 160 }, "additionalProperties": { "type": "string", "maxLength": 8000 } }, "instructions": { "type": "string", "maxLength": 8000 } }, "additionalProperties": false }, { "type": "null" } ] }, "voucherScope": { "description": "shop = all products, products = selected assigned products. Repeat Buyer defaults to shop.", "type": "string", "enum": [ "products", "shop" ] }, "voucherReward": { "description": "Seller Center reward type. coins_cashback is a percentage greater than 3 and does not reduce salePrice.", "type": "string", "enum": [ "discount", "coins_cashback" ] }, "voucherAudience": { "type": "string", "enum": [ "general", "shop_follow" ] }, "repeatPurchaseMinCount": { "description": "Shopee Repeat Buyer: minimum completed shop orders, 1 or 2. Required for shopee_repeat_buyer.", "type": "integer", "minimum": 1, "maximum": 999 }, "repeatPurchaseLookbackDays": { "description": "Shopee Repeat Buyer: lookback window in days, one of 30, 90, 180 or 365. Required for shopee_repeat_buyer.", "type": "integer", "minimum": 1, "maximum": 365 }, "smartVoucher": { "description": "Shopee Smart Voucher toggle. Used by New Buyer and similar portal types.", "type": "boolean" }, "followPrizeExpiryDays": { "description": "Shopee Follow Prize: days after claim until expiry. Seller Center is 7.", "type": "integer", "minimum": 1, "maximum": 30 }, "videoDisplayMode": { "description": "Shopee Video display: shopee_video = all Shopee Video; creator_video = targeted creator videos only.", "type": "string", "enum": [ "shopee_video", "creator_video" ] }, "exclusiveCreatorUsernames": { "description": "Exclusive Creator Voucher: up to 15 Shopee usernames.", "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "exclusiveStreamerUsernames": { "description": "Exclusive Streamer Voucher: up to 15 Shopee usernames.", "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "voucherDisplayChannels": { "description": "Shopee display setting. [\"all\"] = display on all pages; [] = hidden/share by code.", "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "all", "feed", "live", "order_page", "followers", "offline" ] } }, "bundlePriceType": { "type": "string", "enum": [ "discount", "fixed_price" ] }, "bundleTiers": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "minimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "discountValue": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "minimumQuantity", "discountValue" ] } }, "thresholdType": { "type": "string", "enum": [ "item_quantity", "order_amount" ] }, "thresholdValue": { "type": "number", "exclusiveMinimum": 0 }, "giftType": { "type": "string", "enum": [ "gift", "sample" ] }, "giftQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "gifts": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "totalClaimLimit": { "type": "integer", "minimum": 1, "maximum": 99999 } }, "required": [ "productId", "totalClaimLimit" ], "additionalProperties": false } }, "buyQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "getQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "benefitProductIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "benefitType": { "type": "string", "enum": [ "free", "percentage", "fixed_amount" ] }, "benefitValue": { "type": "number", "minimum": 0 }, "maxApplicationsPerOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "bundleMinimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "shippingDeliveryOption": { "description": "Free shipping delivery option. Lazada: STANDARD (default), ECONOMY, EXPRESS, SELLER_OWN_FLEET or P2P, as offered by the store.", "type": "string", "pattern": "^[A-Z0-9_]{1,40}$" }, "shippingBudget": { "description": "Free shipping: total shipping subsidy budget in the store currency. Omit for an unlimited budget.", "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false }, "productIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "reviewNotes": { "default": "", "type": "string", "maxLength": 8000 }, "excludedReason": { "default": "", "type": "string", "maxLength": 2000 }, "source": { "type": "object", "properties": { "sheet": { "type": "string", "maxLength": 160 }, "rows": { "maxItems": 10000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "headers": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "values": { "maxItems": 10000, "type": "array", "items": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 16000 } } } }, "required": [ "sheet", "rows", "headers", "values" ], "additionalProperties": false } }, "required": [ "id", "windowId", "promotion" ], "additionalProperties": false } } }, "required": [ "brief" ], "additionalProperties": false } }, "required": [ "plan" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Campaign detail: plan, revision, executions, audit, schedule, and progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stage": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "approval": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "userId": { "type": "string" }, "approvedAt": { "type": "string" } }, "required": [ "revision", "userId", "approvedAt" ] }, { "type": "null" } ] }, "runId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "pendingChange": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "proposedBy": { "type": "string" }, "proposedAt": { "type": "string" } }, "required": [ "version", "plan", "proposedBy", "proposedAt" ] }, { "type": "null" } ], "description": "A running campaign's proposed plan, applied only when the approver approves it." } }, "required": [ "id", "organizationId", "revision", "stage", "approval", "runId", "startedAt", "endedAt", "createdAt", "updatedAt", "plan", "pendingChange" ] }, "executions": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "windowId": { "type": "string" }, "promotionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "draft", "activating", "prepared", "active", "ending", "ended", "failed" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": {}, "termsRevision": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "offerId", "windowId", "promotionId", "state", "error", "evidence", "termsRevision" ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "actorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "summary": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "brief", "window", "offer" ] }, "action": { "type": "string", "enum": [ "add", "update", "remove" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "field", "label", "from", "to" ] } } }, "required": [ "kind", "action", "id", "name", "changes" ] } }, "hiddenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "action", "actorId", "actorName", "createdAt", "details" ] } }, "readiness": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving or running the current plan." }, "pendingChangeIssues": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving the proposed live change." }, "pendingScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waitingBrowserJobCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] } }, "required": [ "windowId", "phase", "kind" ] } }, "recovery": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live", "start", "end", "revise" ] }, "state": { "type": "string" }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextRetryAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "windowId", "phase", "state", "attempt", "nextRetryAt", "error" ] } }, "cleanupFailed": { "type": "boolean" }, "progress": { "type": "object", "properties": { "asOf": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "counts": { "type": "object", "properties": { "waiting": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "preparing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "prepared": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "live": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelled": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "waiting", "preparing", "prepared", "live", "ending", "ended", "cancelled", "failed" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "name": { "type": "string" }, "error": { "type": "string" } }, "required": [ "offerId", "name", "error" ] } }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": [ "windowId", "phase", "kind", "name", "message" ] } }, "blockers": { "type": "array", "items": { "type": "string" } }, "nextWindow": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preparesAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "preparesAt", "startsAt", "endsAt" ] }, { "type": "null" } ] } }, "required": [ "asOf", "title", "description", "total", "counts", "issues", "scheduleIssues", "blockers", "nextWindow" ] } }, "required": [ "campaign", "executions", "audit", "readiness", "pendingChangeIssues", "pendingScheduleCount", "failedScheduleCount", "waitingBrowserJobCount" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:write` scope, or a session member without organization-wide access" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/campaigns/{campaignId}": { "get": { "operationId": "get_v1_campaigns_by_campaignid", "summary": "Get Campaign", "description": "Read one campaign, including its plan, executions, audit, schedule, and progress. Requires `promotions:read`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Campaign detail: plan, revision, executions, audit, schedule, and progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stage": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "approval": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "userId": { "type": "string" }, "approvedAt": { "type": "string" } }, "required": [ "revision", "userId", "approvedAt" ] }, { "type": "null" } ] }, "runId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "pendingChange": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "proposedBy": { "type": "string" }, "proposedAt": { "type": "string" } }, "required": [ "version", "plan", "proposedBy", "proposedAt" ] }, { "type": "null" } ], "description": "A running campaign's proposed plan, applied only when the approver approves it." } }, "required": [ "id", "organizationId", "revision", "stage", "approval", "runId", "startedAt", "endedAt", "createdAt", "updatedAt", "plan", "pendingChange" ] }, "executions": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "windowId": { "type": "string" }, "promotionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "draft", "activating", "prepared", "active", "ending", "ended", "failed" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": {}, "termsRevision": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "offerId", "windowId", "promotionId", "state", "error", "evidence", "termsRevision" ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "actorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "summary": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "brief", "window", "offer" ] }, "action": { "type": "string", "enum": [ "add", "update", "remove" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "field", "label", "from", "to" ] } } }, "required": [ "kind", "action", "id", "name", "changes" ] } }, "hiddenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "action", "actorId", "actorName", "createdAt", "details" ] } }, "readiness": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving or running the current plan." }, "pendingChangeIssues": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving the proposed live change." }, "pendingScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waitingBrowserJobCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] } }, "required": [ "windowId", "phase", "kind" ] } }, "recovery": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live", "start", "end", "revise" ] }, "state": { "type": "string" }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextRetryAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "windowId", "phase", "state", "attempt", "nextRetryAt", "error" ] } }, "cleanupFailed": { "type": "boolean" }, "progress": { "type": "object", "properties": { "asOf": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "counts": { "type": "object", "properties": { "waiting": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "preparing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "prepared": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "live": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelled": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "waiting", "preparing", "prepared", "live", "ending", "ended", "cancelled", "failed" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "name": { "type": "string" }, "error": { "type": "string" } }, "required": [ "offerId", "name", "error" ] } }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": [ "windowId", "phase", "kind", "name", "message" ] } }, "blockers": { "type": "array", "items": { "type": "string" } }, "nextWindow": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preparesAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "preparesAt", "startsAt", "endsAt" ] }, { "type": "null" } ] } }, "required": [ "asOf", "title", "description", "total", "counts", "issues", "scheduleIssues", "blockers", "nextWindow" ] } }, "required": [ "campaign", "executions", "audit", "readiness", "pendingChangeIssues", "pendingScheduleCount", "failedScheduleCount", "waitingBrowserJobCount" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:read` scope, or a session member without organization-wide access" }, "404": { "description": "Campaign not found for this organization" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } }, "put": { "operationId": "put_v1_campaigns_by_campaignid", "summary": "Update Campaign", "description": "Replace a draft or approved plan, or propose one change to a running plan. Send `expectedRevision` from the last read. Requires `promotions:write`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "description": "Required for session auth. Optional for an API key, which already identifies the organization.", "type": "string", "minLength": 1, "maxLength": 120 }, "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "expectedStage": { "type": "string", "enum": [ "draft", "approved" ] }, "expectedPendingVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "plan": { "type": "object", "properties": { "brief": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "objective": { "default": "", "type": "string", "maxLength": 8000 }, "brand": { "default": "", "type": "string", "maxLength": 160 }, "ownerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "approverId": { "type": "string", "minLength": 1, "maxLength": 160 }, "timezone": { "type": "string" }, "stores": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "marketplace", "country", "storeId" ], "additionalProperties": false } }, "serviceRequest": { "default": "", "type": "string", "maxLength": 300 }, "priority": { "default": "standard", "type": "string", "enum": [ "standard", "priority", "super_priority" ] }, "documentIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "reviewDueAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sourceCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceMarketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "sourceCountry": { "type": "string", "maxLength": 80 }, "cleanupNotes": { "default": "", "type": "string", "maxLength": 8000 } }, "required": [ "name", "ownerId", "approverId", "timezone" ], "additionalProperties": false }, "windows": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "preparesAt": { "default": null, "description": "Preparation time: publish promotions with the future live start/end. Must be at or before startsAt.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "reviewNotes": { "default": "", "type": "string", "maxLength": 8000 } }, "required": [ "id", "name", "startsAt", "endsAt" ], "additionalProperties": false } }, "offers": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "windowId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotionId": { "description": "Existing draft promotion attached to this window; the campaign controls its live dates.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "promotion": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "kind": { "description": "Canonical OmniCommerce promotion mechanic: product discount, flash sale, voucher, gift with purchase, Buy-X-Get-Y, bundle deal, or Lazada-only free shipping and early bird price.", "type": "string", "enum": [ "product_discount", "flash_sale", "voucher", "gift_with_purchase", "buy_x_get_y", "bundle_deal", "free_shipping", "early_bird_price" ] }, "salesChannels": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "pdp", "live" ] } }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0 }, "storeDiscounts": { "description": "Patch discount terms for exact target store keys; unnamed stores remain unchanged. Null discountValue restores shared campaign terms for that store.", "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "storeKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "storeKey", "discountType", "discountValue" ], "additionalProperties": false } }, "targetStores": { "description": "Up to 100 connected stores for create (required) or update. Copy marketplace, country, and storeId from get_promotions targetStores or find_products marketplaceDetails. Do not concatenate a storeKeys string.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "marketplace", "country", "storeId" ], "additionalProperties": false } }, "minSalePrice": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxDiscountAmount": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minSpend": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "voucherCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "claimStartsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "totalUsageLimit": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "perBuyerLimit": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "mechanicConfig": { "type": "object", "properties": { "voucherType": { "description": "Voucher subtype from get_promotions capabilities.voucherTypes. Browser AOP types (delivery=browser_aop) are writable Seller Center vouchers. Omit browserAutomation.aopId to use the built-in marketplace AOP.", "anyOf": [ { "type": "string", "enum": [ "shopee_shop", "shopee_product", "shopee_private", "shopee_live", "shopee_video", "shopee_new_buyer", "shopee_repeat_buyer", "shopee_campaign", "shopee_follow_prize", "shopee_exclusive_streamer", "shopee_welcome", "shopee_member_repeat_buyer", "shopee_exclusive", "shopee_redemption", "shopee_exclusive_creator", "lazada_store_follower", "lazada_regular", "lazada_store_new_buyer", "lazada_live", "lazada_offline", "lazada_co_funded", "lazada_welcome", "lazada_linked_member", "lazada_new_member", "lazada_member_exclusive", "lazada_points_redeemable", "tiktok_seller_coupon", "shopify_discount_code", "amazon_promotion_code", "zalora_seller_voucher", "ebay_coded_coupon" ] }, { "type": "null" } ] }, "voucherCampaign": { "description": "Campaign voucher targeting: exact campaignId/sessionId from Seller Center and termsAccepted only after the seller reviewed participation obligations. Required for shopee_campaign; nomination creates a draft awaiting marketplace review.", "type": "object", "properties": { "campaignId": { "type": "string", "pattern": "^[1-9]\\d{0,39}$" }, "sessionId": { "type": "string", "pattern": "^[1-9]\\d{0,39}$" }, "termsAccepted": { "type": "boolean" } }, "required": [ "campaignId", "sessionId", "termsAccepted" ], "additionalProperties": false }, "browserAutomation": { "anyOf": [ { "type": "object", "properties": { "aopId": { "type": "string", "minLength": 1, "maxLength": 160 }, "variableValues": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 160 }, "additionalProperties": { "type": "string", "maxLength": 8000 } }, "instructions": { "type": "string", "maxLength": 8000 } }, "additionalProperties": false }, { "type": "null" } ] }, "voucherScope": { "description": "shop = all products, products = selected assigned products. Repeat Buyer defaults to shop.", "type": "string", "enum": [ "products", "shop" ] }, "voucherReward": { "description": "Seller Center reward type. coins_cashback is a percentage greater than 3 and does not reduce salePrice.", "type": "string", "enum": [ "discount", "coins_cashback" ] }, "voucherAudience": { "type": "string", "enum": [ "general", "shop_follow" ] }, "repeatPurchaseMinCount": { "description": "Shopee Repeat Buyer: minimum completed shop orders, 1 or 2. Required for shopee_repeat_buyer.", "type": "integer", "minimum": 1, "maximum": 999 }, "repeatPurchaseLookbackDays": { "description": "Shopee Repeat Buyer: lookback window in days, one of 30, 90, 180 or 365. Required for shopee_repeat_buyer.", "type": "integer", "minimum": 1, "maximum": 365 }, "smartVoucher": { "description": "Shopee Smart Voucher toggle. Used by New Buyer and similar portal types.", "type": "boolean" }, "followPrizeExpiryDays": { "description": "Shopee Follow Prize: days after claim until expiry. Seller Center is 7.", "type": "integer", "minimum": 1, "maximum": 30 }, "videoDisplayMode": { "description": "Shopee Video display: shopee_video = all Shopee Video; creator_video = targeted creator videos only.", "type": "string", "enum": [ "shopee_video", "creator_video" ] }, "exclusiveCreatorUsernames": { "description": "Exclusive Creator Voucher: up to 15 Shopee usernames.", "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "exclusiveStreamerUsernames": { "description": "Exclusive Streamer Voucher: up to 15 Shopee usernames.", "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "voucherDisplayChannels": { "description": "Shopee display setting. [\"all\"] = display on all pages; [] = hidden/share by code.", "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "all", "feed", "live", "order_page", "followers", "offline" ] } }, "bundlePriceType": { "type": "string", "enum": [ "discount", "fixed_price" ] }, "bundleTiers": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "minimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "discountValue": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "minimumQuantity", "discountValue" ] } }, "thresholdType": { "type": "string", "enum": [ "item_quantity", "order_amount" ] }, "thresholdValue": { "type": "number", "exclusiveMinimum": 0 }, "giftType": { "type": "string", "enum": [ "gift", "sample" ] }, "giftQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "gifts": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "totalClaimLimit": { "type": "integer", "minimum": 1, "maximum": 99999 } }, "required": [ "productId", "totalClaimLimit" ], "additionalProperties": false } }, "buyQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "getQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "benefitProductIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "benefitType": { "type": "string", "enum": [ "free", "percentage", "fixed_amount" ] }, "benefitValue": { "type": "number", "minimum": 0 }, "maxApplicationsPerOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "bundleMinimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "shippingDeliveryOption": { "description": "Free shipping delivery option. Lazada: STANDARD (default), ECONOMY, EXPRESS, SELLER_OWN_FLEET or P2P, as offered by the store.", "type": "string", "pattern": "^[A-Z0-9_]{1,40}$" }, "shippingBudget": { "description": "Free shipping: total shipping subsidy budget in the store currency. Omit for an unlimited budget.", "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false }, "productIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "reviewNotes": { "default": "", "type": "string", "maxLength": 8000 }, "excludedReason": { "default": "", "type": "string", "maxLength": 2000 }, "source": { "type": "object", "properties": { "sheet": { "type": "string", "maxLength": 160 }, "rows": { "maxItems": 10000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "headers": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "values": { "maxItems": 10000, "type": "array", "items": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 16000 } } } }, "required": [ "sheet", "rows", "headers", "values" ], "additionalProperties": false } }, "required": [ "id", "windowId", "promotion" ], "additionalProperties": false } } }, "required": [ "brief" ], "additionalProperties": false } }, "required": [ "expectedRevision", "plan" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Campaign detail: plan, revision, executions, audit, schedule, and progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stage": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "approval": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "userId": { "type": "string" }, "approvedAt": { "type": "string" } }, "required": [ "revision", "userId", "approvedAt" ] }, { "type": "null" } ] }, "runId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "pendingChange": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "proposedBy": { "type": "string" }, "proposedAt": { "type": "string" } }, "required": [ "version", "plan", "proposedBy", "proposedAt" ] }, { "type": "null" } ], "description": "A running campaign's proposed plan, applied only when the approver approves it." } }, "required": [ "id", "organizationId", "revision", "stage", "approval", "runId", "startedAt", "endedAt", "createdAt", "updatedAt", "plan", "pendingChange" ] }, "executions": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "windowId": { "type": "string" }, "promotionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "draft", "activating", "prepared", "active", "ending", "ended", "failed" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": {}, "termsRevision": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "offerId", "windowId", "promotionId", "state", "error", "evidence", "termsRevision" ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "actorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "summary": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "brief", "window", "offer" ] }, "action": { "type": "string", "enum": [ "add", "update", "remove" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "field", "label", "from", "to" ] } } }, "required": [ "kind", "action", "id", "name", "changes" ] } }, "hiddenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "action", "actorId", "actorName", "createdAt", "details" ] } }, "readiness": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving or running the current plan." }, "pendingChangeIssues": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving the proposed live change." }, "pendingScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waitingBrowserJobCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] } }, "required": [ "windowId", "phase", "kind" ] } }, "recovery": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live", "start", "end", "revise" ] }, "state": { "type": "string" }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextRetryAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "windowId", "phase", "state", "attempt", "nextRetryAt", "error" ] } }, "cleanupFailed": { "type": "boolean" }, "progress": { "type": "object", "properties": { "asOf": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "counts": { "type": "object", "properties": { "waiting": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "preparing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "prepared": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "live": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelled": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "waiting", "preparing", "prepared", "live", "ending", "ended", "cancelled", "failed" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "name": { "type": "string" }, "error": { "type": "string" } }, "required": [ "offerId", "name", "error" ] } }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": [ "windowId", "phase", "kind", "name", "message" ] } }, "blockers": { "type": "array", "items": { "type": "string" } }, "nextWindow": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preparesAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "preparesAt", "startsAt", "endsAt" ] }, { "type": "null" } ] } }, "required": [ "asOf", "title", "description", "total", "counts", "issues", "scheduleIssues", "blockers", "nextWindow" ] } }, "required": [ "campaign", "executions", "audit", "readiness", "pendingChangeIssues", "pendingScheduleCount", "failedScheduleCount", "waitingBrowserJobCount" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:write` scope, or a session member without organization-wide access" }, "404": { "description": "Campaign not found for this organization" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/campaigns/{campaignId}/actions": { "post": { "operationId": "post_v1_campaigns_by_campaignid_actions", "summary": "Act on Campaign", "description": "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`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "run", "approve_and_run", "end", "resume", "retry", "approve_change", "discard_change" ] }, "expectedRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "expectedPendingVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "organizationId": { "description": "Required for session auth. Optional for an API key, which already identifies the organization.", "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "action", "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Campaign detail after the action, plus the scheduling result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stage": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "approval": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "userId": { "type": "string" }, "approvedAt": { "type": "string" } }, "required": [ "revision", "userId", "approvedAt" ] }, { "type": "null" } ] }, "runId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "pendingChange": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plan": { "$ref": "#/components/schemas/CampaignPlan" }, "proposedBy": { "type": "string" }, "proposedAt": { "type": "string" } }, "required": [ "version", "plan", "proposedBy", "proposedAt" ] }, { "type": "null" } ], "description": "A running campaign's proposed plan, applied only when the approver approves it." } }, "required": [ "id", "organizationId", "revision", "stage", "approval", "runId", "startedAt", "endedAt", "createdAt", "updatedAt", "plan", "pendingChange" ] }, "executions": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "windowId": { "type": "string" }, "promotionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "draft", "activating", "prepared", "active", "ending", "ended", "failed" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": {}, "termsRevision": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "offerId", "windowId", "promotionId", "state", "error", "evidence", "termsRevision" ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "actorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "summary": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "brief", "window", "offer" ] }, "action": { "type": "string", "enum": [ "add", "update", "remove" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "field", "label", "from", "to" ] } } }, "required": [ "kind", "action", "id", "name", "changes" ] } }, "hiddenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "action", "actorId", "actorName", "createdAt", "details" ] } }, "readiness": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving or running the current plan." }, "pendingChangeIssues": { "type": "array", "items": { "type": "string" }, "description": "Issues that block approving the proposed live change." }, "pendingScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedScheduleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waitingBrowserJobCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] } }, "required": [ "windowId", "phase", "kind" ] } }, "recovery": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live", "start", "end", "revise" ] }, "state": { "type": "string" }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextRetryAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "windowId", "phase", "state", "attempt", "nextRetryAt", "error" ] } }, "cleanupFailed": { "type": "boolean" }, "progress": { "type": "object", "properties": { "asOf": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "counts": { "type": "object", "properties": { "waiting": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "preparing": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "prepared": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "live": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelled": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "waiting", "preparing", "prepared", "live", "ending", "ended", "cancelled", "failed" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "name": { "type": "string" }, "error": { "type": "string" } }, "required": [ "offerId", "name", "error" ] } }, "scheduleIssues": { "type": "array", "items": { "type": "object", "properties": { "windowId": { "type": "string" }, "phase": { "type": "string", "enum": [ "prepare", "live" ] }, "kind": { "type": "string", "enum": [ "overdue", "missed" ] }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": [ "windowId", "phase", "kind", "name", "message" ] } }, "blockers": { "type": "array", "items": { "type": "string" } }, "nextWindow": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preparesAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "preparesAt", "startsAt", "endsAt" ] }, { "type": "null" } ] } }, "required": [ "asOf", "title", "description", "total", "counts", "issues", "scheduleIssues", "blockers", "nextWindow" ] }, "scheduling": { "type": "object", "properties": { "queued": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "boolean" } }, "required": [ "queued", "pending" ], "description": "`pending` is true when the schedule was saved but not yet acknowledged; retry the action to confirm." } }, "required": [ "campaign", "executions", "audit", "readiness", "pendingChangeIssues", "pendingScheduleCount", "failedScheduleCount", "waitingBrowserJobCount", "scheduling" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:write` scope, or a session member without organization-wide access" }, "404": { "description": "Campaign not found for this organization" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/campaigns/archive": { "post": { "operationId": "post_v1_campaigns_archive", "summary": "Archive Campaigns", "description": "Archive campaigns, or restore archived campaigns by id or by the current archived list filters. Requires `promotions:write`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "campaignIds": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "action": { "type": "string", "enum": [ "archive", "restore" ] }, "organizationId": { "description": "Required for session auth. Optional for an API key, which already identifies the organization.", "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "campaignIds", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "restore" }, "selection": { "type": "object", "properties": { "mode": { "type": "string", "const": "all_matching" }, "filters": { "type": "object", "properties": { "q": { "default": "", "type": "string", "maxLength": 160 }, "stage": { "default": "all", "type": "string", "enum": [ "all", "draft", "approved", "running", "ending", "completed", "archived" ] } }, "additionalProperties": false }, "excludedCampaignIds": { "default": [], "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "required": [ "mode", "filters" ], "additionalProperties": false }, "organizationId": { "description": "Required for session auth. Optional for an API key, which already identifies the organization.", "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "action", "selection" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Aggregate result plus one result per campaign. `success` is true only when every requested campaign succeeds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every requested campaign succeeds." }, "campaignIds": { "type": "array", "items": { "type": "string" } }, "succeededCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "campaignId": { "type": "string" }, "stage": { "type": "string", "enum": [ "draft", "approved", "running", "ending", "completed", "archived" ] }, "error": { "type": "string" } }, "required": [ "success", "campaignId" ] } } }, "required": [ "success", "campaignIds", "succeededCount", "failedCount", "results" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:write` scope, or a session member without organization-wide access" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/campaigns/delete": { "post": { "operationId": "post_v1_campaigns_delete", "summary": "Delete Campaigns", "description": "Permanently delete archived campaigns by explicit id or by archived list filters. Requires `promotions:write`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "description": "Required for session auth. Optional for an API key, which already identifies the organization.", "type": "string", "minLength": 1, "maxLength": 120 }, "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "explicit" }, "campaignIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "required": [ "mode", "campaignIds" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all_matching" }, "filters": { "type": "object", "properties": { "q": { "default": "", "type": "string", "maxLength": 160 }, "stage": { "default": "all", "type": "string", "enum": [ "all", "draft", "approved", "running", "ending", "completed", "archived" ] } }, "additionalProperties": false }, "excludedCampaignIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "required": [ "mode", "filters" ], "additionalProperties": false } ] } }, "required": [ "selection" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Aggregate result plus one result per campaign. `success` is true only when every requested campaign succeeds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every requested campaign succeeds." }, "campaignIds": { "type": "array", "items": { "type": "string" } }, "succeededCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "campaignId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success", "campaignId" ] } } }, "required": [ "success", "campaignIds", "succeededCount", "failedCount", "results" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:write` scope, or a session member without organization-wide access" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/campaigns/options": { "get": { "operationId": "get_v1_campaigns_options", "summary": "Get Campaign Options", "description": "List the organization members and connected stores a campaign plan can name. Use a member `id` for `ownerId` and `approverId`. Requires `promotions:write`.", "tags": [ "campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Members and connected stores.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "description": "Organization members. Use `id` for `ownerId` and `approverId`." }, "stores": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopify", "shopee", "lazada", "tiktok", "whatsapp", "zalora", "amazon", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 200 }, "storeName": { "type": "string", "minLength": 1, "maxLength": 255 }, "isDefaultPublish": { "type": "boolean" }, "dbsHazmatApproved": { "type": "boolean" } }, "required": [ "marketplace", "country", "storeId", "storeName" ], "additionalProperties": false }, "description": "Connected stores for `brief.stores`." }, "promotionStores": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ] }, "country": { "type": "string" }, "storeId": { "type": "string" }, "storeName": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "marketplace", "country", "storeId" ] }, "description": "Connected stores for offer `promotion.targetStores`." } }, "required": [ "members", "stores", "promotionStores" ] } } } }, "400": { "description": "Invalid campaign payload or plan state." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: missing `promotions:write` scope, or a session member without organization-wide access" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/catalog/items": { "get": { "operationId": "get_v1_catalog_items", "summary": "Export Catalog Items", "description": "Cursor-page the authenticated organization's product and variant catalog for pricing systems. Requires `catalog:read`.\n\nEach item includes product-family identity, SKU/UPC, cost, current, sale, compare-at, MAP, and MSRP prices, inventory, active promotion context, and exact marketplace identifiers. Set `format=csv` for a flat catalog-intake CSV shape.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Inclusive item update lower bound for incremental exports.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "format", "in": "query", "required": false, "description": "Use csv for the documented catalog columns; omit for JSON.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Catalog page as JSON, or CSV with X-Has-More and X-Next-Cursor headers." }, "400": { "description": "Invalid cursor or updatedSince value." }, "401": { "description": "Unauthorized." }, "403": { "description": "Missing catalog:read scope." }, "500": { "description": "Internal server error." } } } }, "/api/v1/checkout-sessions": { "post": { "operationId": "post_v1_checkout_sessions", "summary": "Create Agentic Checkout Session", "description": "Create a merchant-fulfilled checkout session, reserve inventory, and return rail-specific payment requirements. Requires an OAuth client token with `checkout:write`.", "tags": [ "agentic-checkout" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for create retries.", "schema": { "type": "string", "maxLength": 180 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations." }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ], "default": "acp_stripe" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "quantity" ], "properties": { "productId": { "type": "string", "description": "OmniCommerce product UUID." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 80 } } }, "shippingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "billingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "metadata": { "type": "object", "additionalProperties": true } } }, "example": { "organizationId": "org_123", "paymentRail": "acp_stripe", "items": [ { "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1 } ] } } } }, "responses": { "201": { "description": "Checkout session created with inventory reserved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "409": { "description": "Insufficient inventory" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/checkout-sessions/{sessionId}": { "get": { "operationId": "get_v1_checkout_sessions_by_sessionid", "summary": "Get Agentic Checkout Session", "description": "Fetch the current checkout session, cart items, totals, payment requirements, and linked order when completed.", "tags": [ "agentic-checkout" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for OAuth clients that can access multiple organizations.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Checkout session found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "500": { "description": "Internal Server Error" } } }, "put": { "operationId": "put_v1_checkout_sessions_by_sessionid", "summary": "Replace Agentic Checkout Session Fields", "description": "UCP-compatible update method for cart/contact fields. The current implementation applies provided fields and leaves omitted fields unchanged. Requires `checkout:write`.", "tags": [ "agentic-checkout" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for OAuth clients that can access multiple organizations.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "quantity" ], "properties": { "productId": { "type": "string", "description": "OmniCommerce product UUID." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 80 } } }, "shippingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "billingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Checkout session updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal session or insufficient inventory" }, "500": { "description": "Internal Server Error" } } }, "patch": { "operationId": "patch_v1_checkout_sessions_by_sessionid", "summary": "Update Agentic Checkout Session", "description": "Update cart/contact fields, recompute totals, and refresh inventory reservations before payment. Requires `checkout:write`.", "tags": [ "agentic-checkout" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for OAuth clients that can access multiple organizations.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "quantity" ], "properties": { "productId": { "type": "string", "description": "OmniCommerce product UUID." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 80 } } }, "shippingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "billingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Checkout session updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal session or insufficient inventory" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/checkout-sessions/{sessionId}/cancel": { "post": { "operationId": "post_v1_checkout_sessions_by_sessionid_cancel", "summary": "Cancel Agentic Checkout Session", "description": "Cancel a ready-for-payment checkout session and release reserved inventory. This operation is exposed for UCP REST clients and requires `checkout:write`.", "tags": [ "agentic-checkout" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for OAuth clients that can access multiple organizations.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Checkout session cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal checkout session" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/checkout-sessions/{sessionId}/complete": { "post": { "operationId": "post_v1_checkout_sessions_by_sessionid_complete", "summary": "Complete Agentic Checkout Session", "description": "Settle the selected rail and create a native `agentic` order. Settlement failures return 402 and leave the session in `ready_for_payment`.", "tags": [ "agentic-checkout" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for OAuth clients that can access multiple organizations.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for completion retries.", "schema": { "type": "string", "maxLength": 180 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "paymentProof" ], "properties": { "idempotencyKey": { "type": "string", "maxLength": 180 }, "paymentProof": { "type": "object", "additionalProperties": true, "description": "Rail-specific payment proof. ACP uses `{ sharedPaymentTokenId: string }`; x402 uses `{ paymentPayload: object }` or `{ xPayment: object }`. Local testing may use `{ test: true, testPaymentToken: string }` when test settlement is enabled." } } } } } }, "responses": { "200": { "description": "Checkout completed and native order created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } }, "settlement": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "providerPaymentId": { "type": [ "string", "null" ] }, "settlementReference": { "type": [ "string", "null" ] }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Settlement failed; the checkout remains ready for payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "agentic_checkout_v1" }, "session": { "type": "object", "required": [ "id", "organizationId", "status", "paymentRail", "currency", "totalAmount", "paymentRequirements", "expiresAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready_for_payment", "completed", "cancelled", "expired" ] }, "paymentRail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "currency": { "type": "string" }, "subtotalAmount": { "type": "number" }, "shippingAmount": { "type": "number" }, "taxAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "totalAmount": { "type": "number" }, "cartVersion": { "type": "integer" }, "buyer": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddress": { "type": "object", "additionalProperties": true }, "paymentRequirements": { "type": "object", "additionalProperties": true }, "orderId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "productSnapshot": { "type": "object", "additionalProperties": true } } } }, "settlement": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "providerPaymentId": { "type": [ "string", "null" ] }, "settlementReference": { "type": [ "string", "null" ] }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" } } } } } } } }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal or expired checkout session" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/compare": { "get": { "operationId": "get_v1_compare", "summary": "Compare Public Products", "description": "Compare 2 to 10 public products side-by-side across price, ACO readiness, marketplace coverage, and inventory.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "products", "in": "query", "required": true, "description": "Comma-separated product IDs (2..10).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Localization language. Defaults to en.", "schema": { "type": "string", "enum": [ "en", "th", "id", "ms", "vi", "tl" ], "default": "en" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "public_compare_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/directory": { "get": { "operationId": "get_v1_directory", "summary": "List Public Merchants", "description": "Discover merchants with public products available through OmniCommerce's public agent APIs.", "tags": [ "public-agent" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "public_directory_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/documents": { "post": { "operationId": "post_v1_documents", "summary": "Upload Document", "description": "Upload one file to the knowledge base as multipart/form-data. Requires `documents:write`.\n\nAccepted: PDF up to 20 MB, Word (.docx) and PowerPoint (.pptx) up to 20 MB, Excel (.xlsx/.xlsm) up to 10 MB, images up to 8 MB, CSV and Markdown up to 2 MB. PDFs, Word, PowerPoint, Markdown, and images are indexed in the background; poll `GET /api/v1/documents/{documentId}` until `status` is `completed`. CSV and Excel are stored for agents to read but are not indexed.", "tags": [ "documents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload." }, "organizationId": { "type": "string", "description": "Required for session auth. API keys already belong to one organization." }, "documentType": { "default": "other", "description": "What the document is. `bank_statement` is never shown to AI.", "type": "string", "enum": [ "datasheet", "invoice", "packing_list", "compliance_certificate", "test_report", "sds", "manual", "warranty", "authorization_letter", "shipping_doc", "regulation", "policy", "bank_statement", "other" ] }, "productId": { "description": "Attach the document to one product instead of the whole organization.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fileName": { "description": "File name to store. Defaults to the uploaded file's name.", "type": "string", "minLength": 1, "maxLength": 1024 } } } } } }, "responses": { "202": { "description": "The document was stored; indexing is queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "documentType": { "type": "string", "enum": [ "datasheet", "invoice", "packing_list", "compliance_certificate", "test_report", "sds", "manual", "warranty", "authorization_letter", "shipping_doc", "regulation", "policy", "bank_statement", "other" ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "completed_with_warnings", "failed" ], "description": "`pending` and `processing` while indexing; `completed` when agents can search it." }, "indexedChunkCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Searchable chunks. CSV and Excel are stored for reading but not indexed, so this is 0." }, "pageCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "fileName", "mimeType", "sizeBytes", "documentType", "productId", "status", "indexedChunkCount", "pageCount", "errorMessage", "createdAt", "updatedAt" ] }, "queued": { "type": "boolean", "description": "Indexing was queued." }, "warning": { "type": "string" } }, "required": [ "document", "queued" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `documents:write` scope" }, "404": { "description": "Product not found" }, "413": { "description": "The request body is not multipart or is too large" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/documents/{documentId}": { "get": { "operationId": "get_v1_documents_by_documentid", "summary": "Get Document", "description": "Read one knowledge base document and its indexing status. Requires `documents:read`.", "tags": [ "documents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "documentType": { "type": "string", "enum": [ "datasheet", "invoice", "packing_list", "compliance_certificate", "test_report", "sds", "manual", "warranty", "authorization_letter", "shipping_doc", "regulation", "policy", "bank_statement", "other" ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "completed_with_warnings", "failed" ], "description": "`pending` and `processing` while indexing; `completed` when agents can search it." }, "indexedChunkCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Searchable chunks. CSV and Excel are stored for reading but not indexed, so this is 0." }, "pageCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "fileName", "mimeType", "sizeBytes", "documentType", "productId", "status", "indexedChunkCount", "pageCount", "errorMessage", "createdAt", "updatedAt" ] } }, "required": [ "document" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `documents:read` scope" }, "404": { "description": "Document not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/evaluate": { "post": { "operationId": "post_v1_evaluate", "summary": "Evaluate SKU Readiness", "description": "Score a persisted product or inline SKU payload for agentic commerce readiness, engine eligibility, and recommended fixes.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/feed/{domain}/llms.txt": { "get": { "operationId": "get_v1_feed_by_domain_llms_txt", "summary": "Get Merchant LLM Feed", "description": "Return a plain-text, LLM-optimized merchant feed keyed by website domain.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of merchant products to include in the feed.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Merchant feed not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/images/ghost-mannequin": { "post": { "operationId": "post_v1_images_ghost_mannequin", "summary": "Generate Ghost Mannequin Image", "description": "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.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "maxLength": 4096, "description": "Publicly fetchable HTTP(S) image URL. Supported source formats are JPEG, PNG, GIF, or WebP. Data URIs are not accepted." }, "productTitle": { "type": "string", "maxLength": 160, "description": "Optional product title used only as image-edit context so the model preserves the correct garment or product type." }, "categoryName": { "type": "string", "maxLength": 160, "description": "Optional category label used only as image-edit context." }, "categoryId": { "type": "string", "maxLength": 80, "description": "Optional category ID used as fallback image-edit context when a category label is not available." } } }, "example": { "imageUrl": "https://cdn.example.com/products/dress-front.jpg", "productTitle": "Linen Wrap Dress", "categoryName": "Women Clothes > Dresses" } } } }, "responses": { "200": { "description": "Ghost mannequin image generated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "image" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "image": { "type": "string", "description": "Remote HTTP(S) URL for the generated ghost mannequin image stored by OmniCommerce." } } }, "example": { "ok": true, "apiVersion": "developer_v1", "operationId": "8f7e8f8f-2b9e-46e6-a2c0-50d0f4612b2d", "status": "completed", "warnings": [], "recommendations": [], "image": "https://cdn.example.com/generated/ghost-mannequin.webp" } } } }, "400": { "description": "Bad Request - invalid JSON or imageUrl" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing catalog:enrich scope" }, "502": { "description": "Image generation failed or the generated image could not be retrieved." } } } }, "/api/v1/jobs/{jobId}": { "get": { "operationId": "get_v1_jobs_by_jobid", "summary": "Get Developer Job Status", "description": "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.\n\nPrice comparison jobs expose partial progress in data.results and their final batch result in data.result; completed means processing finished, so inspect data.result.success for comparison failures.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session-authenticated requests; derived from API keys.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/jobs/{jobId}/cancel": { "post": { "operationId": "post_v1_jobs_by_jobid_cancel", "summary": "Cancel Developer Job", "description": "Request cancellation for a running or pending developer job.\n\nSupported jobs:\n\n- Product workflows returned by `POST /api/v1/products`\n\n- Bulk CSV imports returned by `POST /api/v1/products/bulk-import`\n\n- Look generation returned by `POST /api/v1/looks`\n\nCompleted or failed jobs cannot be cancelled and are returned with their current terminal status.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "description": "Optional for API-key requests; required only when cancelling with a browser session across multiple organizations." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/looks": { "get": { "operationId": "get_v1_looks", "summary": "List Looks", "description": "List AI-styled product Looks for the authenticated organization, newest first. Use query parameters for search, status filtering, and pagination.", "tags": [ "looks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search by look title, city, style, or generated prompt.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by look status.", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit per page. Defaults to 24; maximum is 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 24 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Looks page for the authenticated organization.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "organizationId", "status", "createdAt", "updatedAt", "productCount" ], "properties": { "id": { "type": "string", "description": "Look UUID." }, "organizationId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "subject": { "type": [ "string", "null" ] }, "style": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "timeOfDay": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "additionalNotes": { "type": [ "string", "null" ] }, "stylePrompt": { "type": [ "string", "null" ], "description": "One-sentence prompt used for image generation." }, "heroImageTagId": { "type": [ "string", "null" ], "description": "Generated image_tags UUID when image tagging succeeded." }, "heroImageUrl": { "type": [ "string", "null" ], "description": "Remote HTTP(S) URL for the generated look image." }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ] }, "productCount": { "type": "integer", "minimum": 0 } } } }, "pagination": { "type": "object", "required": [ "offset", "limit", "total", "hasMore" ], "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] } } } } }, "example": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "organizationId": "org_123", "title": "Spring city edit", "status": "draft", "subject": "model", "style": "Chic", "season": "Spring", "timeOfDay": "Day", "city": "Paris", "heroImageUrl": "https://cdn.example.com/looks/spring.png", "productCount": 3, "createdAt": "2026-07-04T00:00:00.000Z", "updatedAt": "2026-07-04T00:01:00.000Z" } ], "pagination": { "offset": 0, "limit": 24, "total": 1, "hasMore": false, "nextOffset": null } } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_looks", "summary": "Create Look", "description": "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}`.", "tags": [ "looks" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "productIds" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations." }, "title": { "type": "string", "maxLength": 160 }, "productIds": { "type": "array", "minItems": 1, "maxItems": 9, "description": "Ordered OmniCommerce product UUIDs to use as visual references. The first item is the primary product; the rest are reference products.", "items": { "type": "string" } }, "subject": { "type": "string", "maxLength": 120, "description": "Scene subject such as model, table setting, shelf, desk setup, or free text." }, "style": { "type": "string", "maxLength": 120 }, "season": { "type": "string", "maxLength": 80 }, "timeOfDay": { "type": "string", "maxLength": 80 }, "city": { "type": "string", "maxLength": 160 }, "additionalNotes": { "type": "string", "maxLength": 1000, "description": "Additional one-look styling guidance for the AI." }, "model": { "type": "string", "maxLength": 120, "description": "Optional image model override. Looks default to the organization's configured image model and optimize for faster preview generation." } } }, "example": { "productIds": [ "33333333-3333-5333-8333-333333333333", "44444444-4444-5444-8444-444444444444" ], "title": "Spring city edit", "subject": "model", "style": "Chic", "season": "Spring", "timeOfDay": "Day", "city": "Paris", "additionalNotes": "Cafe terrace, relaxed luxury styling" } } } }, "responses": { "202": { "description": "Look record created and preview image generation queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "apiVersion", "operationId", "status", "jobId", "data" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted" ] }, "jobId": { "type": "string", "description": "Async look generation job ID. Look jobs use the `look_` prefix." }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "required": [ "look" ], "properties": { "look": { "type": "object", "required": [ "id", "organizationId", "status", "createdAt", "updatedAt", "productCount" ], "properties": { "id": { "type": "string", "description": "Look UUID." }, "organizationId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "subject": { "type": [ "string", "null" ] }, "style": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "timeOfDay": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "additionalNotes": { "type": [ "string", "null" ] }, "stylePrompt": { "type": [ "string", "null" ], "description": "One-sentence prompt used for image generation." }, "heroImageTagId": { "type": [ "string", "null" ], "description": "Generated image_tags UUID when image tagging succeeded." }, "heroImageUrl": { "type": [ "string", "null" ], "description": "Remote HTTP(S) URL for the generated look image." }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ] }, "productCount": { "type": "integer", "minimum": 0 } } } } } } }, "example": { "ok": true, "apiVersion": "developer_v1", "operationId": "8f7e8f8f-2b9e-46e6-a2c0-50d0f4612b2d", "status": "accepted", "jobId": "look_7e1d7c4c-7c44-4a57-bf46-75a10f1b8e31", "warnings": [], "recommendations": [ "Poll GET /api/v1/jobs/{jobId}?organizationId={organizationId} until status is completed or failed." ], "links": { "job": "/api/v1/jobs/look_7e1d7c4c-7c44-4a57-bf46-75a10f1b8e31?organizationId=org_123", "look": "/api/v1/looks/11111111-1111-4111-8111-111111111111" }, "data": { "look": { "id": "11111111-1111-4111-8111-111111111111", "organizationId": "org_123", "title": "Spring city edit", "status": "draft", "style": "Chic", "productCount": 2, "createdAt": "2026-07-04T00:00:00.000Z", "updatedAt": "2026-07-04T00:00:00.000Z" } } } } } }, "400": { "description": "Bad Request - invalid payload, duplicate product IDs, or products not owned by the organization" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing catalog:write scope or organization access" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/looks/{lookId}": { "get": { "operationId": "get_v1_looks_by_lookid", "summary": "Get Look", "description": "Fetch a single Look by ID, including the generated hero image URL and the shoppable product cards used in the Look.", "tags": [ "looks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lookId", "in": "path", "required": true, "description": "Look UUID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Look detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "look" ], "properties": { "look": { "type": "object", "required": [ "id", "organizationId", "status", "createdAt", "updatedAt", "productCount", "products" ], "properties": { "id": { "type": "string", "description": "Look UUID." }, "organizationId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "subject": { "type": [ "string", "null" ] }, "style": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "timeOfDay": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "additionalNotes": { "type": [ "string", "null" ] }, "stylePrompt": { "type": [ "string", "null" ], "description": "One-sentence prompt used for image generation." }, "heroImageTagId": { "type": [ "string", "null" ], "description": "Generated image_tags UUID when image tagging succeeded." }, "heroImageUrl": { "type": [ "string", "null" ], "description": "Remote HTTP(S) URL for the generated look image." }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ] }, "productCount": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID." }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ], "description": "Remote HTTP(S) catalog image URL." } } } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "404": { "description": "Look Not Found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/manage-product-category/recommend": { "post": { "operationId": "post_v1_manage_product_category_recommend", "summary": "Recommend Marketplace Product Categories", "description": "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_...`.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "productId", "targets" ], "properties": { "organizationId": { "type": "string", "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations." }, "productId": { "type": "string", "description": "OmniCommerce product ID. The API key must belong to the organization that owns this product." }, "targets": { "type": "array", "description": "Marketplace/country targets to recommend categories for.", "items": { "type": "object", "additionalProperties": false, "required": [ "marketplace" ], "properties": { "marketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "country": { "type": "string", "description": "Marketplace country code or name, for example singapore, malaysia, sg, or my." } } } }, "query": { "type": "string", "minLength": 2, "maxLength": 4000, "description": "Optional product-context query. When omitted, OmniCommerce derives it from product title, brand, SKU, highlights, tags, and description." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Maximum category candidates per marketplace." }, "includeAttributeAutoValues": { "type": "boolean", "default": true, "description": "When true, uses product context and category attribute metadata to suggest autofill values." }, "model": { "type": "string", "maxLength": 100, "description": "Optional model override for attribute autofill suggestions." } } }, "example": { "productId": "prod_123", "targets": [ { "marketplace": "lazada", "country": "singapore" }, { "marketplace": "shopee", "country": "malaysia" } ], "limit": 5, "includeAttributeAutoValues": true } } } }, "responses": { "200": { "description": "Semantic category recommendations with attribute metadata and suggested attribute values.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "apiVersion", "operationId", "status", "productId", "success", "marketplaces" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "success": { "type": "boolean" }, "marketplaces": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "existsOnProduct": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "string" }, "label": { "type": "string" }, "marketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "country": { "type": [ "string", "null" ] }, "similarity": { "type": [ "number", "null" ] }, "attributes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "variantAttributes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "suggestedAttributeValues": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "suggestionMeta": { "type": "object", "additionalProperties": true } } } } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Product Not Found" }, "422": { "description": "Product has no searchable category text" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/marketplaces/connected": { "get": { "operationId": "get_v1_marketplaces_connected", "summary": "List Connected Marketplaces", "description": "List connected marketplace stores for the authenticated organization. Results are scoped to the API key organization unless `organizationId` is supplied for session-authenticated calls.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional marketplace filter.", "schema": { "type": "string", "enum": [ "shopify", "shopee", "lazada", "tiktok", "whatsapp", "zalora", "amazon", "ebay" ] } }, { "name": "country", "in": "query", "required": false, "description": "Optional country filter, for example singapore, malaysia, sg, or my.", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Connected marketplace stores for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "organizationId": { "type": "string" }, "connectedMarketplaces": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopify", "shopee", "lazada", "tiktok", "whatsapp", "zalora", "amazon", "ebay" ] }, "country": { "type": "string" }, "storeId": { "type": "string" }, "storeName": { "type": "string" }, "isDefaultPublish": { "type": "boolean" } } } }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopify", "shopee", "lazada", "tiktok", "whatsapp", "zalora", "amazon", "ebay" ] }, "countries": { "type": "array", "items": { "type": "string" } }, "storeCount": { "type": "integer" }, "defaultStoreCount": { "type": "integer" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/merchants/{merchantId}/manifest": { "get": { "operationId": "get_v1_merchants_by_merchantid_manifest", "summary": "Get Public Merchant Manifest", "description": "Return machine-readable capability and endpoint metadata for a single public merchant.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "merchant_manifest_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/merchants/{merchantId}/products": { "get": { "operationId": "get_v1_merchants_by_merchantid_products", "summary": "List Public Merchant Products", "description": "Browse a single merchant's public product feed with optional marketplace and localization filters.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, { "name": "country", "in": "query", "required": false, "description": "Marketplace country hint (example: sg).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Localization language. Defaults to en.", "schema": { "type": "string", "enum": [ "en", "th", "id", "ms", "vi", "tl" ], "default": "en" } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit (1..100). Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (0..10000). Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "merchant_products_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/merchants/{merchantId}/search": { "get": { "operationId": "get_v1_merchants_by_merchantid_search", "summary": "Search Within Public Merchant Catalog", "description": "Search within a single merchant's public product feed using the same filter model as the cross-merchant search API.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "ISO currency code. Required for price ranges and price sorting; no cross-currency ranking or conversion.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "min_rating", "in": "query", "required": false, "description": "Minimum average imported product review rating. Unrated products do not match; not a marketplace-wide lifetime rating.", "schema": { "type": "number", "minimum": 1, "maximum": 5 } }, { "name": "min_review_count", "in": "query", "required": false, "description": "Minimum number of imported rated product reviews.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "added_after", "in": "query", "required": false, "description": "Inclusive catalog creation timestamp with time zone. Does not mean product release date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "variant_options", "in": "query", "required": false, "description": "JSON array of 1-5 exact, case-insensitive option pairs, e.g. [{\"name\":\"Color\",\"value\":\"Red\"}]. All options must match the same variant.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Natural-language search query.", "schema": { "type": "string", "maxLength": 300 } }, { "name": "category", "in": "query", "required": false, "description": "Optional category-name filter.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "brand", "in": "query", "required": false, "description": "Optional brand filter.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum catalogPrice in the requested currency (inclusive). Requires currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum catalogPrice in the requested currency (inclusive). Requires currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "in_stock", "in": "query", "required": false, "description": "Filter by stock availability.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by relevance, newest catalog addition, catalog price, imported average rating, or review count. Price sorting requires currency; most_reviewed is not best selling.", "schema": { "type": "string", "enum": [ "relevance", "newest", "price_asc", "price_desc", "rating_desc", "most_reviewed" ], "default": "relevance" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, { "name": "country", "in": "query", "required": false, "description": "Marketplace country hint (example: sg).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Localization language. Defaults to en.", "schema": { "type": "string", "enum": [ "en", "th", "id", "ms", "vi", "tl" ], "default": "en" } }, { "name": "include_intent", "in": "query", "required": false, "description": "Include lightweight parsed query intent metadata.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit (1..100). Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (0..10000). Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "merchant_search_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/monitor": { "post": { "operationId": "post_v1_monitor", "summary": "Run AI Shelf Share Monitor", "description": "Queue AI Shelf Share replay/monitoring for a product, query, or organization catalog.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/oauth/revoke": { "post": { "operationId": "post_v1_oauth_revoke", "summary": "Revoke Access Token", "description": "Revoke an OAuth bearer access token using client_secret_post authentication.", "tags": [ "oauth" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token", "client_id", "client_secret" ], "properties": { "token": { "type": "string", "description": "Bearer access token to revoke." }, "token_type_hint": { "type": "string", "enum": [ "access_token" ], "description": "Optional OAuth token type hint." }, "client_id": { "type": "string", "description": "Your OAuth client ID." }, "client_secret": { "type": "string", "description": "Your OAuth client secret." } } }, "example": { "token": "", "token_type_hint": "access_token", "client_id": "your-client-id-uuid", "client_secret": "your-client-secret" } }, "application/json": { "schema": { "type": "object", "required": [ "token", "client_id", "client_secret" ], "properties": { "token": { "type": "string", "description": "Bearer access token to revoke." }, "token_type_hint": { "type": "string", "enum": [ "access_token" ] }, "client_id": { "type": "string", "description": "Your OAuth client ID." }, "client_secret": { "type": "string", "description": "Your OAuth client secret." } } } } } }, "responses": { "200": { "description": "Token revocation accepted. The response body is intentionally empty." }, "400": { "description": "Bad Request - Missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid client credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_client" ] }, "error_description": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/oauth/token": { "post": { "operationId": "post_v1_oauth_token", "summary": "Get Access Token", "description": "Exchange client credentials for an access token using OAuth 2.0 client_credentials grant. Tokens are valid for 1 hour.", "tags": [ "oauth" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Must be 'client_credentials'." }, "client_id": { "type": "string", "description": "Your OAuth client ID (UUID format)." }, "client_secret": { "type": "string", "description": "Your OAuth client secret." } } }, "example": { "grant_type": "client_credentials", "client_id": "your-client-id-uuid", "client_secret": "your-client-secret" } }, "application/json": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Must be 'client_credentials'." }, "client_id": { "type": "string", "description": "Your OAuth client ID (UUID format)." }, "client_secret": { "type": "string", "description": "Your OAuth client secret." } } } } } }, "responses": { "200": { "description": "Token issued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "JWT access token to use in Authorization header." }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "Token type (always 'Bearer')." }, "expires_in": { "type": "integer", "description": "Token validity in seconds (3600 = 1 hour)." } } }, "example": { "access_token": "", "token_type": "Bearer", "expires_in": 3600 } } } }, "400": { "description": "Bad Request - Missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid client credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_client" ] }, "error_description": { "type": "string" } } } } } } } } }, "/api/v1/orders": { "get": { "operationId": "get_v1_orders", "summary": "List Orders", "description": "List orders for the authenticated organization using the same filters, sorting, and pagination semantics as the workspace Orders listing page. Requires `orders:read`.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Search order number, external order ID, buyer fields, and line-item product/SKU fields.", "schema": { "type": "string", "maxLength": 140 } }, { "name": "status", "in": "query", "required": false, "description": "Orders listing status filter. Groups are to_ship, shipped, completed, pending, return, and canceled. awaiting_collection is packed orders waiting for carrier pickup. Shopify, Amazon, and eBay have no separate collection status.", "schema": { "type": "string", "enum": [ "to_ship", "shipped", "completed", "pending", "return", "canceled", "awaiting_collection" ] } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplace platforms (for example `shopee,lazada,tiktok,zalora`).", "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated normalized country codes.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated marketplace account IDs.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "bundleType", "in": "query", "required": false, "description": "Filter whole orders by recorded catalog bundle type, with mapped catalog fallback for legacy lines. Hard/virtual match any line; non_bundle requires no bundle lines. Marketplace bundle-deal promotions alone are not catalog bundles.", "schema": { "type": "string", "enum": [ "", "hard", "virtual", "non_bundle" ] } }, { "name": "sortBy", "in": "query", "required": false, "description": "Comma-separated sort tokens. Supports multi-sort up to six tokens. Aliases: `latest` -> `updated_desc`, `oldest` -> `updated_asc`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive lower bound on order created date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Inclusive upper bound on order created date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit per page. Values above 50 are clamped silently. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset. Use `pagination.nextOffset` from the previous response to page forward.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Orders page returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "paymentReceived": { "type": [ "number", "null" ], "description": "Formula-net marketplace payment. Null until every active line has been reconciled." }, "orderCogs": { "type": [ "number", "null" ], "description": "Order-time COGS total. Null while any active line lacks a cost snapshot." }, "orderProfit": { "type": [ "number", "null" ] }, "orderMargin": { "type": [ "number", "null" ] }, "hasReturnSignal": { "type": "boolean" }, "returnRefundAmount": { "type": "number", "minimum": 0 }, "returnState": { "type": "string", "enum": [ "none", "partial", "full" ] }, "includeInSalesMetrics": { "type": "boolean" } } } }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer" }, "summary": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "toShipCount": { "type": "integer" }, "shippedCount": { "type": "integer" }, "completedCount": { "type": "integer" }, "pendingCount": { "type": "integer" }, "returnCount": { "type": "integer" }, "canceledCount": { "type": "integer" }, "awaitingCollectionCount": { "type": "integer", "description": "Packed orders waiting for carrier pickup." } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] }, "maxLimit": { "type": "integer" }, "defaultLimit": { "type": "integer" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `orders:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_orders", "summary": "Create Order", "description": "Create a native `agentic` order with line items. This operation uses the same upsert path as agentic checkout completion.\n\n### Authentication\n\nRequires `orders:write`.\n\n### Upsert behavior\n\n- Reusing an `externalOrderId` updates the existing order instead of creating a duplicate.\n- For one-row-per-SKU integrations, use the marketplace order ID as `externalOrderId` and the row ID as `items[].externalOrderItemId`.\n- When `totalAmount` is omitted, OmniCommerce recomputes it from all order lines after the upsert.\n\n### Pricing and catalog defaults\n\n- Each line can provide `price`, `unitPrice`, `paidPrice`, and `costPrice`.\n- When `productId` is provided, missing price or currency values may resolve from the product catalog.\n- An explicit `costPrice` updates `product_data.costPrice` and is snapshotted on the order line. Omitting it never clears an existing product cost.\n\n### Country resolution\n\nWhen `country` is empty, OmniCommerce may derive it from an unambiguous order currency, such as PHP for the Philippines. USD is not used to infer a country.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations." }, "externalOrderId": { "type": "string", "maxLength": 160, "description": "Stable external order identifier and upsert key (unique per org + agentic platform). For marketplace recon (e.g. Zalora), use the marketplace order number — not a partner per-SKU row id. When omitted, OmniCommerce generates a developer order ID. Re-posting the same value upserts the same order and appends/updates lines by externalOrderItemId." }, "externalOrderNumber": { "type": "string", "maxLength": 160, "description": "Customer-facing order number. Defaults to externalOrderId when omitted." }, "platform": { "type": "string", "enum": [ "agentic" ], "default": "agentic" }, "status": { "type": "string", "enum": [ "pending", "to_ship", "shipped", "completed", "return", "canceled" ], "default": "pending", "description": "Canonical order status. Same enum as PATCH /api/v1/orders/{orderId}." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 order currency. Prefer marketplace market currency for recon (e.g. PHP for Zalora PH). When country is empty, unambiguous market currencies also derive country (SGD→singapore, MYR→malaysia, PHP→philippines, HKD→hong kong, etc.). USD is not used to derive country." }, "totalAmount": { "type": "number", "minimum": 0, "description": "Order total. When omitted, Omni recomputes from all line paid/unit prices × quantity after item upsert (safe for sequential one-line-at-a-time multi-SKU pushes). When provided, the explicit value is stored as-is." }, "shippingFee": { "type": "number", "minimum": 0 }, "discountAmount": { "type": "number", "minimum": 0 }, "country": { "type": "string", "maxLength": 80, "description": "Marketplace country (code or name, e.g. SG, singapore, PH, philippines). Optional. When omitted or empty, Omni derives from order currency when unambiguous (SGD→singapore, MYR→malaysia, PHP→philippines, HKD→hong kong, THB→thailand, VND→vietnam, IDR→indonesia, TWD→taiwan, BRL→brazil). Explicit country always wins. Shipping address country is used when top-level country is omitted. Stored as a canonical full name when possible." }, "accountId": { "type": "string", "maxLength": 160 }, "buyer": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 80 } } }, "shippingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "billingAddress": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 200 }, "line1": { "type": "string", "maxLength": 300 }, "line2": { "type": "string", "maxLength": 300 }, "city": { "type": "string", "maxLength": 160 }, "region": { "type": "string", "maxLength": 160 }, "postalCode": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 } } }, "orderCreatedAt": { "type": "string", "format": "date-time", "description": "Order created timestamp (ISO 8601 with timezone). Defaults to now. Re-posting the same externalOrderId does not overwrite an existing created date; use PATCH /api/v1/orders/{orderId} to correct it." }, "orderUpdatedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Order lines. Partners with one row per SKU can send one item per request or all items in one request; reuse the same externalOrderId and distinct externalOrderItemId values.", "items": { "type": "object", "additionalProperties": false, "required": [ "productName", "quantity" ], "properties": { "externalOrderItemId": { "type": "string", "maxLength": 160, "description": "Stable line identifier used for upserts and marketplace recon (e.g. Zalora order item id, or a partner per-SKU row id). When omitted, Omni generates `{externalOrderId}-{index}`. Prefer setting this when partners store one row per SKU." }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string", "minLength": 1, "maxLength": 500 }, "sku": { "type": "string", "maxLength": 160 }, "sellerSku": { "type": "string", "maxLength": 160, "description": "Seller SKU. Used as a secondary match key for marketplace recon (e.g. Zalora) when unique on the order." }, "shopSku": { "type": "string", "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9999 }, "price": { "type": "number", "minimum": 0, "description": "Alias for `unitPrice` (list / original unit price). Prefer `unitPrice` on new integrations. When list and paid amounts are the same, you may send only `price` or only `paidPrice`. When omitted together with unitPrice/paidPrice, may resolve from the product catalog if productId is provided." }, "unitPrice": { "type": "number", "minimum": 0, "description": "Per-unit list / original (sticker) price before line discounts. Same meaning as `price`. Not the order total. Use with `paidPrice` when you need list vs discounted; otherwise one of unitPrice/price/paidPrice is enough." }, "paidPrice": { "type": "number", "minimum": 0, "description": "Per-unit amount actually charged after discounts (what the buyer paid for one unit). Preferred for order totals, GMV, and return refund estimates: total line money uses paidPrice×quantity when set, else unitPrice/price×quantity. Not COGS (see costPrice). Not marketplace fees." }, "costPrice": { "type": "number", "minimum": 0, "description": "Unit cost (COGS). When provided with productId, updates the reusable product_data.costPrice catalog default. The metadata.costPrice order-line snapshot is canonical for historical P&L. Omitted costPrice never clears existing product or line cost. When omitted with productId on create, the line snapshot may resolve from the product catalog. Distinct from price/unitPrice/paidPrice (selling prices). Stored in the local/target currency after FX when costPriceCurrency is set." }, "costPriceCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO currency of the raw costPrice (e.g. USD) before conversion. Required when cost is not already in the order/line currency. Alias: costCurrency." }, "costCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Alias for costPriceCurrency." }, "costPriceFxRate": { "type": "number", "exclusiveMinimum": 0, "description": "Manual FX rate: units of costPriceFxTo per 1 unit of costPriceCurrency (USD→MYR at 4.45 means 1 USD = 4.45 MYR). Omit to auto-fetch the rate from Frankfurter (ECB daily rates)." }, "costPriceFxTo": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Target currency for the conversion. Defaults to the line currency, then the order currency, and must match that accounting currency when one is present." }, "costPriceFxAsOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "description": "Pins the auto-fetched rate to a date: YYYY-MM-DD, or YYYY-MM for the last calendar day of that month. Omit to use the latest rate." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "status": { "type": "string", "enum": [ "pending", "to_ship", "shipped", "completed", "return", "canceled" ], "description": "Canonical order status for the line item." }, "imageUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "variation": { "type": "string", "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": true } } } }, "metadata": { "type": "object", "additionalProperties": true } } }, "examples": { "singleLine": { "summary": "Single-line agentic order", "value": { "organizationId": "org_123", "externalOrderId": "partner-order-1001", "externalOrderNumber": "PO-1001", "status": "pending", "currency": "USD", "totalAmount": 49.99, "buyer": { "name": "Alex Buyer", "email": "alex@example.com" }, "shippingAddress": { "line1": "123 Market Street", "city": "Singapore", "country": "SG" }, "items": [ { "productId": "11111111-1111-4111-8111-111111111111", "productName": "Linen Wrap Dress", "sku": "DRESS-001", "quantity": 1, "price": 49.99, "unitPrice": 49.99, "paidPrice": 49.99, "costPrice": 20, "currency": "USD" } ] } }, "multiSkuMarketplaceCart": { "summary": "Multi-SKU marketplace cart (one Omni order; partner row ids as line ids)", "description": "Use the marketplace order id as externalOrderId. Put each partner per-SKU row id on externalOrderItemId. Omit totalAmount so Omni recomputes from all lines when appending.", "value": { "organizationId": "org_123", "externalOrderId": "3012345678", "externalOrderNumber": "3012345678", "status": "to_ship", "currency": "SGD", "items": [ { "externalOrderItemId": "ORD-9001", "sku": "SKU-A", "sellerSku": "SKU-A", "productName": "Item A", "quantity": 1, "paidPrice": 50, "currency": "SGD" }, { "externalOrderItemId": "ORD-9002", "sku": "SKU-B", "sellerSku": "SKU-B", "productName": "Item B", "quantity": 1, "paidPrice": 40, "currency": "SGD" } ] } } } } } }, "responses": { "200": { "description": "Existing order updated for the same platform/externalOrderId pair.", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Order created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `orders:write` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/orders/{orderId}": { "get": { "operationId": "get_v1_orders_by_orderid", "summary": "Get Order", "description": "Get one order by its OmniCommerce UUID for the authenticated organization.\n\n### Authentication\n\nRequires `orders:read`.\n\n### Response\n\nThe organization-scoped detail includes:\n\n- Line items and normalized status\n- Buyer and contact fields\n- Shipping and billing addresses\n- Return context\n- Finance breakdown\n- Settlement projection, when available\n\nOrders outside the authenticated organization are not exposed and return `404 Not Found`.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "OmniCommerce order UUID returned from create or list.", "schema": { "type": "string", "format": "uuid" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Order detail returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ok", "apiVersion", "operationId", "status", "data", "warnings", "recommendations", "links" ], "properties": { "ok": { "type": "boolean", "const": true }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "completed" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "additionalProperties": false, "required": [ "order" ], "properties": { "order": { "type": "object", "additionalProperties": true, "required": [ "id", "externalOrderId", "externalOrderNumber", "marketplace", "status", "statusGroup", "country", "storeId", "currency", "totalAmount", "shippingFee", "discountAmount", "createdAt", "updatedAt", "lines" ], "properties": { "id": { "type": "string", "format": "uuid" }, "externalOrderId": { "type": "string" }, "externalOrderNumber": { "type": [ "string", "null" ] }, "marketplaceOrderUrl": { "type": [ "string", "null" ], "format": "uri" }, "marketplace": { "type": "string" }, "marketplaceLabel": { "type": "string" }, "status": { "type": "string", "description": "Normalized display status for the source order." }, "statusLabel": { "type": "string" }, "statusGroup": { "type": "string", "enum": [ "to_ship", "shipped", "completed", "pending", "return", "canceled" ], "description": "Provider-neutral status for integration logic." }, "country": { "type": [ "string", "null" ] }, "storeId": { "type": [ "string", "null" ], "description": "Exact connected marketplace account ID." }, "storeLabel": { "type": [ "string", "null" ] }, "buyerName": { "type": [ "string", "null" ] }, "buyerUserId": { "type": [ "string", "null" ] }, "buyerUsername": { "type": [ "string", "null" ] }, "buyerPhone": { "type": [ "string", "null" ] }, "shippingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "billingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "currency": { "type": "string" }, "totalAmount": { "type": [ "number", "null" ] }, "shippingFee": { "type": [ "number", "null" ] }, "discountAmount": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sellerNote": { "type": [ "object", "null" ], "additionalProperties": true }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "id", "externalOrderItemId", "name", "quantity", "status", "currency", "unitPrice", "paidPrice", "lineTotal", "costPrice", "costPriceCurrency", "productId", "variantId" ], "properties": { "id": { "type": "string" }, "externalOrderItemId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "quantity": { "type": "integer", "minimum": 0 }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "sellerSku": { "type": [ "string", "null" ] }, "shopSku": { "type": [ "string", "null" ] }, "variation": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "unitPrice": { "type": [ "number", "null" ] }, "paidPrice": { "type": [ "number", "null" ] }, "lineTotal": { "type": [ "number", "null" ] }, "costPrice": { "type": [ "number", "null" ], "description": "Historical order-line cost snapshot in costPriceCurrency when available." }, "costPriceCurrency": { "type": [ "string", "null" ] }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "productVersionId": { "type": [ "string", "null" ] }, "productVersionNumber": { "type": [ "integer", "null" ] }, "bundle": { "type": [ "object", "null" ], "description": "Virtual bundle components for this order line. Order snapshots preserve the composition first observed by Omni; current_catalog is an explicitly non-historical fallback for legacy lines.", "required": [ "type", "compositionSource", "capturedAt", "components" ], "properties": { "type": { "type": "string", "const": "virtual" }, "compositionSource": { "type": "string", "enum": [ "order_snapshot", "current_catalog" ] }, "capturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "components": { "type": "array", "items": { "type": "object", "required": [ "productId", "sku", "name", "quantityPerBundle", "quantityRequired" ], "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "quantityPerBundle": { "type": "integer", "minimum": 1 }, "quantityRequired": { "type": "integer", "minimum": 0, "description": "Units per bundle multiplied by the order-line quantity." } } } } } } } } }, "cancellationDetails": { "type": [ "object", "null" ], "additionalProperties": true }, "returnCompletion": { "type": [ "object", "null" ], "additionalProperties": true }, "statusHistory": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "financeBreakdown": { "type": [ "object", "null" ], "additionalProperties": true }, "settlementProjection": { "type": [ "object", "null" ], "additionalProperties": true } } } } } } } } } }, "400": { "description": "Invalid order UUID or organization scope." }, "401": { "description": "Unauthorized." }, "403": { "description": "Forbidden or missing `orders:read` scope." }, "404": { "description": "Order not found for this organization." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal server error." } } }, "patch": { "operationId": "patch_v1_orders_by_orderid", "summary": "Update Order", "description": "Update a native **agentic** order.\n\n### Authentication\n\nRequires `orders:write`.\n\n### Supported changes\n\n- External order identifiers, status, currency, and country\n- `totalAmount`, `shippingFee`, and `discountAmount`\n- Metadata and `orderCreatedAt`\n- Line identifiers, prices, COGS, currency, status, and quantity\n\n### Line upserts\n\n- A matching `externalOrderItemId` updates the existing line.\n- A new `externalOrderItemId` with `productName` and `quantity` appends a line.\n- When lines change and `totalAmount` is omitted, OmniCommerce recomputes the total from all lines.\n\n### Country resolution\n\nWhen `country` is omitted and the stored country is empty, OmniCommerce may derive it from an unambiguous resulting order currency.\n\n### Restrictions and events\n\nMarketplace-owned orders from Shopee, Lazada, TikTok, and Shopify are rejected with `409 Conflict`. A status change emits `order.status.changed`; other changes emit `order.updated`.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "OmniCommerce order UUID returned from create or list.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "At least one of externalOrderId, externalOrderNumber, status, currency, country, totalAmount, shippingFee, discountAmount, metadata, orderCreatedAt, or items is required.", "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations." }, "externalOrderId": { "type": "string", "maxLength": 160, "description": "Replacement stable external order identifier. Must be unique among agentic orders in the organization." }, "externalOrderNumber": { "type": "string", "maxLength": 160, "description": "Replacement customer-facing external order number." }, "status": { "type": "string", "enum": [ "pending", "to_ship", "shipped", "completed", "return", "canceled" ], "description": "Canonical order status: pending, to_ship, shipped, completed, return, canceled." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 currency code for the order. When country is empty, unambiguous market currencies also derive country (see country field)." }, "country": { "type": "string", "maxLength": 80, "description": "Marketplace country (code or name). Optional. When omitted and the order's stored country is empty, Omni derives from the resulting order currency when unambiguous (SGD→singapore, MYR→malaysia, PHP→philippines, HKD→hong kong, etc.). Explicit country always wins. USD is not used to derive country." }, "totalAmount": { "type": "number", "minimum": 0, "description": "Order total. When omitted and line prices change, recomputed from line paid/unit prices × quantity." }, "shippingFee": { "type": "number", "minimum": 0 }, "discountAmount": { "type": "number", "minimum": 0 }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional shallow merge into existing order metadata (does not replace the full object)." }, "orderCreatedAt": { "type": "string", "format": "date-time", "description": "Replacement order created timestamp (ISO 8601 with timezone). Overwrites stored order_created_at used by listing and analytics date filters. Omitted value is left unchanged. Re-posting POST /api/v1/orders with the same externalOrderId does not overwrite an existing created date." }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Line upserts. Match by externalOrderItemId or productId to update. To replace a line identifier, select with currentExternalOrderItemId and provide the new externalOrderItemId. To append a multi-SKU line, send a new externalOrderItemId with productName and quantity.", "items": { "type": "object", "additionalProperties": false, "properties": { "currentExternalOrderItemId": { "type": "string", "maxLength": 160, "description": "Current line identifier used to select the line when replacing externalOrderItemId." }, "externalOrderItemId": { "type": "string", "maxLength": 160, "description": "Selects the line when currentExternalOrderItemId is omitted. When currentExternalOrderItemId is provided, this is the replacement identifier. If no line matches and productName + quantity are provided, inserts a new line." }, "productId": { "type": "string", "format": "uuid", "description": "Match a single line by product UUID when unique on the order." }, "productName": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required with quantity when inserting a new line." }, "sku": { "type": "string", "maxLength": 160 }, "sellerSku": { "type": "string", "maxLength": 160 }, "shopSku": { "type": "string", "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9999, "description": "Required with productName when inserting a new line." }, "price": { "type": "number", "minimum": 0, "description": "Alias for `unitPrice` (list / original unit price). Prefer `unitPrice` on new integrations." }, "unitPrice": { "type": "number", "minimum": 0, "description": "Per-unit list / original (sticker) price before line discounts. Same meaning as `price`." }, "paidPrice": { "type": "number", "minimum": 0, "description": "Per-unit amount actually charged after discounts. Preferred for totals and return refund estimates (paidPrice×quantity when set, else unitPrice/price×quantity). Not COGS." }, "costPrice": { "type": "number", "minimum": 0, "description": "Unit COGS. With productId (on the patch or existing line), upserts product_data.costPrice. Omitted costPrice never clears existing product or line cost. Distinct from price/unitPrice/paidPrice. Stored in the local/target currency after FX when costPriceCurrency is set." }, "costPriceCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO currency of the raw costPrice (e.g. USD) before conversion. Required when cost is not already in the order/line currency. Alias: costCurrency." }, "costCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Alias for costPriceCurrency." }, "costPriceFxRate": { "type": "number", "exclusiveMinimum": 0, "description": "Manual FX rate: units of costPriceFxTo per 1 unit of costPriceCurrency (USD→MYR at 4.45 means 1 USD = 4.45 MYR). Omit to auto-fetch the rate from Frankfurter (ECB daily rates)." }, "costPriceFxTo": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Target currency for the conversion. Defaults to the line currency, then the order currency, and must match that accounting currency when one is present." }, "costPriceFxAsOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "description": "Pins the auto-fetched rate to a date: YYYY-MM-DD, or YYYY-MM for the last calendar day of that month. Omit to use the latest rate." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "status": { "type": "string", "enum": [ "pending", "to_ship", "shipped", "completed", "return", "canceled" ] }, "imageUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "variation": { "type": "string", "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "examples": { "updateStatusAndLine": { "summary": "Status, money, and line price patch", "value": { "organizationId": "org_123", "externalOrderId": "MY-223347629SG", "externalOrderNumber": "MY-223347629SG", "status": "shipped", "currency": "SGD", "totalAmount": 120.5, "items": [ { "currentExternalOrderItemId": "dev-order-1", "externalOrderItemId": "10817558", "price": 110, "costPrice": 45, "currency": "SGD" } ], "metadata": { "trackingNumber": "SG123456789" } } }, "correctCreatedAt": { "summary": "Correct the order created timestamp", "value": { "organizationId": "org_123", "orderCreatedAt": "2026-03-15T08:00:00.000Z" } }, "appendMultiSkuLine": { "summary": "Append a multi-SKU line on an existing agentic order", "description": "New externalOrderItemId with productName + quantity inserts a line. Omit totalAmount so Omni recomputes from all lines.", "value": { "organizationId": "org_123", "items": [ { "externalOrderItemId": "ORD-9002", "productName": "Item B", "sku": "SKU-B", "sellerSku": "SKU-B", "quantity": 1, "paidPrice": 40, "currency": "SGD" } ] } } } } } }, "responses": { "200": { "description": "Order updated (or unchanged no-op).", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request — invalid status or payload" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `orders:write` scope" }, "404": { "description": "Order not found for this organization" }, "409": { "description": "Updates are not supported for marketplace-owned orders, or an external identifier is already in use" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/orders/{orderId}/action-options": { "get": { "operationId": "get_v1_orders_by_orderid_action_options", "summary": "Get Order Action Options", "description": "Ask the marketplace which choices an action needs, such as pickup or drop-off for `ship`. Requires `orders:write`.\n\nSend the chosen choice's `payload` with `POST /api/v1/orders/{orderId}/actions`.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ship", "cancel", "labels", "update_tracking" ] } } ], "responses": { "200": { "description": "Choices for the action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "ship", "cancel", "labels", "update_tracking" ] }, "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "payload": { "description": "Send this as the action `payload` to use the choice.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "requiresInput": { "description": "The choice needs extra fields, such as a tracking number.", "type": "boolean" } }, "required": [ "id", "label" ] } } }, "required": [ "action", "choices" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `orders:write` scope" }, "404": { "description": "Order not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/orders/{orderId}/actions": { "get": { "operationId": "get_v1_orders_by_orderid_actions", "summary": "List Order Actions", "description": "The order's 20 most recent action jobs, newest first, plus its latest successful label job. Requires `orders:read`.\n\nPoll this after queueing an action. A succeeded `labels` job lists its label files in `labels`.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Action jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "action": { "type": "string", "enum": [ "ship", "cancel", "labels", "update_tracking" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "not_supported" ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Download URL of the label file." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "name", "mimeType" ] }, "description": "Shipping label files. Filled when a `labels` job has succeeded." } }, "required": [ "id", "orderId", "action", "status", "errorMessage", "updatedAt", "completedAt", "labels" ] } } }, "required": [ "jobs" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `orders:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_orders_by_orderid_actions", "summary": "Queue Order Action", "description": "Ship, cancel, generate shipping labels for, or update tracking on a marketplace order. Requires `orders:write`.\n\nThe marketplace call runs in the background: the response is `202` with `jobId`; poll `GET /api/v1/orders/{orderId}/actions`. A repeated `idempotencyKey` returns `200` with the original job.", "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "description": "Required for session auth. API keys already belong to one organization.", "type": "string", "minLength": 1, "maxLength": 120 }, "action": { "type": "string", "enum": [ "ship", "cancel", "labels", "update_tracking" ], "description": "`ship` arranges shipment, `labels` generates shipping labels, `update_tracking` sends a tracking number, and `cancel` cancels the order." }, "payload": { "description": "Marketplace inputs for the action. Send the `payload` of the choice returned by `GET /api/v1/orders/{orderId}/action-options`, plus fields such as `trackingNumber` or `cancelReason` when a choice requires input.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "idempotencyKey": { "description": "Repeat a request with the same key to get the original job instead of a second marketplace call.", "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The idempotency key matched an existing job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobStatus": { "type": "string" }, "duplicate": { "type": "boolean" } }, "required": [ "jobId", "jobStatus", "duplicate" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "202": { "description": "The action job was queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobStatus": { "type": "string" }, "duplicate": { "type": "boolean" } }, "required": [ "jobId", "jobStatus", "duplicate" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `orders:write` scope" }, "404": { "description": "Order not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/organizations": { "post": { "operationId": "post_v1_organizations", "summary": "Create Organization", "description": "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.", "tags": [ "organizations" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Organization display name.", "minLength": 2, "maxLength": 80 }, "keepCurrentActiveOrganization": { "type": "boolean", "default": false, "description": "When true, Better Auth keeps the current active organization instead of switching active context." } } }, "example": { "name": "Acme Team" } } } }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "organizationId": { "type": "string" }, "redirectUrl": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } }, "required": [ "ok", "organizationId", "organization" ] } } } }, "400": { "description": "Bad Request - Invalid organization name or JSON" }, "401": { "description": "Unauthorized - Sign in is required" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/price-books": { "get": { "operationId": "get_v1_price_books", "summary": "List Price Book Rules", "description": "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`.", "tags": [ "price-books" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by marketplace platform: `shopee`, `lazada`, `tiktok`, `shopify`, `whatsapp`, `zalora`, `amazon`, or `ebay`.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, { "name": "enabledOnly", "in": "query", "required": false, "description": "When `true`, return only enabled rules.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Price book rules returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rules", "total" ], "properties": { "rules": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Bad Request (invalid platform filter)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `price_books:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_price_books", "summary": "Create Price Book Rule", "description": "Create a marketplace price book rule for a platform (optional store and country). Does not change Omni product prices. Requires `price_books:write`.\n\n`expression` is the buyer formula and replaces markup percent. `price` in that formula is the catalog price, not cost price. Without an expression, `marginValue` is the markup percent.", "tags": [ "price-books" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "platform", "marginValue" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth across multiple organizations. Optional for OAuth/API keys bound to one organization." }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "storeId": { "type": [ "string", "null" ], "maxLength": 200, "description": "Optional connected store ID. Null/omit applies to all stores for the platform." }, "country": { "type": [ "string", "null" ], "maxLength": 80, "description": "Optional country scope (name or code). Null/omit applies to all countries." }, "marginValue": { "type": "number", "minimum": 0, "maximum": 500, "description": "Markup percent applied to the catalog price. Ignored when `expression` is set." }, "expression": { "type": [ "string", "null" ], "maxLength": 500, "description": "Buyer formula. `price` is the catalog price. Supports arithmetic, percentages, CEILING, IF, and CURRENCY(rate, \"USD\"). Replaces markup percent." }, "rounding": { "type": "string", "enum": [ "none", "currency_minor", "nearest_0_05", "nearest_1" ], "description": "Defaults to `currency_minor` when omitted." }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3, "description": "Optional ISO 4217 currency for `currency_minor` rounding." }, "enabled": { "type": "boolean", "default": true, "description": "Whether the rule is active. Defaults to true." } } }, "example": { "platform": "shopee", "marginValue": 10, "country": "singapore", "rounding": "currency_minor", "currency": "SGD", "enabled": true } } } }, "responses": { "201": { "description": "Price book rule created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rule" ], "properties": { "rule": { "type": "object" } } } } } }, "400": { "description": "Bad Request (invalid payload, markup range, or duplicate platform/store/country scope)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `price_books:write` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/price-books/{ruleId}": { "get": { "operationId": "get_v1_price_books_by_ruleid", "summary": "Get Price Book Rule", "description": "Fetch one marketplace price book rule by ID. Requires `price_books:read`.", "tags": [ "price-books" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Price book rule returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rule" ], "properties": { "rule": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `price_books:read` scope" }, "404": { "description": "Price book rule not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "operationId": "patch_v1_price_books_by_ruleid", "summary": "Update Price Book Rule", "description": "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`.", "tags": [ "price-books" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "storeId": { "type": [ "string", "null" ], "maxLength": 200 }, "country": { "type": [ "string", "null" ], "maxLength": 80 }, "marginValue": { "type": "number", "minimum": 0, "maximum": 500 }, "rounding": { "type": "string", "enum": [ "none", "currency_minor", "nearest_0_05", "nearest_1" ] }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "expression": { "type": [ "string", "null" ], "maxLength": 500, "description": "Buyer formula. `price` is the catalog price. Null clears the formula and markup percent applies again." }, "enabled": { "type": "boolean" } } }, "example": { "marginValue": 12.5, "enabled": true } } } }, "responses": { "200": { "description": "Price book rule updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rule" ], "properties": { "rule": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `price_books:write` scope" }, "404": { "description": "Price book rule not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "operationId": "delete_v1_price_books_by_ruleid", "summary": "Delete Price Book Rule", "description": "Delete a marketplace price book rule by ID. Requires `price_books:write`.", "tags": [ "price-books" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Price book rule deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `price_books:write` scope" }, "404": { "description": "Price book rule not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/price-books/preview": { "post": { "operationId": "post_v1_price_books_preview", "summary": "Preview Channel List Price", "description": "Compute channel list price from a canonical list price using matching enabled rules (or a forced ruleId). Requires `price_books:read`.", "tags": [ "price-books" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "platform", "listPrice" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth across multiple organizations. Optional for OAuth/API keys bound to one organization." }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "listPrice": { "type": "number", "description": "Canonical list price to mark up." }, "storeId": { "type": [ "string", "null" ], "maxLength": 200 }, "country": { "type": [ "string", "null" ], "maxLength": 80 }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "ruleId": { "type": "string", "format": "uuid", "description": "Optional force a specific rule instead of specificity matching." } } }, "example": { "platform": "shopee", "listPrice": 100, "country": "singapore", "currency": "SGD" } } } }, "responses": { "200": { "description": "Preview computed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "listPrice", "channelListPrice", "applied", "source" ], "properties": { "listPrice": { "type": "number" }, "channelListPrice": { "type": "number" }, "applied": { "type": "boolean" }, "source": { "type": "string", "enum": [ "price_book", "canonical" ] }, "markupPercent": { "type": "number" }, "currency": { "type": "string", "description": "Listed currency when known. A buyer formula with CURRENCY sets it." }, "belowCatalogPrice": { "type": "boolean", "description": "Present and true when the buyer formula lists below the catalog price in the same currency. This is usually a payout formula, price * (1 - fees), used where the gross-up, price / (1 - fees), was meant." }, "formulaError": { "type": "string", "description": "Set when the matched buyer formula cannot price this list price. Publish fails for that listing instead of using the catalog price." }, "rule": { "type": [ "object", "null" ] }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request, or the forced `ruleId` has a buyer formula that cannot price this list price" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `price_books:read` scope" }, "404": { "description": "Price book rule not found (when ruleId is set)" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products": { "get": { "operationId": "get_v1_products", "summary": "List Products", "description": "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`.\n\n### Stock and variants\n\nRows are in `items`. Read catalog stock from `items[].stockQuantity`: parent rows already aggregate their non-deleted variants, and virtual bundles use component availability with any manual cap. Null means unknown, not zero. A row with `variantCount` above 0 has variants; fetch them from `GET /api/v1/products/{productId}`. List rows do not contain `inventoryQuantity`, `inventory.quantity`, or an embedded `variants` array.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by one catalog view status. Lifecycle values include draft, active, archived and deleted; derived views include flagged, errors, qc_pending and qc_rejected. A product may have a lifecycle value and multiple derived signals simultaneously.", "schema": { "type": "string" } }, { "name": "marketplace", "in": "query", "required": false, "description": "Filter by enabled marketplace.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] } }, { "name": "country", "in": "query", "required": false, "description": "Filter by marketplace country (e.g., Singapore, Malaysia).", "schema": { "type": "string", "maxLength": 80 } }, { "name": "q", "in": "query", "required": false, "description": "Search query for product name or SKU.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "sku", "in": "query", "required": false, "description": "Exact catalog SKU match after trim. Not fuzzy and not substring. Repeat the parameter or comma-separate up to 50 SKUs. Combined with other filters using AND.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "minPrice", "in": "query", "required": false, "description": "Minimum price filter.", "schema": { "type": "number", "minimum": 0 } }, { "name": "maxPrice", "in": "query", "required": false, "description": "Maximum price filter.", "schema": { "type": "number", "minimum": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort order for results.", "schema": { "type": "string", "enum": [ "updatedAt", "createdAt", "name", "price" ], "default": "updatedAt" } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit per page. Values above the cap are clamped silently; the applied value is returned in `pagination.limit`. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset. Use `pagination.nextOffset` from the previous response to page forward. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "sku", "parentId", "isVariant", "stockQuantity", "variantCount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ], "format": "uuid" }, "isVariant": { "type": "boolean" }, "stockQuantity": { "type": [ "integer", "null" ], "minimum": 0, "description": "Catalog stock in whole units, matching the Products page. Parent rows aggregate non-deleted variants in the same organization; virtual bundles derive stock from components and any manual cap. Null means unknown: never substitute zero for missing or null stock. This is not a sum of marketplace inventory mirrors or a per-location available-to-promise balance." }, "variantCount": { "type": "integer", "minimum": 0, "description": "Number of non-deleted variants; greater than 0 means the product has variants. A parent row's stockQuantity already includes their stock. Read the variants themselves from `GET /api/v1/products/{productId}`." }, "status": { "type": "string" }, "statusFacets": { "type": "object", "description": "Read-only product-wide state. Lifecycle status and derived quality/error signals are independent; this field is recalculated from current product, marketplace QC, and review flags.", "required": [ "lifecycle", "derived" ], "properties": { "lifecycle": { "type": "string", "enum": [ "draft", "active", "archived", "deleted", "unknown" ] }, "derived": { "type": "array", "items": { "type": "string", "enum": [ "flagged", "errors", "qc_pending", "qc_rejected" ] } }, "zaloraQualityControl": { "type": "object" } } } } } }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer" }, "summary": { "type": "object", "properties": { "totalCount": { "type": "integer", "description": "All-tab count under the other filters, before applying the selected status. Use pagination.total for the matching result count." }, "statusCounts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Counts by product status under the other selected filters." } } }, "pagination": { "type": "object", "description": "Echoes the offset/limit actually applied to the query (after clamping) plus discovery metadata for paging.", "properties": { "offset": { "type": "integer", "description": "Offset that was applied to this page." }, "limit": { "type": "integer", "description": "Limit that was applied to this page (after clamping to `maxLimit`)." }, "total": { "type": "integer", "description": "Total number of records matching the filters, ignoring offset/limit." }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ], "description": "Null when `hasMore` is false." }, "maxLimit": { "type": "integer", "description": "Server-side maximum for the `limit` query parameter." }, "defaultLimit": { "type": "integer", "description": "Default `limit` applied when none is provided." } }, "required": [ "offset", "limit", "total", "hasMore", "nextOffset", "maxLimit", "defaultLimit" ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_products", "summary": "Create Product", "description": "Queue a single-product create workflow for the authenticated organization. Product enrichment is disabled by default; set `workflow.enrich` to `true` to enable it.\n\n### Request behavior\n\n- `product` contains developer-supplied fields. Unknown fields are preserved as enrichment context.\n- SKU is the unique product upsert identifier.\n- Externally hosted HTTP(S) images are copied to managed R2 storage.\n- `targetMarketplaces` and `targetCountries` are optional; enrichment can run without publishing targets.\n\n### Asynchronous result\n\nThe API returns a job ID. Poll `GET /api/v1/jobs/{jobId}` for completion. Product creation, image ingestion, enrichment, and taxonomy assignment run in the same product workflow job. ACO generation runs separately when enabled; poll `result.geoJobId` for its completion.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "type": "object", "description": "Single product payload. `sku` and `title` are required for create/upsert. Known fields are normalized; arbitrary extra fields are preserved and passed to enrichment.", "required": [ "sku", "title" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Optional external/source product ID." }, "sku": { "type": "string", "description": "Unique SKU used as the product upsert identifier.", "maxLength": 200 }, "title": { "type": "string", "maxLength": 400 }, "name": { "type": "string", "description": "Alias accepted for `title`.", "maxLength": 400 }, "brand": { "type": "string", "maxLength": 160 }, "description": { "type": "string", "description": "Original product description or source evidence for enrichment." }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Product selling price." }, "costPrice": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Unit cost basis for COGS. Persisted as top-level `product_data.costPrice`." }, "inventory": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" }, { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 0 } } } ], "description": "Inventory quantity. Objects with `quantity` are accepted." }, "weight": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Product weight in grams. No `weightUnit` field is required." }, "dimensions": { "oneOf": [ { "type": "object", "properties": { "length": { "type": "number", "minimum": 0 }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 } } }, { "type": "string" } ], "description": "Product dimensions. Strings such as `Length 17cm x Height 11cm x Width 9cm` are parsed when possible." }, "images": { "type": "array", "items": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://" }, "description": "Array of HTTP(S) image URL strings only. Image objects and delimited strings are not accepted. Each entry is a complete URL, including commas in paths or query strings. Images follow array order. Images are mirrored to R2 before storage. At least one URL is required unless automatic image sourcing is enabled; data URI/base64 images are not supported." }, "category": { "type": "string" }, "categoryName": { "type": "string" }, "category_name": { "type": "string" }, "product_type": { "type": "string", "description": "Alias/source hint used for category name when present." }, "marketplaces": { "type": "object", "additionalProperties": true, "description": "Select connected stores with `product.marketplaces..storeId`. This request supports one store and country per marketplace.\n\nGet store IDs from `GET /api/v1/marketplaces/connected` ([List Connected Marketplaces](/api-reference/developer-platform/list-connected-marketplaces)). Copy `storeId` from the matching entry in `connectedMarketplaces`; use a store connected to the authenticated organization.\n\nUse an ISO 3166-1 alpha-2 country code, such as `sg` or `my`. For a Zalora Global Seller Center store, set `product.marketplaces.zalora.country` to `global`. Provided values are trimmed and normalized to lowercase. Country names such as `Singapore` and custom values are rejected with HTTP 400. When country is omitted, ingestion resolves it from the selected connected store.\n\nWhen top-level `targetMarketplaces` and `targetCountries` are omitted, targets are inferred from these entries. A marketplace's `country` takes precedence over the first top-level target country for its saved assignment.\n\nTo enrich and assign categories, brands, and attributes without human approval, set both `workflow.enrich` and `workflow.autoAssignMarketplaceTaxonomy` to `true`; both default to `false`. This saves the product in Omni; publishing is a separate action.\n\nExample value for `product.marketplaces`:\n\n```json\n{\n \"shopee\": {\n \"enabled\": true,\n \"country\": \"sg\",\n \"storeId\": \"YOUR_SHOPEE_STORE_ID\"\n },\n \"lazada\": {\n \"enabled\": true,\n \"country\": \"sg\",\n \"storeId\": \"YOUR_LAZADA_STORE_ID\"\n }\n}\n```", "properties": { "shopee": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "lazada": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "tiktok": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "shopify": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "zalora": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ZaloraProductCountry" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "amazon": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "ebay": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } } } } } }, "variants": { "type": "array", "description": "Optional variant rows to create under the root product. Arbitrary variant fields are accepted; `variationAttributes` or `attributes` are normalized when present.", "items": { "type": "object", "additionalProperties": true, "properties": { "sku": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "inventory": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "variationAttributes": { "type": "object", "additionalProperties": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true } } } }, "variationSchema": { "type": "object", "description": "Optional variation schema, e.g. `{ \"color\": [\"BLUE\", \"BLACK\"] }`.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "targetMarketplaces": { "type": "array", "description": "Optional marketplace targets. Product creation/enrichment works when omitted.", "items": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] } }, "targetCountries": { "type": "array", "description": "Optional country codes for marketplace and ACO workflows. Uses the same country enum as product.marketplaces..country. Codes are normalized to lowercase; country names and custom values are rejected.", "items": { "$ref": "#/components/schemas/ProductCountryCode" } }, "model": { "type": "string", "description": "Optional enrichment model override." }, "additionalInstructions": { "type": "string", "maxLength": 4000, "description": "Optional instructions applied to LLM enrichment and image handling. For example, exclude images tagged as size charts, maps, or cluttered supplier feed shots." }, "workflow": { "type": "object", "description": "Optional workflow switches.", "properties": { "enrich": { "type": "boolean", "default": false, "description": "Enable AI product enrichment. Defaults to false when omitted, including when the workflow object is omitted." }, "aco": { "type": "boolean", "default": false, "description": "Defaults to false. Set true to queue a separate ACO generation job after the product is written. Otherwise generate a profile explicitly. Poll `result.geoJobId` when a job is queued." }, "publish": { "type": "boolean", "default": false }, "syncBack": { "type": "boolean", "default": false, "description": "Reserved for future source-store sync-back. Accepted for forward compatibility, but currently does not trigger a source update." }, "sourceImagesAutomatically": { "type": "boolean", "default": false, "description": "When true, permits products without submitted image URLs and lets enrichment use the Source Product Images tool to find official brand-site gallery photos. Requires `workflow.enrich: true` to source images." }, "enableRichDescription": { "type": "boolean", "default": false, "description": "When true, asks enrichment to produce slot-based Rich Content Descriptions (Markdown With Images). Description image URLs are converted to slot:// placeholders and must be distinct from product gallery image URLs." }, "skipBackgroundRemoval": { "type": "boolean", "default": false, "description": "When true, skips automatic background removal during image ingestion." }, "enableMannequinRemoval": { "type": "boolean", "default": false, "description": "When true, queues separate ghost mannequin removal jobs for eligible product images after ingestion. Their IDs are returned in `result.imageProcessing.ghostMannequinQueuedJobIds`." }, "autoAssignMarketplaceTaxonomy": { "type": "boolean", "default": false, "description": "Defaults to false. Set to true together with `workflow.enrich: true` and marketplace/country targets to automatically resolve and save marketplace categories, brands, and attributes without human approval. Existing assigned taxonomy is preserved. Low-confidence matches and missing required attributes are reported in the job result warnings; publishing remains a separate step." }, "excludedImageTags": { "oneOf": [ { "type": "string" }, { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 120 } } ], "description": "Optional comma-separated string or string array of normalized image tags to exclude from the saved product gallery after image tagging." }, "customImageTags": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "name", "description" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 120, "description": "Seller-defined tag name. Normalized to snake_case before tagging." }, "description": { "type": "string", "maxLength": 280, "description": "Natural-language instruction describing what the vision model should look for before adding this tag." } } }, "description": "Seller-defined image tags evaluated by the same image tagging step as built-in tags. Use `excludedImageTags` separately when matching tagged images should be removed from the saved gallery." } } } } }, "example": { "product": { "id": "cml55mqcq06vwo20ialgr54ry", "sku": "TZVBGTB82269", "sku_tpp": "TZVBGTB82269", "sku_ori": "63074830", "title": "Navy Blue Leather Tote and Crossbody Bag", "brand": "ZADIG & VOLTAIRE", "status": "ACTIVE", "price": "600", "compare_at_price": "720", "cost_per_item": "425.4", "description": "Gender: Women Brand: ZADIG & VOLTAIRE Product Name: Zadig & Voltaire Navy Blue Leather Tote and Crossbody Bag Condition: A Color: navy blue Material: lamb leather Origin: Tunisia Includes: dust bag", "images": [ "https://api.example.com/images/1.jpg", "https://api.example.com/images/2.jpg" ], "category": "BAGS", "category_name": "SHOULDER BAGS", "color": "BLUE", "condition": "GOOD", "gender": "WOMEN", "material": "LEATHER", "inventory": "1", "dimensions": "Length 17cm x Height 11cm x Width 9cm", "weight": 450, "product_type": "SHOULDER BAGS", "marketplaces": { "shopee": { "enabled": true, "country": "sg", "storeId": "YOUR_SHOPEE_STORE_ID" }, "lazada": { "enabled": true, "country": "sg", "storeId": "YOUR_LAZADA_STORE_ID" } } }, "variants": [ { "sku": "TZVBGTB82269-BLUE", "price": "600", "variationAttributes": { "color": "BLUE" } } ], "additionalInstructions": "Exclude images that are size charts, maps, or cluttered supplier feed shots.", "targetMarketplaces": [ "shopee", "lazada" ], "targetCountries": [ "sg" ], "workflow": { "enrich": false, "aco": false, "sourceImagesAutomatically": false, "enableRichDescription": false, "skipBackgroundRemoval": false, "enableMannequinRemoval": true, "autoAssignMarketplaceTaxonomy": false, "customImageTags": [ { "name": "model_holding_bag", "description": "person is holding or wearing the bag" } ], "excludedImageTags": [ "phone", "logo", "size_reference" ] } } } } }, "responses": { "202": { "description": "Product create/enrich workflow accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string" }, "jobId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "normalizedInput": { "type": "object" }, "issues": { "type": "array", "items": { "type": "object" } }, "targetMarketplaces": { "type": "array", "items": { "type": "string" } }, "targetCountries": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad Request - Invalid product data" }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}": { "get": { "operationId": "get_v1_products_by_productid", "summary": "Get Product", "description": "Retrieve a single product by ID for the authenticated organization.\n\nAuthenticate with an API key using Bearer token authentication.\n\nWhen available, the response includes generated Agentic Commerce Optimization (ACO) data:\n\n- Profile metadata and FAQs\n- Localization content and cultural notes\n- Intent queries and signals\n- Sources and claims\n\nA parent product returns its variants in `variants`, with each variant's option values, price, stock, image, and marketplace listings.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "brand": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "status": { "type": "string" }, "statusFacets": { "type": "object", "description": "Read-only product-wide state. Lifecycle status and derived quality/error signals are independent; this field is recalculated from current product, marketplace QC, and review flags.", "required": [ "lifecycle", "derived" ], "properties": { "lifecycle": { "type": "string", "enum": [ "draft", "active", "archived", "deleted", "unknown" ] }, "derived": { "type": "array", "items": { "type": "string", "enum": [ "flagged", "errors", "qc_pending", "qc_rejected" ] } }, "zaloraQualityControl": { "type": "object" } } }, "images": { "type": "array", "items": { "type": "object" } }, "excludedImages": { "type": "array", "description": "Import image exclusions, with original source URLs, classification tags, matching filters, and reasons. Empty when no exclusion audit was saved.", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "sourceUrl": { "type": "string", "format": "uri" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "imageTagId": { "type": "string" }, "imageTags": { "type": "array", "items": { "type": "string" } }, "matchedExcludedTags": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string", "enum": [ "excluded_tag", "size_chart", "gallery_limit", "non_product_asset", "mirror_unavailable" ] } }, "required": [ "url", "sourceUrl", "position", "imageTags", "matchedExcludedTags", "reason" ], "additionalProperties": false } }, "highlights": { "type": [ "array", "null" ], "items": { "type": "string" } }, "marketplaces": { "type": "object" }, "inventory": { "type": "object" }, "weight": { "type": [ "number", "null" ] }, "dimensions": { "type": [ "object", "null" ] }, "seoTitle": { "type": [ "string", "null" ] }, "seoDescription": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "bundle": { "type": [ "object", "null" ] }, "acoProfile": { "type": [ "object", "null" ], "description": "Current ACO/GEO profile metadata for the product. Null when no profile has been generated.", "properties": { "profileId": { "type": "string" }, "productId": { "type": "string" }, "readinessScore": { "type": [ "number", "null" ] }, "intentSummary": { "type": "string" }, "generatedAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp" }, "updatedAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp" }, "platformScope": { "type": "array", "items": { "type": "string" } }, "countryScope": { "type": "array", "description": "Country hints associated with the current ACO profile.", "items": { "type": "string" } }, "generationVersion": { "type": [ "string", "null" ] }, "scoringVersion": { "type": [ "string", "null" ] }, "localizationVersion": { "type": [ "string", "null" ] }, "promptVersion": { "type": [ "string", "null" ] }, "ontologyVersion": { "type": [ "string", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "seasonalRelevance": { "type": "object" }, "compliance": { "type": "object" }, "trust": { "type": "object" }, "categoryAttributes": { "type": "object" } } }, "acoFaqs": { "type": "array", "description": "Generated Agentic Commerce Optimization FAQs for the product, ordered by language then rank. Empty array when no ACO profile has been generated yet.", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code (en, th, id, ms, vi, tl)." }, "intentKey": { "type": [ "string", "null" ], "description": "Intent ontology key (e.g., capable_of, suitable_for_context, used_for_audience, compliance_flag)." }, "rank": { "type": [ "integer", "null" ], "description": "Rank within the language group. Lower is more prominent." }, "confidence": { "type": [ "number", "null" ], "description": "Generator confidence, 0..1." }, "evidenceKeys": { "type": "array", "items": { "type": "string" } }, "citationUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "question", "answer" ] } }, "acoLocalizations": { "type": "array", "description": "Localized ACO content by language, including intent descriptions, generated buyer intent queries, and cultural notes.", "items": { "type": "object", "properties": { "profileId": { "type": "string" }, "language": { "type": "string" }, "intentDescription": { "type": "string" }, "intentQueries": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "description": "Country hints this localization and cultural note applies to.", "items": { "type": "string" } }, "culturalNotes": { "type": "object" } }, "required": [ "language", "intentDescription" ] } }, "acoSignals": { "type": "array", "description": "Normalized ACO retrieval and ranking signals extracted from the product profile.", "items": { "type": "object", "properties": { "profileId": { "type": "string" }, "key": { "type": "string" }, "display": { "type": "string" }, "normalized": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "attributeClass": { "type": [ "string", "null" ] } } } }, "acoIntentQueries": { "type": "array", "description": "Deduplicated buyer intent queries aggregated from all ACO localizations.", "items": { "type": "string" } }, "acoCulturalNotes": { "type": "object", "description": "Cultural notes keyed by `language:country` (example: `en:sg`). Uses `global` when no country scope is known.", "additionalProperties": { "type": "object", "properties": { "language": { "type": "string" }, "country": { "type": "string" }, "notes": { "type": "object" } }, "required": [ "language", "country", "notes" ] } }, "acoSources": { "type": "array", "description": "Citation/source records used by ACO trust enrichment.", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object" }, "createdAt": { "type": [ "string", "null" ] } } } }, "acoClaims": { "type": "array", "description": "Trust claims and citation URLs associated with the generated ACO profile.", "items": { "type": "object", "properties": { "fieldPath": { "type": "string" }, "text": { "type": "string" }, "isFactual": { "type": "boolean" }, "status": { "type": [ "string", "null" ] }, "citationUrls": { "type": "array", "items": { "type": "string" } } } } }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp" }, "variants": { "type": "array", "description": "The product's non-deleted variants, oldest first, in the same row shape as `GET /api/v1/products` items. Empty for a simple product and when the requested product is itself a variant.", "items": { "allOf": [ { "type": "object", "required": [ "id", "name", "sku", "parentId", "isVariant", "stockQuantity", "variantCount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ], "format": "uuid" }, "isVariant": { "type": "boolean" }, "stockQuantity": { "type": [ "integer", "null" ], "minimum": 0, "description": "Catalog stock in whole units, matching the Products page. Parent rows aggregate non-deleted variants in the same organization; virtual bundles derive stock from components and any manual cap. Null means unknown: never substitute zero for missing or null stock. This is not a sum of marketplace inventory mirrors or a per-location available-to-promise balance." }, "variantCount": { "type": "integer", "minimum": 0, "description": "Number of non-deleted variants; greater than 0 means the product has variants. A parent row's stockQuantity already includes their stock. Read the variants themselves from `GET /api/v1/products/{productId}`." }, "status": { "type": "string" }, "statusFacets": { "type": "object", "description": "Read-only product-wide state. Lifecycle status and derived quality/error signals are independent; this field is recalculated from current product, marketplace QC, and review flags.", "required": [ "lifecycle", "derived" ], "properties": { "lifecycle": { "type": "string", "enum": [ "draft", "active", "archived", "deleted", "unknown" ] }, "derived": { "type": "array", "items": { "type": "string", "enum": [ "flagged", "errors", "qc_pending", "qc_rejected" ] } }, "zaloraQualityControl": { "type": "object" } } } } }, { "type": "object", "properties": { "variationAttributes": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Option values that identify the variant, for example `{ \"Color\": \"Navy\", \"Size\": \"M\" }`." }, "price": { "type": [ "number", "null" ], "minimum": 0 }, "salePrice": { "type": [ "number", "null" ], "minimum": 0 }, "priceLabel": { "type": "string", "description": "Price formatted with the product currency." }, "imageUrl": { "type": [ "string", "null" ], "description": "The variant's own image, falling back to the parent product image." }, "imageUrls": { "type": "array", "items": { "type": "string" } }, "marketplaces": { "type": "array", "description": "The variant's listing on each connected marketplace.", "items": { "type": "object", "properties": { "marketplace": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "storeId": { "type": [ "string", "null" ] }, "storeLabel": { "type": [ "string", "null" ] }, "published": { "type": "boolean" }, "itemId": { "type": [ "string", "null" ] }, "listingUrl": { "type": [ "string", "null" ] } } } } } } ] } } }, "required": [ "variants" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "404": { "description": "Product not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "operationId": "patch_v1_products_by_productid", "summary": "Update Product", "description": "Update an existing product by ID. Only provided fields will be updated. Supports API key Bearer token authentication.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial product object. Only provided fields will be updated.", "properties": { "name": { "type": "string", "maxLength": 400 }, "description": { "type": "string" }, "sku": { "type": "string", "maxLength": 200 }, "brand": { "type": "string", "maxLength": 160 }, "price": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "maxLength": 3 }, "weight": { "type": "number", "minimum": 0 }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } } }, "inventory": { "type": "object", "properties": { "quantity": { "type": "integer" }, "lowStockThreshold": { "type": "integer" } } }, "images": { "type": "array", "items": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://" }, "description": "Array of HTTP(S) image URL strings only. Image objects and delimited strings are not accepted. Each entry is a complete URL, including commas in paths or query strings. Images follow array order." }, "highlights": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "marketplaces": { "type": "object", "additionalProperties": true, "properties": { "shopee": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "lazada": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "tiktok": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "shopify": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "zalora": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ZaloraProductCountry" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "amazon": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } }, "ebay": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean", "description": "Enable this marketplace on the product. On create, when top-level targetMarketplaces is omitted, entries with enabled set to true or omitted become targets." }, "country": { "$ref": "#/components/schemas/ProductCountryCode" }, "storeId": { "type": "string", "maxLength": 255, "description": "Connected store ID. Copy connectedMarketplaces[].storeId from GET /api/v1/marketplaces/connected for this marketplace and country." } } } } }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] } } }, "example": { "price": 69.99, "inventory": { "quantity": 150 }, "highlights": [ "Active noise cancellation", "30-hour battery", "IPX5 water resistant" ] } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "productId": { "type": "string" }, "product": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid update data" }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "404": { "description": "Product not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "operationId": "delete_v1_products_by_productid", "summary": "Delete Product", "description": "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.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "productId": { "type": "string" }, "action": { "type": "string", "enum": [ "deleted", "permanently_deleted" ], "description": "Whether the product was soft-deleted or permanently removed." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "404": { "description": "Product not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/cost": { "patch": { "operationId": "patch_v1_products_by_productid_cost", "summary": "Update Product Cost", "description": "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.\n\nRequires `catalog:write`. When `costPriceCurrency` differs from the product selling currency and `costPriceFxRate` is omitted, Omni stores an FX quote on the product.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "OmniCommerce simple-product or variant UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "costPrice" ], "properties": { "costPrice": { "type": [ "number", "null" ], "minimum": 0 }, "costPriceCurrency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "costPriceFxRate": { "type": "number", "exclusiveMinimum": 0 }, "costPriceFxTo": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "costPriceFxAsOf": { "type": "string" } } }, "example": { "costPrice": 578, "costPriceCurrency": "USD" } } } }, "responses": { "200": { "description": "Catalog cost updated." }, "400": { "description": "Invalid cost payload." }, "401": { "description": "Unauthorized" }, "403": { "description": "Credential lacks catalog:write or organization is inactive." }, "404": { "description": "Product or variant not found." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/delist": { "post": { "operationId": "post_v1_products_by_productid_delist", "summary": "Delist Product", "description": "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 listing. This does not delete the OmniCommerce product.\n\nPoll GET /api/v1/jobs/{jobId} until data.status is succeeded, partial, or failed. Accepted means the job was queued, not that the marketplace has removed the listing.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "OmniCommerce product or variant ID. A variant delists its parent listing.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations." }, "marketplaces": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Which marketplaces to delist from. One or more of shopee, lazada, tiktok, shopify, whatsapp, zalora, amazon, ebay. Omit to delist every existing listing.", "items": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } } } }, "example": { "marketplaces": [ "shopee", "lazada" ] } } } }, "responses": { "202": { "description": "Delist job queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted" ] }, "productId": { "type": "string" }, "jobId": { "type": "string", "description": "Pollable delist job. Read it with GET /api/v1/jobs/{jobId}." }, "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "delistBatchId": { "type": "string" }, "marketplaces": { "type": "array", "items": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, "sourceProductId": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request - invalid payload, or the product has no listing on a requested marketplace" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Product Not Found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/images": { "post": { "operationId": "post_v1_products_by_productid_images", "summary": "Upload Product Image", "description": "Upload one image to a product's or variant's gallery as multipart/form-data. Requires `catalog:write`.\n\nJPEG, PNG, WebP, AVIF, or HEIC up to 8 MB; WebP, AVIF, and HEIC are stored as JPEG. The image is added at `position`, or at the end. Publish the product to send the new gallery to marketplaces.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The image file." }, "organizationId": { "type": "string", "description": "Required for session auth. API keys already belong to one organization." }, "position": { "description": "Zero-based place in the gallery; 0 makes it the main image. Defaults to the end.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "responses": { "201": { "description": "The image was added to the gallery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "image": { "type": "object", "properties": { "url": { "type": "string", "description": "Public URL of the stored image." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url", "position" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url", "position" ] }, "description": "The product's gallery after the upload, in order." } }, "required": [ "image", "images" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `catalog:write` scope" }, "404": { "description": "Product not found" }, "413": { "description": "The request body is not multipart or is too large" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/inventory": { "patch": { "operationId": "patch_v1_products_by_productid_inventory", "summary": "Update Product Inventory", "description": "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.\n\n### Authorization\n\nRequires an API credential with `catalog:write`. OmniCommerce derives `organizationId` from that credential; the request body cannot select or override an organization. ERP-managed and multi-source inventory keeps its existing ownership protections.\n\n### Marketplace sync\n\nThe update is Omni-only by default. Set `syncToMarketplaces` to `true` to create one durable inventory outbox job per marketplace account. Omit `targets` to sync every enabled, published account for the product, or provide exact `{ platform, accountId }` targets. Every explicit target is validated before inventory changes. The response contains each job ID and immediate target status; use `GET /api/v1/jobs/{jobId}` for progress.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "OmniCommerce simple-product or variant UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 0, "description": "New canonical on-hand quantity." }, "syncToMarketplaces": { "type": "boolean", "default": false, "description": "Queue durable sync jobs after the Omni inventory update." }, "targets": { "type": "array", "minItems": 1, "maxItems": 25, "description": "Exact enabled and published marketplace accounts. Requires syncToMarketplaces=true.", "items": { "type": "object", "additionalProperties": false, "required": [ "platform", "accountId" ], "properties": { "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "maxLength": 255 } } } } } }, "example": { "quantity": 125, "syncToMarketplaces": true, "targets": [ { "platform": "shopee", "accountId": "shop-456" }, { "platform": "lazada", "accountId": "seller-123" } ] } } } }, "responses": { "200": { "description": "Inventory updated; no marketplace job was queued.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "ok", "operationId", "status", "productId", "warnings", "recommendations", "links", "data" ], "properties": { "apiVersion": { "type": "string", "enum": [ "developer_v1" ] }, "ok": { "type": "boolean", "enum": [ true ] }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "accepted" ] }, "productId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "additionalProperties": false, "required": [ "changed", "quantity", "inventoryVersion", "syncToMarketplaces", "jobIds", "targets", "emittedEvents" ], "properties": { "changed": { "type": "boolean" }, "quantity": { "type": "integer", "minimum": 0 }, "inventoryVersion": { "type": [ "integer", "null" ], "minimum": 0 }, "syncToMarketplaces": { "type": "boolean" }, "jobIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "platform", "accountId", "status", "jobId" ], "properties": { "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "description": "Exact marketplace store, shop, or seller account ID." }, "status": { "type": "string", "enum": [ "queued" ] }, "jobId": { "type": "string", "format": "uuid" }, "targetId": { "type": "string", "description": "Target correlation within a price-sync batch." } } } }, "emittedEvents": { "type": "array", "items": { "type": "string", "enum": [ "product.inventory.changed" ] } } } } } } } } }, "202": { "description": "Inventory updated and marketplace sync jobs queued.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "ok", "operationId", "status", "productId", "warnings", "recommendations", "links", "data" ], "properties": { "apiVersion": { "type": "string", "enum": [ "developer_v1" ] }, "ok": { "type": "boolean", "enum": [ true ] }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "accepted" ] }, "productId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "additionalProperties": false, "required": [ "changed", "quantity", "inventoryVersion", "syncToMarketplaces", "jobIds", "targets", "emittedEvents" ], "properties": { "changed": { "type": "boolean" }, "quantity": { "type": "integer", "minimum": 0 }, "inventoryVersion": { "type": [ "integer", "null" ], "minimum": 0 }, "syncToMarketplaces": { "type": "boolean" }, "jobIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "platform", "accountId", "status", "jobId" ], "properties": { "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "description": "Exact marketplace store, shop, or seller account ID." }, "status": { "type": "string", "enum": [ "queued" ] }, "jobId": { "type": "string", "format": "uuid" }, "targetId": { "type": "string", "description": "Target correlation within a price-sync batch." } } } }, "emittedEvents": { "type": "array", "items": { "type": "string", "enum": [ "product.inventory.changed" ] } } } } } } } } }, "400": { "description": "Invalid quantity, variant selection, inventory ownership, or marketplace target." }, "401": { "description": "Unauthorized" }, "403": { "description": "Credential lacks catalog:write or organization is inactive." }, "404": { "description": "Product or variant not found." }, "409": { "description": "Inventory source is managed externally." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/listings": { "get": { "operationId": "get_v1_products_by_productid_listings", "summary": "Get Product Listings", "description": "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`.\n\nPoll after `POST /api/v1/products/{productId}/publish`.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "The product's listings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "productId": { "type": "string" }, "listings": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string" }, "marketplaceLabel": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "storeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "storeLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "type": "boolean", "description": "The marketplace has a live listing for the product." }, "unlisted": { "type": "boolean", "description": "The listing was delisted; its marketplace identity is kept." }, "itemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Marketplace item id." }, "listingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Buyer-facing listing URL while published." }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestPublish": { "anyOf": [ { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "success", "error" ] }, "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`created` or `updated` once the job has run." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorDetail": { "description": "The marketplace's rejection details, when it returned any." }, "updatedAt": { "type": "string" } }, "required": [ "jobId", "status", "action", "message", "error", "updatedAt" ] }, { "type": "null" } ], "description": "The most recent publish to this marketplace, including one still running." } }, "required": [ "marketplace", "marketplaceLabel", "country", "storeId", "storeLabel", "published", "unlisted", "itemId", "listingUrl", "publishedAt", "latestPublish" ] } } }, "required": [ "productId", "listings" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `catalog:read` scope" }, "404": { "description": "Product not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/price": { "patch": { "operationId": "patch_v1_products_by_productid_price", "summary": "Update Product Price", "description": "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.\n\n### Authorization\n\nRequires an API credential with `catalog:write`. OmniCommerce derives `organizationId` from that credential; the request body cannot select or override an organization.\n\n### Marketplace sync\n\nThe update is Omni-only by default. Set `syncToMarketplaces` to `true` to queue durable marketplace work. Omit `targets` to sync every enabled, published account for the product, or provide exact `{ platform, accountId }` targets. Every explicit target is validated before the catalog changes. The response contains pollable job IDs and immediate per-target queue status; use `GET /api/v1/jobs/{jobId}` for progress.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "OmniCommerce simple-product or variant UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "price" ] }, { "required": [ "salePrice" ] } ], "properties": { "price": { "type": "number", "minimum": 0, "description": "New catalog list price. Provide price or salePrice." }, "salePrice": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional sale price. Use null to clear it; it must be below the list price." }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "Three-letter ISO currency code." }, "syncToMarketplaces": { "type": "boolean", "default": false, "description": "Queue durable sync jobs after the Omni catalog update." }, "targets": { "type": "array", "minItems": 1, "maxItems": 25, "description": "Exact enabled and published marketplace accounts. Requires syncToMarketplaces=true.", "items": { "type": "object", "additionalProperties": false, "required": [ "platform", "accountId" ], "properties": { "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "maxLength": 255 } } } } } }, "example": { "price": 29.9, "currency": "SGD", "syncToMarketplaces": true, "targets": [ { "platform": "lazada", "accountId": "seller-123" } ] } } } }, "responses": { "200": { "description": "Catalog price updated; no marketplace job was queued.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "ok", "operationId", "status", "productId", "warnings", "recommendations", "links", "data" ], "properties": { "apiVersion": { "type": "string", "enum": [ "developer_v1" ] }, "ok": { "type": "boolean", "enum": [ true ] }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "accepted" ] }, "productId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "additionalProperties": false, "required": [ "changed", "changedFields", "price", "salePrice", "currency", "syncToMarketplaces", "jobIds", "targets", "emittedEvents" ], "properties": { "changed": { "type": "boolean" }, "changedFields": { "type": "array", "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "salePrice": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "syncToMarketplaces": { "type": "boolean" }, "jobIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "platform", "accountId", "status", "jobId" ], "properties": { "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "description": "Exact marketplace store, shop, or seller account ID." }, "status": { "type": "string", "enum": [ "queued" ] }, "jobId": { "type": "string", "format": "uuid" }, "targetId": { "type": "string", "description": "Target correlation within a price-sync batch." } } } }, "emittedEvents": { "type": "array", "items": { "type": "string", "enum": [ "product.price.changed" ] } } } } } } } } }, "202": { "description": "Catalog price updated and marketplace sync queued.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "ok", "operationId", "status", "productId", "warnings", "recommendations", "links", "data" ], "properties": { "apiVersion": { "type": "string", "enum": [ "developer_v1" ] }, "ok": { "type": "boolean", "enum": [ true ] }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "accepted" ] }, "productId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "additionalProperties": false, "required": [ "changed", "changedFields", "price", "salePrice", "currency", "syncToMarketplaces", "jobIds", "targets", "emittedEvents" ], "properties": { "changed": { "type": "boolean" }, "changedFields": { "type": "array", "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "salePrice": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "syncToMarketplaces": { "type": "boolean" }, "jobIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "platform", "accountId", "status", "jobId" ], "properties": { "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "description": "Exact marketplace store, shop, or seller account ID." }, "status": { "type": "string", "enum": [ "queued" ] }, "jobId": { "type": "string", "format": "uuid" }, "targetId": { "type": "string", "description": "Target correlation within a price-sync batch." } } } }, "emittedEvents": { "type": "array", "items": { "type": "string", "enum": [ "product.price.changed" ] } } } } } } } } }, "400": { "description": "Invalid price, variant selection, or marketplace target." }, "401": { "description": "Unauthorized" }, "403": { "description": "Credential lacks catalog:write or organization is inactive." }, "404": { "description": "Product or variant not found." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/{productId}/publish": { "post": { "operationId": "post_v1_products_by_productid_publish", "summary": "Publish Product", "description": "### Publishing\n\nQueue durable marketplace publish/update jobs for a product. Omit marketplaces to use every enabled or already listed marketplace, or name the marketplaces to target. Omit updateFields for a full publish with live/draft visibility. Set updateFields to update only saved values for those fields on existing listings with assigned stores; other fields and listing visibility stay unchanged. No new listing is created by a selected-field update.\n\n### Marketplace capabilities\n\nSEO is Shopify-only; highlights support Lazada, TikTok and Amazon; attributes exclude WhatsApp. Category-only updates require a full publish on TikTok and Amazon. Unsupported combinations and missing listings/stores return explicit per-marketplace failures while valid targets continue.\n\n### Completion\n\nAccepted means queued; inspect every result and await every jobId and inventory correlation with jobs.wait, then verify the listings.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "OmniCommerce product ID to publish.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations." }, "marketplaces": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "description": "Optional marketplaces to publish/update. Omit to target every enabled or already listed marketplace. Duplicates are removed in first-requested order." }, "updateFields": { "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "string", "enum": [ "name", "description", "images", "category", "attributes", "highlights", "seo", "price", "inventory" ] }, "description": "Optional fields to publish from saved product data to existing listings only. Omit for all fields. Other fields and listing visibility remain unchanged. Empty/unknown fields are rejected; duplicates are removed. Platform capability limits appear in per-target results." }, "visibility": { "type": "string", "enum": [ "live", "draft" ], "default": "live", "description": "Publish visibility mode." } } }, "example": { "marketplaces": [ "shopee", "lazada" ], "updateFields": [ "name", "description", "images" ] } } } }, "responses": { "202": { "description": "Publish jobs queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted" ] }, "productId": { "type": "string" }, "jobId": { "type": "string" }, "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "jobBatchId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "required": [ "ok", "productId" ], "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "queued": { "type": "boolean" }, "productId": { "type": "string" }, "sourceProductId": { "type": "string" }, "productName": { "type": "string" }, "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "action": { "type": "string", "enum": [ "created", "updated" ] }, "visibility": { "type": "string", "enum": [ "live", "draft" ], "description": "Requested visibility; selected-field updates preserve existing listing visibility." }, "updateFields": { "type": "array", "items": { "type": "string", "enum": [ "name", "description", "images", "category", "attributes", "highlights", "seo", "price", "inventory" ] } }, "jobId": { "type": "string", "description": "Await this durable job with jobs.wait." }, "error": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" }, "correlations": { "type": "array", "items": { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "inventory_job" ] }, "id": { "type": "string", "description": "Inventory job ID; await every returned correlation with jobs.wait." }, "platform": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "storeId": { "type": "string" }, "productId": { "type": "string" } } } } } } } } } } } } } }, "400": { "description": "Bad Request - invalid payload, marketplace not enabled, or store selection required" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Product Not Found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/bulk-import": { "post": { "operationId": "post_v1_products_bulk_import", "summary": "Bulk Import Products from JSON or CSV", "description": "Queue a bulk product import for the authenticated organization.\n\n### Input options\n\n- Upload a CSV (2 MiB) or JSON products file (8 MiB) using `multipart/form-data`.\n- Send JSON with a `products` array of 1–5,000 flat product objects (8 MiB request maximum).\n- Send JSON with inline `csvText`.\n- Send JSON referencing a stored `documentId`.\n\n### Asynchronous result\n\nThe API creates import rows, then queues draft creation and AI Review through Inngest. Completed import jobs expose `reviewBatchIds`, `reviewUrls`, and `reviewWarnings`; generated changes require Review approval. Poll the returned `bulk_...` job with `GET /api/v1/jobs/{jobId}`.\n\nCancel an in-flight import with `POST /api/v1/jobs/{jobId}/cancel`.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "products": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 200 }, "title": { "type": "string", "maxLength": 400 }, "gtin": { "type": "string", "maxLength": 100 }, "brand": { "type": "string", "maxLength": 160 }, "description": { "type": "string", "maxLength": 10000 }, "price": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "compareAtPrice": { "type": "number", "minimum": 0 }, "salePrice": { "type": "number", "minimum": 0 }, "costPerItem": { "type": "number", "minimum": 0 }, "inventory": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "images": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 2048, "format": "uri" } }, "category": { "type": "string", "maxLength": 255 }, "categoryName": { "type": "string", "maxLength": 500 }, "weight": { "type": "number", "minimum": 0 }, "dimensions": { "type": "object", "properties": { "length": { "type": "number", "minimum": 0 }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 } }, "required": [ "length", "width", "height" ], "additionalProperties": false } }, "required": [ "sku" ], "additionalProperties": false } }, "organizationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "csvText": { "type": "string" }, "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "fileName": { "type": "string", "maxLength": 500 }, "selectedRowIndexes": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "lane": { "type": "string", "enum": [ "standard", "enterprise" ] }, "targetMarketplaces": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, "targetCountries": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "fieldMapping": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "dedupPolicy": { "type": "string", "enum": [ "keep_first", "keep_last", "merge_fields_prefer_non_empty", "fail_job" ] }, "autoApproveThreshold": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "spendCeilingUsd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "marketplaceStoreSelections": { "type": "object", "minProperties": 1, "description": "Required: select at least one connected store. One store per marketplace, not an array of store IDs.", "properties": { "shopee": { "type": "string", "description": "Connected shopee store ID." }, "lazada": { "type": "string", "description": "Connected lazada store ID." }, "tiktok": { "type": "string", "description": "Connected tiktok store ID." }, "shopify": { "type": "string", "description": "Connected shopify store ID." }, "whatsapp": { "type": "string", "description": "Connected whatsapp store ID." }, "zalora": { "type": "string", "description": "Connected zalora store ID." }, "amazon": { "type": "string", "description": "Connected amazon store ID." }, "ebay": { "type": "string", "description": "Connected ebay store ID." } }, "additionalProperties": false }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "imageAnnotationTemplateId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "imageAnnotationGalleryTemplateId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "imageAnnotationScope": { "type": "string", "enum": [ "primary", "all_gallery" ] }, "workflow": { "type": "object", "properties": { "enableRichDescription": { "type": "boolean" }, "sourceImagesAutomatically": { "type": "boolean" }, "autoAssignMarketplaceTaxonomy": { "type": "boolean" }, "enableBackgroundRemoval": { "type": "boolean" }, "enableMannequinRemoval": { "type": "boolean" }, "skipImageTagging": { "type": "boolean" }, "skipZeroInventoryProducts": { "type": "boolean" }, "excludedImageTags": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } } ] }, "enabledBuiltInImageTags": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "customImageTags": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "minLength": 1, "maxLength": 280 } }, "required": [ "name", "description" ] } }, "enrich": { "type": "boolean" }, "disableAcoGeneration": { "description": "Accepted for compatibility. Bulk import does not queue ACO.", "type": "boolean" }, "skipEnrichment": { "type": "boolean" }, "skipBackgroundRemoval": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "targetMarketplaces", "marketplaceStoreSelections" ], "oneOf": [ { "required": [ "products" ] }, { "required": [ "csvText" ] }, { "required": [ "documentId" ] } ] }, "example": { "products": [ { "sku": "SKU-1", "title": "Sample product", "price": 19.9, "costPerItem": 10, "inventory": 20, "images": [ "https://cdn.example.com/sku-1.jpg" ] } ], "targetMarketplaces": [ "shopee" ], "marketplaceStoreSelections": { "shopee": "store_123" }, "workflow": { "enableRichDescription": true, "autoAssignMarketplaceTaxonomy": true } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "targetMarketplaces", "marketplaceStoreSelections" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file or JSON array containing product rows. JSON object files may wrap the array as `products`." }, "organizationId": { "type": "string", "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations." }, "fileName": { "type": "string", "description": "Optional display name override. Defaults to the uploaded file name." }, "title": { "type": "string", "maxLength": 120, "description": "Optional name for the generated Review job." }, "targetMarketplaces": { "oneOf": [ { "type": "string", "description": "Comma-separated marketplace list, e.g. `shopee,lazada`." }, { "type": "array", "items": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } } ] }, "targetCountries": { "oneOf": [ { "type": "string", "description": "Ignored. Catalog country comes from marketplaceStoreSelections." }, { "type": "array", "items": { "type": "string" } } ] }, "fieldMapping": { "type": "string", "description": "JSON object mapping CSV headers to import fields, e.g. `{\"sku\":\"SKU\",\"title\":\"Product Name\"}`." }, "marketplaceStoreSelections": { "oneOf": [ { "type": "object", "minProperties": 1, "description": "Required: select at least one connected store. One store per marketplace, not an array of store IDs.", "properties": { "shopee": { "type": "string", "description": "Connected shopee store ID." }, "lazada": { "type": "string", "description": "Connected lazada store ID." }, "tiktok": { "type": "string", "description": "Connected tiktok store ID." }, "shopify": { "type": "string", "description": "Connected shopify store ID." }, "whatsapp": { "type": "string", "description": "Connected whatsapp store ID." }, "zalora": { "type": "string", "description": "Connected zalora store ID." }, "amazon": { "type": "string", "description": "Connected amazon store ID." }, "ebay": { "type": "string", "description": "Connected ebay store ID." } }, "additionalProperties": false }, { "type": "string", "description": "Multipart form fields are strings. Send the same object encoded as JSON, e.g. `{\"shopee\":\"store_123\"}`." } ], "description": "Connected store ID for each target marketplace. JSON requests send an object; multipart may send that object as a JSON string." }, "selectedRowIndexes": { "type": "string", "description": "JSON array of zero-based CSV row indexes to import." }, "lane": { "type": "string", "enum": [ "standard", "enterprise" ] }, "dedupPolicy": { "type": "string", "enum": [ "keep_first", "keep_last", "merge_fields_prefer_non_empty", "fail_job" ] }, "autoApproveThreshold": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Optional confidence threshold between 0 and 1, or the string `null`." }, "spendCeilingUsd": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "model": { "type": "string", "description": "Optional enrichment model override." }, "imageAnnotationTemplateId": { "type": "string", "format": "uuid" }, "imageAnnotationGalleryTemplateId": { "type": "string", "format": "uuid" }, "imageAnnotationScope": { "type": "string", "enum": [ "primary", "all_gallery" ] }, "workflow": { "type": "string", "description": "JSON object with enrichment workflow options such as `sourceImagesAutomatically`, `enableRichDescription`, and `autoAssignMarketplaceTaxonomy`." } } } } } }, "responses": { "202": { "description": "Bulk import workflow accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string" }, "jobId": { "type": "string", "description": "Bulk import job ID with `bulk_` prefix." }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "rowCount": { "type": "integer" }, "fileName": { "type": "string" }, "targetMarketplaces": { "type": "array", "items": { "type": "string" } }, "targetCountries": { "type": "array", "items": { "type": "string" } }, "fieldMapping": { "type": "object" }, "counts": { "type": "object" } } } } } } } }, "400": { "description": "Bad Request - Invalid products, CSV, or payload" }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Token not authorized for this organization" }, "413": { "description": "Payload Too Large - JSON request or file upload exceeds limit" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/compare-prices": { "post": { "operationId": "post_v1_products_compare_prices", "summary": "Compare Product Market Prices", "description": "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.\n\n### Authorization\n\nRequires catalog:read. API keys resolve organizationId from the credential; session callers must provide an authorized organizationId.\n\n### Durable batches\n\nAccepts 1–50 input entries, trimmed and deduplicated in first-requested order. Returns HTTP 202 and a durable jobId. Retrieve progress and results from GET /api/v1/products/compare-prices/jobs/{jobId} or await jobs.wait in the SDK with a suitable timeout. A client timeout does not cancel the job. Use variant IDs for products with variants. Each listing market has its own durable search step; searches use bounded concurrency and retry failed providers once. Final result.success is true only when every requested product and listing market succeeds. Partial failures remain explicit.\n\nOmit country/gl to compare every recorded listing market. Global Zalora compares its exact country prices in SG, MY, ID, PH, HK, and TW as present on the listing; variant offers use exact SKU/variant identity. An India Shopify store selling in SGD is researched in Singapore because market selection follows selling currency, not the store address. gl overrides country and restricts research to that market. Unsupported currencies and missing country prices are reported without silently skipping listings or converting currencies.\n\nresults[].markets contains separate platform/store/country prices and shopping statistics. Prices come from persisted marketplace snapshots or acknowledged marketplace writes; priceSource and priceAsOf identify the evidence. Published listings without exact price evidence may return catalog research but success is false, with an explicit verification error. Unlisted products use their catalog price/currency. Research does not refresh the connected marketplace listing; refresh stale listing data before comparing.\n\nMarket comparison measures recorded listing list price minus market median (p50), with percentage relative to the median. Catalog fallback comparisons use the explicitly named catalog_price_vs_market_median metric. The product-level currentPrice/currency remain catalog fields; product-level research/comparison are available only for a single market with compatible currency. For multiple markets, consume markets[]. These differences are not recommended selling prices; monetary values are never combined across currencies.\n\nShopping search coverage depends on the provider index; individual marketplaces and listings are not verified.\n\nOffers may refer to different variants, pack sizes, bundles, or similar products. Verify the offer before using its price.\n\nPricing strategy excludes offers from ebay and walmart.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "productIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "OmniCommerce simple product or variant UUIDs. Deduplicated in first-requested order; maximum 50 input entries." }, "country": { "type": "string", "enum": [ "Singapore", "Indonesia", "Malaysia", "Vietnam", "Thailand", "Philippines" ] }, "gl": { "description": "Optional shopping market restriction; overrides country. Omit to compare every listing market using its currency, or the catalog currency for unlisted products.", "type": "string", "enum": [ "sg", "id", "my", "vn", "th", "ph", "us", "hk", "tw" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 15 } }, "required": [ "productIds" ], "additionalProperties": false }, "example": { "productIds": [ "cc87d195-097a-4a5a-8229-cd989ce98d0f" ], "gl": "sg", "limit": 15 } } } }, "responses": { "202": { "description": "Batch accepted. jobId tracks durable progress; acceptance does not mean comparisons succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "apiVersion", "operationId", "status", "jobId", "data", "warnings", "recommendations", "links" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "accepted" ] }, "jobId": { "type": "string" }, "data": { "type": "object", "properties": { "jobId": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "jobId", "productIds" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "400": { "description": "Invalid payload or missing session organizationId." }, "401": { "description": "Missing or invalid credentials." }, "403": { "description": "Missing catalog:read or unauthorized organization/product scope." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Unable to load comparison data." } } } }, "/api/v1/products/compare-prices/jobs/{jobId}": { "get": { "operationId": "get_v1_products_compare_prices_jobs_by_jobid", "summary": "Get Product Price Comparison", "description": "Read durable batch progress and ordered per-product results. Requires catalog:read and the job's organization.\n\ncompleted means every target was processed; inspect result.success, succeededCount, failedCount, and each result for partial failures. Session callers must supply organizationId.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current progress or completed results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "price_comparison" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "productIds": { "type": "array", "items": { "type": "string" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "processed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "success": { "type": "boolean" }, "retryable": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "research": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "queries": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "gl": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "price": { "type": "number" }, "priceText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "price", "priceText", "source", "link" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "percentiles": { "type": "object", "properties": { "p20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p80": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "p20", "p50", "p80" ], "additionalProperties": false } }, "required": [ "min", "max", "avg", "percentiles" ], "additionalProperties": false }, "pricingBands": { "type": "object", "properties": { "low": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "high": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "low", "mid", "high" ], "additionalProperties": false } }, "required": [ "success", "queries", "gl", "count", "items", "stats", "pricingBands" ], "additionalProperties": false }, { "type": "null" } ] }, "comparison": { "anyOf": [ { "type": "object", "properties": { "metric": { "type": "string", "const": "catalog_price_vs_market_median" }, "currency": { "type": "string" }, "medianPrice": { "type": "number" }, "differenceAmount": { "type": "number" }, "differencePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "currency", "medianPrice", "differenceAmount", "differencePercent" ], "additionalProperties": false }, { "type": "null" } ] }, "markets": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "anyOf": [ { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, { "type": "null" } ] }, "storeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listingCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceSource": { "type": "string", "enum": [ "marketplace_snapshot", "acknowledged_write", "catalog_fallback" ] }, "priceAsOf": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "success": { "type": "boolean" }, "retryable": { "type": "boolean" }, "research": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "queries": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "gl": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "price": { "type": "number" }, "priceText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "price", "priceText", "source", "link" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "percentiles": { "type": "object", "properties": { "p20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p80": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "p20", "p50", "p80" ], "additionalProperties": false } }, "required": [ "min", "max", "avg", "percentiles" ], "additionalProperties": false }, "pricingBands": { "type": "object", "properties": { "low": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "high": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "low", "mid", "high" ], "additionalProperties": false } }, "required": [ "success", "queries", "gl", "count", "items", "stats", "pricingBands" ], "additionalProperties": false }, { "type": "null" } ] }, "comparison": { "anyOf": [ { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "catalog_price_vs_market_median", "listing_price_vs_market_median" ] }, "currency": { "type": "string" }, "medianPrice": { "type": "number" }, "differenceAmount": { "type": "number" }, "differencePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "currency", "medianPrice", "differenceAmount", "differencePercent" ], "additionalProperties": false }, { "type": "null" } ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "marketplace", "storeId", "listingCountry", "country", "gl", "currency", "currentPrice", "priceSource", "priceAsOf", "success", "retryable", "research", "comparison", "warnings" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "productId", "success", "retryable", "name", "sku", "currentPrice", "currency", "research", "comparison", "markets", "warnings" ], "additionalProperties": false } }, "result": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "productIds": { "type": "array", "items": { "type": "string" } }, "succeededCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "success": { "type": "boolean" }, "retryable": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "research": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "queries": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "gl": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "price": { "type": "number" }, "priceText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "price", "priceText", "source", "link" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "percentiles": { "type": "object", "properties": { "p20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p80": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "p20", "p50", "p80" ], "additionalProperties": false } }, "required": [ "min", "max", "avg", "percentiles" ], "additionalProperties": false }, "pricingBands": { "type": "object", "properties": { "low": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "high": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "low", "mid", "high" ], "additionalProperties": false } }, "required": [ "success", "queries", "gl", "count", "items", "stats", "pricingBands" ], "additionalProperties": false }, { "type": "null" } ] }, "comparison": { "anyOf": [ { "type": "object", "properties": { "metric": { "type": "string", "const": "catalog_price_vs_market_median" }, "currency": { "type": "string" }, "medianPrice": { "type": "number" }, "differenceAmount": { "type": "number" }, "differencePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "currency", "medianPrice", "differenceAmount", "differencePercent" ], "additionalProperties": false }, { "type": "null" } ] }, "markets": { "type": "array", "items": { "type": "object", "properties": { "marketplace": { "anyOf": [ { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, { "type": "null" } ] }, "storeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listingCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceSource": { "type": "string", "enum": [ "marketplace_snapshot", "acknowledged_write", "catalog_fallback" ] }, "priceAsOf": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "success": { "type": "boolean" }, "retryable": { "type": "boolean" }, "research": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "queries": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "gl": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "price": { "type": "number" }, "priceText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "price", "priceText", "source", "link" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "percentiles": { "type": "object", "properties": { "p20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p80": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "p20", "p50", "p80" ], "additionalProperties": false } }, "required": [ "min", "max", "avg", "percentiles" ], "additionalProperties": false }, "pricingBands": { "type": "object", "properties": { "low": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "high": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "low", "mid", "high" ], "additionalProperties": false } }, "required": [ "success", "queries", "gl", "count", "items", "stats", "pricingBands" ], "additionalProperties": false }, { "type": "null" } ] }, "comparison": { "anyOf": [ { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "catalog_price_vs_market_median", "listing_price_vs_market_median" ] }, "currency": { "type": "string" }, "medianPrice": { "type": "number" }, "differenceAmount": { "type": "number" }, "differencePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "currency", "medianPrice", "differenceAmount", "differencePercent" ], "additionalProperties": false }, { "type": "null" } ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "marketplace", "storeId", "listingCountry", "country", "gl", "currency", "currentPrice", "priceSource", "priceAsOf", "success", "retryable", "research", "comparison", "warnings" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "productId", "success", "retryable", "name", "sku", "currentPrice", "currency", "research", "comparison", "markets", "warnings" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "productIds", "succeededCount", "failedCount", "results", "warnings" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "productIds", "total", "processed", "remaining", "results", "result", "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credentials." }, "403": { "description": "Unauthorized organization or missing catalog:read." }, "404": { "description": "Job not found in the authorized organization." }, "429": { "description": "Rate limit exceeded." } } } }, "/api/v1/products/cost": { "post": { "operationId": "post_v1_products_cost", "summary": "Batch Update Product Cost", "description": "Set catalog cost price and currency for one or more products. Cost is Omni-only and never syncs to marketplaces.\n\nEach update targets `productId` or `sku` (Omni `products.sku`). Provide `costPrice` with `costPriceCurrency` when the source amount is not in the product selling currency. If `costPriceFxRate` is omitted and the currencies differ, Omni quotes FX via the canonical FX service and stores the rate on the product.\n\n### Authorization\n\nRequires `catalog:write`. `organizationId` comes from the credential; the body cannot select an organization.\n\n### Limits\n\n`updates` is required, 1–200 items. Duplicate product IDs fail after the first occurrence. `costPrice: null` clears cost and FX.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "updates" ], "properties": { "updates": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "required": [ "costPrice" ], "anyOf": [ { "required": [ "productId" ] }, { "required": [ "sku" ] } ], "properties": { "productId": { "type": "string", "format": "uuid" }, "sku": { "type": "string", "minLength": 1, "maxLength": 200 }, "costPrice": { "type": [ "number", "null" ], "minimum": 0, "description": "Source cost amount. Null clears catalog cost and FX." }, "costPriceCurrency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO currency of costPrice, for example USD. Defaults to the product selling currency." }, "costPriceFxRate": { "type": "number", "exclusiveMinimum": 0, "description": "Optional units of selling currency per 1 costPriceCurrency. Quoted automatically when omitted and currencies differ." }, "costPriceFxTo": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "Must match the product selling currency when provided." }, "costPriceFxAsOf": { "type": "string", "description": "Optional YYYY-MM or YYYY-MM-DD quote date." } } } } } }, "example": { "updates": [ { "sku": "TLVBGLX83220", "costPrice": 578, "costPriceCurrency": "USD" } ] } } } }, "responses": { "200": { "description": "Batch processed. Top-level success is true only when every update succeeded." }, "400": { "description": "Invalid payload." }, "401": { "description": "Unauthorized" }, "403": { "description": "Credential lacks catalog:write or organization is inactive." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/products/enrich": { "post": { "operationId": "post_v1_products_enrich", "summary": "Queue Product Enrichment", "description": "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.\n\n### Enrichment options\n\nFields, instructions and auto-apply settings use the canonical enrichment service. Exclude name from selectedFields to preserve titles. Weight and dimensions are always included; image and taxonomy workflows are not queued here.\n\nautoApplyHighConfidence defaults to false. When enabled, the supplied threshold (0.62–1) or organization threshold applies; low-confidence or blocked proposals remain in Review. AI usage is billed to the authenticated organization. Open links.review to inspect results.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "description": "Required for session auth; derived from the credential for bearer auth.", "type": "string", "minLength": 1, "maxLength": 255 }, "productIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Existing Omni product IDs. Trimmed and deduplicated in requested order; at most 1,000 entries." }, "selectedFields": { "description": "Fields to enrich. Omit for all content fields. Weight and dimensions are always included by the enrichment service. Exclude name to preserve the product title.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "name", "description", "highlights", "seoTitle", "seoDescription", "weight", "dimensions" ] } }, "instructions": { "type": "string", "maxLength": 2000 }, "title": { "type": "string", "maxLength": 120 }, "autoApplyHighConfidence": { "default": false, "type": "boolean" }, "enrichmentAutoApplyThreshold": { "description": "Confidence threshold for automatic application when enabled. Omit to use the organization's threshold.", "type": "number", "minimum": 0.62, "maximum": 1 } }, "required": [ "productIds" ], "additionalProperties": false }, "example": { "productIds": [ "omni-product-id" ], "selectedFields": [ "description" ], "instructions": "Do not change the title. Do not add warranty or return information.", "autoApplyHighConfidence": true, "enrichmentAutoApplyThreshold": 0.7 } } } }, "responses": { "202": { "description": "Jobs accepted for background processing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "status", "jobId", "data", "links" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted" ] }, "jobId": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "required": [ "success", "queued", "productIds", "jobIds", "succeededCount", "failedCount", "results" ], "properties": { "success": { "type": "boolean", "description": "True when all requested targets were accepted for processing. Does not mean processing completed." }, "queued": { "type": "boolean" }, "productIds": { "type": "array", "items": { "type": "string" } }, "jobIds": { "type": "array", "items": { "type": "string" } }, "succeededCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "batchJobId": { "type": "string" }, "enrichmentBatchId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "required": [ "productId", "success", "jobId" ], "properties": { "productId": { "type": "string" }, "success": { "type": "boolean" }, "jobId": { "type": "string" } } } } } } } } } } }, "400": { "description": "Invalid request or queue preparation failed. Inspect the error before resubmitting." }, "401": { "description": "Missing or invalid credentials." }, "403": { "description": "Missing scope, insufficient permission, organization mismatch, or inactive organization." }, "404": { "description": "Target not found in the authenticated organization." }, "409": { "description": "An import or enrichment job is already active for the target." }, "429": { "description": "Rate limit exceeded." } } } }, "/api/v1/promotions": { "get": { "operationId": "get_v1_promotions", "summary": "List Promotions", "description": "List central promotions for the authenticated organization with filters and offset pagination matching the workspace Promotions listing. Requires `promotions:read`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Search promotion name.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "description": "Effective status filter: `all`, `draft`, `scheduled`, `active`, `paused`, `ended`, or `archived`.", "schema": { "type": "string", "enum": [ "all", "draft", "scheduled", "active", "paused", "ended", "archived" ] } }, { "name": "marketplace", "in": "query", "required": false, "description": "Comma-separated marketplaces, for example `shopee,lazada,tiktok,shopify`.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated promotion store keys (`marketplace:country:storeId`).", "schema": { "type": "string", "maxLength": 2000 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort field.", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "name", "startsAt", "status" ], "default": "createdAt" } }, { "name": "sortDir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Default 20, max 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Promotions page returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "summary" ], "properties": { "items": { "type": "array", "items": { "type": "object" } }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer" }, "summary": { "type": "object" }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] }, "maxLimit": { "type": "integer" }, "defaultLimit": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_promotions", "summary": "Create Promotion", "description": "Create a central promotion targeting connected stores. Requires `promotions:write`. Fixed-amount discounts resolve currency from the selected store countries.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "discountType", "discountValue", "targetStores" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Required for session auth across multiple organizations. Optional for OAuth/API keys bound to one organization." }, "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "kind": { "type": "string", "enum": [ "product_discount", "flash_sale", "voucher", "gift_with_purchase", "buy_x_get_y", "bundle_deal", "free_shipping", "early_bird_price" ] }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0, "description": "Discount amount or percentage. Use 0 for gift/sample-only and free Buy-X-Get-Y mechanics." }, "targetStores": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "marketplace", "country", "storeId" ], "properties": { "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ] }, "country": { "type": "string" }, "storeId": { "type": "string" } } }, "description": "Connected stores as `{ marketplace, country, storeId }`. Copy from existing promotion targetStores or product marketplaceDetails." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "ended", "archived" ], "default": "active", "description": "Defaults to active. Future start dates display as scheduled. Use draft to save without activation; explicit inactive lifecycle states are preserved." }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "minSalePrice": { "type": [ "number", "null" ], "minimum": 0 }, "maxDiscountAmount": { "type": [ "number", "null" ], "minimum": 0 }, "minSpend": { "type": [ "number", "null" ], "minimum": 0, "description": "Lazada voucher minimum spend. Defaults to 1 when unset." }, "totalUsageLimit": { "type": [ "integer", "null" ], "minimum": 1, "description": "Total redemption/order limit, or per-SKU promotional quantity for flash sales." }, "mechanicConfig": { "type": "object", "additionalProperties": false, "properties": { "voucherCampaign": { "type": "object", "additionalProperties": false, "required": [ "campaignId", "sessionId", "termsAccepted" ], "description": "Exact Shopee campaign/session for Campaign Voucher Nomination, with reviewed participation obligations. Nomination remains a draft until Shopee approval.", "properties": { "campaignId": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[1-9][0-9]{0,39}$" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[1-9][0-9]{0,39}$" }, "termsAccepted": { "type": "boolean" } } }, "voucherType": { "type": [ "string", "null" ], "enum": [ "shopee_shop", "shopee_product", "shopee_private", "shopee_live", "shopee_video", "shopee_new_buyer", "shopee_repeat_buyer", "shopee_campaign", "shopee_follow_prize", "shopee_exclusive_streamer", "shopee_welcome", "shopee_member_repeat_buyer", "shopee_exclusive", "shopee_redemption", "shopee_exclusive_creator", "lazada_store_follower", "lazada_regular", "lazada_store_new_buyer", "lazada_live", "lazada_offline", "lazada_co_funded", "lazada_welcome", "lazada_linked_member", "lazada_new_member", "lazada_member_exclusive", "lazada_points_redeemable", "tiktok_seller_coupon", "shopify_discount_code", "amazon_promotion_code", "zalora_seller_voucher", "ebay_coded_coupon", null ], "description": "Exact marketplace voucher subtype. Native types use APIs; Seller Center-only types use a browser AOP with per-store eligibility checks." }, "browserAutomation": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "variableValues": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "string", "maxLength": 8000 }, "description": "Optional overrides for the selected AOP's declared variables. promotionId, action, and storeId are supplied automatically; the AOP loads the campaign with get_promotions." }, "aopId": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Optional organization AOP override. Omit to select the built-in marketplace AOP." }, "instructions": { "type": "string", "maxLength": 8000 } } }, "voucherScope": { "type": "string", "enum": [ "products", "shop" ] }, "voucherReward": { "type": "string", "enum": [ "discount", "coins_cashback" ] }, "exclusiveStreamerUsernames": { "type": "array", "maxItems": 15, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Approved Shopee usernames targeted by an Exclusive Streamer voucher. The Seller Centre API resolves eligible streamer identities; user IDs must not be supplied here." }, "voucherAudience": { "type": "string", "enum": [ "general", "shop_follow" ] }, "voucherDisplayChannels": { "type": "array", "maxItems": 4, "description": "Shopee supports all, feed, live, order_page (update only), or [] for hidden. Lazada requires exactly one of all, live, followers, offline; followers requires voucherScope=shop.", "items": { "type": "string", "enum": [ "all", "feed", "live", "order_page", "followers", "offline" ] } }, "bundlePriceType": { "type": "string", "enum": [ "discount", "fixed_price" ] }, "bundleTiers": { "type": "array", "maxItems": 2, "items": { "type": "object", "required": [ "minimumQuantity", "discountValue" ], "properties": { "minimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "discountValue": { "type": "number", "exclusiveMinimum": 0 } } } }, "thresholdType": { "type": "string", "enum": [ "item_quantity", "order_amount" ] }, "thresholdValue": { "type": "number", "exclusiveMinimum": 0 }, "giftType": { "type": "string", "enum": [ "gift", "sample" ] }, "giftQuantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "gifts": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "totalClaimLimit" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "variantId": { "type": [ "string", "null" ], "format": "uuid" }, "totalClaimLimit": { "type": "integer", "minimum": 1, "maximum": 99999 } } } }, "buyQuantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "getQuantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "benefitProductIds": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "format": "uuid" } }, "benefitType": { "type": "string", "enum": [ "free", "percentage", "fixed_amount" ] }, "benefitValue": { "type": "number", "minimum": 0 }, "maxApplicationsPerOrder": { "type": "integer", "minimum": 1, "maximum": 999 }, "bundleMinimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "shippingDeliveryOption": { "type": "string", "pattern": "^[A-Z0-9_]{1,40}$", "description": "Free shipping delivery option offered by the Lazada store; defaults to STANDARD." }, "shippingBudget": { "type": "number", "exclusiveMinimum": 0, "description": "Free shipping subsidy budget in the store currency. Omit for an unlimited budget." } } }, "storeDiscounts": { "type": "array", "maxItems": 100, "description": "Patch discount overrides by exact target store key. Other stores retain their terms. Null discountValue restores shared terms for that store.", "items": { "type": "object", "additionalProperties": false, "required": [ "storeKey", "discountType", "discountValue" ], "properties": { "storeKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": [ "number", "null" ], "minimum": 0, "description": "Percentage must not exceed 100." } } } } } }, "example": { "name": "Christmas", "discountType": "fixed_amount", "discountValue": 12, "targetStores": [ { "marketplace": "shopee", "country": "singapore", "storeId": "115085776" } ], "startsAt": "2026-07-06T17:00:00.000Z", "endsAt": "2026-08-02T03:59:00.000Z" } } } }, "responses": { "201": { "description": "Promotion created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "promotion" ], "properties": { "promotion": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:write` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/promotions/{promotionId}": { "get": { "operationId": "get_v1_promotions_by_promotionid", "summary": "Get Promotion", "description": "Fetch one promotion by ID, including effective status. Requires `promotions:read`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Promotion returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "promotion" ], "properties": { "promotion": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:read` scope" }, "404": { "description": "Promotion not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "operationId": "patch_v1_promotions_by_promotionid", "summary": "Update Promotion", "description": "Update promotion fields (name, discount, schedule, status, stores). Requires `promotions:write`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "kind": { "type": "string", "enum": [ "product_discount", "flash_sale", "voucher", "gift_with_purchase", "buy_x_get_y", "bundle_deal", "free_shipping", "early_bird_price" ] }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0, "description": "Discount amount or percentage. Use 0 for gift/sample-only and free Buy-X-Get-Y mechanics." }, "targetStores": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "marketplace", "country", "storeId" ], "properties": { "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ] }, "country": { "type": "string" }, "storeId": { "type": "string" } } } }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "ended", "archived" ] }, "minSalePrice": { "type": [ "number", "null" ], "minimum": 0 }, "maxDiscountAmount": { "type": [ "number", "null" ], "minimum": 0 }, "minSpend": { "type": [ "number", "null" ], "minimum": 0 }, "totalUsageLimit": { "type": [ "integer", "null" ], "minimum": 1 }, "mechanicConfig": { "type": "object", "additionalProperties": false, "properties": { "voucherCampaign": { "type": "object", "additionalProperties": false, "required": [ "campaignId", "sessionId", "termsAccepted" ], "description": "Exact Shopee campaign/session for Campaign Voucher Nomination, with reviewed participation obligations. Nomination remains a draft until Shopee approval.", "properties": { "campaignId": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[1-9][0-9]{0,39}$" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[1-9][0-9]{0,39}$" }, "termsAccepted": { "type": "boolean" } } }, "voucherType": { "type": [ "string", "null" ], "enum": [ "shopee_shop", "shopee_product", "shopee_private", "shopee_live", "shopee_video", "shopee_new_buyer", "shopee_repeat_buyer", "shopee_campaign", "shopee_follow_prize", "shopee_exclusive_streamer", "shopee_welcome", "shopee_member_repeat_buyer", "shopee_exclusive", "shopee_redemption", "shopee_exclusive_creator", "lazada_store_follower", "lazada_regular", "lazada_store_new_buyer", "lazada_live", "lazada_offline", "lazada_co_funded", "lazada_welcome", "lazada_linked_member", "lazada_new_member", "lazada_member_exclusive", "lazada_points_redeemable", "tiktok_seller_coupon", "shopify_discount_code", "amazon_promotion_code", "zalora_seller_voucher", "ebay_coded_coupon", null ], "description": "Exact marketplace voucher subtype. Native types use APIs; Seller Center-only types use a browser AOP with per-store eligibility checks." }, "browserAutomation": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "variableValues": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "string", "maxLength": 8000 }, "description": "Optional overrides for the selected AOP's declared variables. promotionId, action, and storeId are supplied automatically; the AOP loads the campaign with get_promotions." }, "aopId": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Optional organization AOP override. Omit to select the built-in marketplace AOP." }, "instructions": { "type": "string", "maxLength": 8000 } } }, "voucherScope": { "type": "string", "enum": [ "products", "shop" ] }, "voucherReward": { "type": "string", "enum": [ "discount", "coins_cashback" ] }, "exclusiveStreamerUsernames": { "type": "array", "maxItems": 15, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Approved Shopee usernames targeted by an Exclusive Streamer voucher. The Seller Centre API resolves eligible streamer identities; user IDs must not be supplied here." }, "voucherAudience": { "type": "string", "enum": [ "general", "shop_follow" ] }, "voucherDisplayChannels": { "type": "array", "maxItems": 4, "description": "Shopee supports all, feed, live, order_page (update only), or [] for hidden. Lazada requires exactly one of all, live, followers, offline; followers requires voucherScope=shop.", "items": { "type": "string", "enum": [ "all", "feed", "live", "order_page", "followers", "offline" ] } }, "bundlePriceType": { "type": "string", "enum": [ "discount", "fixed_price" ] }, "bundleTiers": { "type": "array", "maxItems": 2, "items": { "type": "object", "required": [ "minimumQuantity", "discountValue" ], "properties": { "minimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "discountValue": { "type": "number", "exclusiveMinimum": 0 } } } }, "thresholdType": { "type": "string", "enum": [ "item_quantity", "order_amount" ] }, "thresholdValue": { "type": "number", "exclusiveMinimum": 0 }, "giftType": { "type": "string", "enum": [ "gift", "sample" ] }, "giftQuantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "gifts": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "totalClaimLimit" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "variantId": { "type": [ "string", "null" ], "format": "uuid" }, "totalClaimLimit": { "type": "integer", "minimum": 1, "maximum": 99999 } } } }, "buyQuantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "getQuantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "benefitProductIds": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "format": "uuid" } }, "benefitType": { "type": "string", "enum": [ "free", "percentage", "fixed_amount" ] }, "benefitValue": { "type": "number", "minimum": 0 }, "maxApplicationsPerOrder": { "type": "integer", "minimum": 1, "maximum": 999 }, "bundleMinimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "shippingDeliveryOption": { "type": "string", "pattern": "^[A-Z0-9_]{1,40}$", "description": "Free shipping delivery option offered by the Lazada store; defaults to STANDARD." }, "shippingBudget": { "type": "number", "exclusiveMinimum": 0, "description": "Free shipping subsidy budget in the store currency. Omit for an unlimited budget." } } }, "storeDiscounts": { "type": "array", "maxItems": 100, "description": "Patch discount overrides by exact target store key. Other stores retain their terms. Null discountValue restores shared terms for that store.", "items": { "type": "object", "additionalProperties": false, "required": [ "storeKey", "discountType", "discountValue" ], "properties": { "storeKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": [ "number", "null" ], "minimum": 0, "description": "Percentage must not exceed 100." } } } } } } } } }, "responses": { "200": { "description": "Promotion updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "promotion" ], "properties": { "promotion": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:write` scope" }, "404": { "description": "Promotion not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "operationId": "delete_v1_promotions_by_promotionid", "summary": "Delete Promotion", "description": "Delete a promotion by ID. Requires `promotions:write`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Promotion deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:write` scope" }, "404": { "description": "Promotion not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/promotions/{promotionId}/products": { "get": { "operationId": "get_v1_promotions_by_promotionid_products", "summary": "List Promotion Assignments", "description": "List products assigned to a promotion. Requires `promotions:read`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Assignments returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:read` scope" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_promotions_by_promotionid_products", "summary": "Assign Products to Promotion", "description": "Assign one or more products to a promotion. Creates pending marketplace sync rows; call sync after assign. Requires `promotions:write`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "productIds" ], "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "productIds": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "format": "uuid" } }, "variantSku": { "type": [ "string", "null" ], "maxLength": 120 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 }, "productDiscounts": { "type": "array", "maxItems": 200, "description": "Optional per-product discount for product discounts and flash sales. Uses the campaign discount type. Null restores the shared discount. Shopee and TikTok publish the resulting price. Lazada vouchers and Shopify fail sync while any product has its own discount.", "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "discountValue" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "discountValue": { "type": [ "number", "null" ], "exclusiveMinimum": 0 } } } } } }, "example": { "productIds": [ "f831911c-ba05-4c83-9a03-e026e0aaf102" ], "priority": 0 } } } }, "responses": { "201": { "description": "Products assigned.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:write` scope" }, "500": { "description": "Internal Server Error" } } }, "delete": { "operationId": "delete_v1_promotions_by_promotionid_products", "summary": "Unassign Products from Promotion", "description": "Remove product assignments and queue marketplace teardown. Requires `promotions:write`.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "productIds" ], "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "productIds": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "format": "uuid" } }, "variantSku": { "type": [ "string", "null" ], "maxLength": 120 } } } } } }, "responses": { "200": { "description": "Products unassigned.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:write` scope" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/promotions/{promotionId}/retry": { "post": { "operationId": "post_v1_promotions_by_promotionid_retry", "summary": "Retry Marketplace Delivery", "description": "Run marketplace delivery again after a failure, for example once a store is reconnected. Requires `promotions:write`.\n\nYou do not need this to publish a promotion: creating or activating it, editing it while active or scheduled, and assigning products already deliver it, and pausing, ending, or archiving removes it. A retry brings each marketplace back in line with the promotion's current status.", "tags": [ "promotions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organizationId": { "type": "string", "maxLength": 120 }, "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ], "description": "Retry one marketplace. When omitted, retries every promotion marketplace." }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Retry only these products. When omitted, retries every assigned product." } } }, "example": { "marketplace": "shopee" } } } }, "responses": { "202": { "description": "Delivery queued again.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "queued", "syncBatchId", "marketplaces" ], "properties": { "ok": { "type": "boolean" }, "queued": { "type": "boolean" }, "jobId": { "type": "string" }, "syncBatchId": { "type": "string" }, "marketplaces": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `promotions:write` scope" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/returns": { "get": { "operationId": "get_v1_returns", "summary": "List Returns", "description": "List normalized, PII-free marketplace returns with SKU-level lines. Requires `returns:read`. Use updatedSince and cursor for bootstrap/recovery alongside return webhooks.", "tags": [ "returns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "marketplace", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "externalOrderId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/returns/{returnId}": { "get": { "operationId": "get_v1_returns_by_returnid", "summary": "Get Return", "description": "Get one normalized, PII-free return by OmniCommerce UUID. Requires `returns:read`; another organization's return returns 404.", "tags": [ "returns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "returnId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "404": { "description": "Return not found." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/reviews": { "get": { "operationId": "get_v1_reviews", "summary": "List Reviews", "description": "List marketplace product reviews, newest first unless `sortBy` says otherwise. Requires `reviews:read`.\n\nUse `priority=unreplied` for a reply queue. `replyRestriction` is null when a reply will be accepted.", "tags": [ "reviews" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "q", "in": "query", "required": false, "description": "Search the comment, product name or SKU, marketplace item id, and review id.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "marketplace", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "replied", "hidden", "handoff", "solicited", "ineligible" ] } }, { "name": "priority", "in": "query", "required": false, "description": "`unreplied`: open reviews the marketplace allows a reply to. `negative`: rating of 3 or lower.", "schema": { "type": "string", "enum": [ "unreplied", "negative" ] } }, { "name": "store", "in": "query", "required": false, "description": "Comma-separated store (account) ids from `GET /api/v1/marketplaces/connected`.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "productId", "in": "query", "required": false, "description": "A product or variant UUID. Includes reviews of the whole product family.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Comma-separated sort keys: reviewed_desc, reviewed_asc, rating_desc, rating_asc, status_asc, status_desc, marketplace_asc, marketplace_desc, product_asc, product_desc. Defaults to reviewed_desc.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "A page of reviews.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Marketplace store id." }, "storeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Confirmed linked variant UUID, or null when the purchased variant is unknown." }, "variantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantSku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalReviewId": { "type": "string" }, "externalOrderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "product_review", "solicitation" ], "description": "`solicitation` rows are Amazon orders you can send a review request for." }, "status": { "type": "string", "enum": [ "open", "replied", "hidden", "handoff", "solicited", "ineligible" ] }, "rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sellerReply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sellerRepliedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canReply": { "type": "boolean", "description": "The marketplace's own reply eligibility flag." }, "replyRestriction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why a reply is not possible right now, or null when the marketplace allows a seller reply." }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketplaceListingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public marketplace product page, when it can be resolved." }, "sellerCenterUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "id", "platform", "accountId", "storeName", "productId", "productName", "productSku", "productThumbnailUrl", "variantId", "variantName", "variantSku", "orderId", "externalItemId", "externalReviewId", "externalOrderId", "kind", "status", "rating", "comment", "sellerReply", "sellerRepliedAt", "canReply", "replyRestriction", "reviewedAt", "marketplaceListingUrl", "sellerCenterUrl", "firstSeenAt", "lastSeenAt" ] } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "reviews", "total", "limit", "offset", "hasMore", "nextOffset" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `reviews:read` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/reviews/{reviewId}": { "get": { "operationId": "get_v1_reviews_by_reviewid", "summary": "Get Review", "description": "Read one review by its OmniCommerce UUID. Requires `reviews:read`.", "tags": [ "reviews" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Required for session auth. API keys already belong to one organization.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "The review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "review": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon", "ebay" ] }, "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Marketplace store id." }, "storeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Confirmed linked variant UUID, or null when the purchased variant is unknown." }, "variantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variantSku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalReviewId": { "type": "string" }, "externalOrderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "product_review", "solicitation" ], "description": "`solicitation` rows are Amazon orders you can send a review request for." }, "status": { "type": "string", "enum": [ "open", "replied", "hidden", "handoff", "solicited", "ineligible" ] }, "rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sellerReply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sellerRepliedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canReply": { "type": "boolean", "description": "The marketplace's own reply eligibility flag." }, "replyRestriction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why a reply is not possible right now, or null when the marketplace allows a seller reply." }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketplaceListingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public marketplace product page, when it can be resolved." }, "sellerCenterUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "id", "platform", "accountId", "storeName", "productId", "productName", "productSku", "productThumbnailUrl", "variantId", "variantName", "variantSku", "orderId", "externalItemId", "externalReviewId", "externalOrderId", "kind", "status", "rating", "comment", "sellerReply", "sellerRepliedAt", "canReply", "replyRestriction", "reviewedAt", "marketplaceListingUrl", "sellerCenterUrl", "firstSeenAt", "lastSeenAt" ] } }, "required": [ "review" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `reviews:read` scope" }, "404": { "description": "Review not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/reviews/{reviewId}/reply": { "post": { "operationId": "post_v1_reviews_by_reviewid_reply", "summary": "Reply to Review", "description": "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 organization AI credits.\n\nRead `data.submitted` for confirmed marketplace submission. Generated text is retained when submission fails. Unsupported marketplaces return their capability limitation. Check review state before retrying an unconfirmed submission. Amazon review requests are separate.", "tags": [ "reviews" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "description": "Seller reply to send to this review. Omit when generateWithAi is true.", "type": "string", "minLength": 1, "maxLength": 500 }, "generateWithAi": { "default": false, "description": "Generate a reply using the review context and organization brand voice. Uses AI credits.", "type": "boolean" }, "submit": { "default": true, "description": "true submits the reply to the marketplace. With generateWithAi, false returns a draft without submitting.", "type": "boolean" }, "instructions": { "description": "Optional writing instructions for AI-generated replies. Requires generateWithAi.", "type": "string", "minLength": 1, "maxLength": 2000 }, "organizationId": { "description": "Required for session auth. API keys already belong to one organization.", "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The reply or draft result for this review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "const": "developer_v1" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "completed", "failed" ] }, "jobId": { "type": "string" }, "productId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "reviewId": { "type": "string" }, "submitted": { "type": "boolean", "description": "True only when the marketplace reply service confirms success. False for a draft or unconfirmed submission." }, "reply": { "type": "string" }, "model": { "type": "string" }, "error": { "type": "string" }, "sellerCenterUrl": { "type": "string" } }, "required": [ "success", "reviewId", "submitted" ] } }, "required": [ "ok", "apiVersion", "operationId", "status", "warnings", "recommendations", "links", "data" ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing the `reviews:write` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/search": { "get": { "operationId": "get_v1_search", "summary": "Search Public Merchant Products", "description": "Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "currency", "in": "query", "required": false, "description": "ISO currency code. Required for price ranges and price sorting; no cross-currency ranking or conversion.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "min_rating", "in": "query", "required": false, "description": "Minimum average imported product review rating. Unrated products do not match; not a marketplace-wide lifetime rating.", "schema": { "type": "number", "minimum": 1, "maximum": 5 } }, { "name": "min_review_count", "in": "query", "required": false, "description": "Minimum number of imported rated product reviews.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "added_after", "in": "query", "required": false, "description": "Inclusive catalog creation timestamp with time zone. Does not mean product release date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "variant_options", "in": "query", "required": false, "description": "JSON array of 1-5 exact, case-insensitive option pairs, e.g. [{\"name\":\"Color\",\"value\":\"Red\"}]. All options must match the same variant.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Natural-language search query.", "schema": { "type": "string", "maxLength": 300 } }, { "name": "category", "in": "query", "required": false, "description": "Optional category-name filter.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "brand", "in": "query", "required": false, "description": "Optional brand filter.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum catalogPrice in the requested currency (inclusive). Requires currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum catalogPrice in the requested currency (inclusive). Requires currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "in_stock", "in": "query", "required": false, "description": "Filter by stock availability.", "schema": { "type": "boolean" } }, { "name": "merchant_ids", "in": "query", "required": false, "description": "Comma-separated merchant IDs to scope the search.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by relevance, newest catalog addition, catalog price, imported average rating, or review count. Price sorting requires currency; most_reviewed is not best selling.", "schema": { "type": "string", "enum": [ "relevance", "newest", "price_asc", "price_desc", "rating_desc", "most_reviewed" ], "default": "relevance" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, { "name": "country", "in": "query", "required": false, "description": "Marketplace country hint (example: sg).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Localization language. Defaults to en.", "schema": { "type": "string", "enum": [ "en", "th", "id", "ms", "vi", "tl" ], "default": "en" } }, { "name": "include_intent", "in": "query", "required": false, "description": "Include lightweight parsed query intent metadata.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit (1..100). Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (0..10000). Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "public_search_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_search", "summary": "Search Public Merchant Products", "description": "Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.", "tags": [ "public-agent" ], "security": [], "parameters": [ { "name": "currency", "in": "query", "required": false, "description": "ISO currency code. Required for price ranges and price sorting; no cross-currency ranking or conversion.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "min_rating", "in": "query", "required": false, "description": "Minimum average imported product review rating. Unrated products do not match; not a marketplace-wide lifetime rating.", "schema": { "type": "number", "minimum": 1, "maximum": 5 } }, { "name": "min_review_count", "in": "query", "required": false, "description": "Minimum number of imported rated product reviews.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "added_after", "in": "query", "required": false, "description": "Inclusive catalog creation timestamp with time zone. Does not mean product release date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "variant_options", "in": "query", "required": false, "description": "JSON array of 1-5 exact, case-insensitive option pairs, e.g. [{\"name\":\"Color\",\"value\":\"Red\"}]. All options must match the same variant.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Natural-language search query.", "schema": { "type": "string", "maxLength": 300 } }, { "name": "category", "in": "query", "required": false, "description": "Optional category-name filter.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "brand", "in": "query", "required": false, "description": "Optional brand filter.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum catalogPrice in the requested currency (inclusive). Requires currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum catalogPrice in the requested currency (inclusive). Requires currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "in_stock", "in": "query", "required": false, "description": "Filter by stock availability.", "schema": { "type": "boolean" } }, { "name": "merchant_ids", "in": "query", "required": false, "description": "Comma-separated merchant IDs to scope the search.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by relevance, newest catalog addition, catalog price, imported average rating, or review count. Price sorting requires currency; most_reviewed is not best selling.", "schema": { "type": "string", "enum": [ "relevance", "newest", "price_asc", "price_desc", "rating_desc", "most_reviewed" ], "default": "relevance" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] } }, { "name": "country", "in": "query", "required": false, "description": "Marketplace country hint (example: sg).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Localization language. Defaults to en.", "schema": { "type": "string", "enum": [ "en", "th", "id", "ms", "vi", "tl" ], "default": "en" } }, { "name": "include_intent", "in": "query", "required": false, "description": "Include lightweight parsed query intent metadata.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Result limit (1..100). Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (0..10000). Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "public_search_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/settlements": { "get": { "operationId": "get_v1_settlements", "summary": "List Settlements", "description": "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.", "tags": [ "settlements" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "marketplace", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "orderId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "externalOrderId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_settlements", "summary": "Apply Settlements", "description": "Apply marketplace-agnostic settlement lines to existing orders.\n\n### Authentication\n\nRequires `orders:write`.\n\n### What this endpoint does\n\n- Stores every submitted line as marketplace financial evidence.\n- Projects **settled** rows into the order finance ledger.\n- Keeps pending, reversed, and voided rows as evidence only, removing any earlier developer API ledger projection for the same `sourceEventKey`.\n- Recomputes Payment received when a marketplace-specific formula exists. Zalora is currently supported.\n\n### Order matching\n\nOrders are matched by organization, marketplace platform, and exact `externalOrderId`. Include `externalOrderItemId` when an order has multiple lines.\n\n- `accountId` is an exact store match, never a wildcard.\n- `marketplace=zalora` can match Zalora Seller Center orders (`platform=zalora`) and reconciliation-era agentic carts.\n- If the same `externalOrderId` exists in both groups, the line is ambiguous. Pass `accountId` to disambiguate it.\n- Ledger rows retain the platform of the matched order.\n\n### Zalora ITR parity\n\n- Send one `lines[]` entry per report row. `transactionType` can represent Commission, Item Price Credit, ZAP Commitments, Payment Gateway Fee, shipping, penalties, or credits.\n- `settlementStatus=settled` is paid; `pending` is not.\n- Payment received is calculated from Item Price Credit − ZAP − Commission ledger entries. Payment gateway, shipping, and penalty entries still post to P&L when settled but are excluded from that formula.\n- Item Price Credit updates Payment received without changing line `paidPrice` or `unitPrice`. Use `PATCH /api/v1/orders/{orderId}` when displayed prices must also change.\n\n### Important limitations\n\nThis is not an order-price API. Selling prices, COGS, and returns belong on `POST /api/v1/orders` or `PATCH /api/v1/orders/{orderId}`. Do not send `paymentReceived`.\n\nThis endpoint does not replace ITR apply for:\n\n- Spreadsheet parsing\n- Updating `paidPrice` or `unitPrice`\n- Automatically marking returned or cancelled lines and restoring return inventory\n- SKU fallback matching\n- Rewriting order currency or totals\n- Rebasing COGS currency\n- Undo or redo\n\nDo not apply the same fee lines through both this API and the Zalora Item Transaction Report tool. Their `source_event_key` namespaces differ (`developer_api:…` and `zalora_report:…`), so Payment received would be counted twice.", "tags": [ "settlements" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "marketplace", "lines" ], "properties": { "organizationId": { "type": "string", "maxLength": 120, "description": "Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations." }, "marketplace": { "type": "string", "minLength": 2, "maxLength": 32, "description": "Settlement source marketplace slug (zalora, shopee, lazada, tiktok, shopify, agentic, …). Used to match orders and pick a payment-received formula. `zalora` matches both Seller Center orders (`platform=zalora`) and reconciliation-era agentic carts." }, "accountId": { "type": "string", "maxLength": 160, "description": "Exact store/account id. Never a wildcard. Omit only when org + marketplace + externalOrderId already identifies one order." }, "lines": { "type": "array", "minItems": 1, "maxItems": 200, "description": "Settlement lines. Plural even for one target. Each line is one fee/credit/reversal, not a net paymentReceived.", "items": { "type": "object", "additionalProperties": false, "required": [ "externalOrderId", "amount", "currency", "settlementStatus" ], "properties": { "externalOrderId": { "type": "string", "maxLength": 160, "description": "Exact order identifier stored on the Omni order." }, "externalOrderItemId": { "type": "string", "maxLength": 160, "description": "Required when the order has more than one line. Exact marketplace/item id." }, "sourceEventKey": { "type": "string", "maxLength": 240, "description": "Optional idempotency key. Omni namespaces it under developer_api:{marketplace}:…" }, "externalTransactionId": { "type": "string", "maxLength": 240, "description": "Marketplace transaction number used to derive sourceEventKey when omitted." }, "transactionType": { "type": "string", "maxLength": 160, "description": "Source label (e.g. Commission). Used to derive feeType when feeType is omitted." }, "feeType": { "type": "string", "maxLength": 160, "description": "Stored ledger fee_type. Prefer this when you already have a sanitized key." }, "amount": { "type": "number", "description": "Non-zero signed amount in line currency. Positive is seller credit unless direction is set." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217. Must match the order/line currency." }, "direction": { "type": "string", "enum": [ "credit", "debit" ], "description": "Optional. When omitted, a negative amount is debit and a positive amount is credit." }, "settlementStatus": { "type": "string", "enum": [ "estimated", "pending", "settled", "reversed", "voided" ], "description": "Only settled rows project into the finance ledger. Other statuses remain evidence." }, "occurredAt": { "type": "string", "format": "date-time" }, "settlementReference": { "type": "string", "maxLength": 240 }, "payoutReference": { "type": "string", "maxLength": 240 } } } } } }, "examples": { "zaloraCommission": { "summary": "Zalora settled commission on an agentic order line", "value": { "organizationId": "org_123", "marketplace": "zalora", "lines": [ { "externalOrderId": "MY-213127917", "externalOrderItemId": "11476389", "transactionType": "Commission", "amount": -12.5, "currency": "MYR", "settlementStatus": "settled" } ] } }, "shopeePending": { "summary": "Shopee pending fee (evidence only)", "value": { "marketplace": "shopee", "accountId": "shop-1", "lines": [ { "externalOrderId": "SO-1001", "externalOrderItemId": "ITEM-1", "feeType": "commission", "amount": -3.2, "currency": "SGD", "settlementStatus": "pending", "externalTransactionId": "ESC-99" } ] } } } } } }, "responses": { "200": { "description": "Batch accepted. Top-level success is true only when every requested line succeeds; partial failures remain in data.results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "operationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every requested line succeeds." }, "marketplace": { "type": "string" }, "sourceEventKeys": { "type": "array", "items": { "type": "string" } }, "succeededCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "evidenceUpserted": { "type": "integer" }, "ledgerProjected": { "type": "integer" }, "ledgerUnprojected": { "type": "integer" }, "paymentReceivedRecomputed": { "type": "boolean" }, "paymentReceivedFormulaId": { "type": [ "string", "null" ], "description": "Set when a marketplace formula exists (zalora_payment_received_v1 today)." }, "orderIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "sourceEventKey": { "type": "string" }, "externalOrderId": { "type": "string" }, "externalOrderItemId": { "type": [ "string", "null" ] }, "orderId": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "feeType": { "type": [ "string", "null" ] }, "settlementStatus": { "type": "string", "enum": [ "estimated", "pending", "settled", "reversed", "voided" ] }, "projected": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } } } }, "400": { "description": "Bad Request — invalid payload" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or missing `orders:write` scope" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/settlements/{settlementId}": { "get": { "operationId": "get_v1_settlements_by_settlementid", "summary": "Get Settlement", "description": "Get the latest normalized settlement snapshot by stable settlement ID. Requires `settlements:read`.", "tags": [ "settlements" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "settlementId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "404": { "description": "Settlement not found." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/sync": { "post": { "operationId": "post_v1_sync", "summary": "Sync Product Commercial Fields", "description": "Update price, sale price, or stock quantity in OmniCommerce and queue marketplace sync workers where applicable.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/threads/{thread_id}/status": { "get": { "operationId": "get_v1_threads_by_thread_id_status", "summary": "Get Thread Status", "description": "Poll an AOP execution started by `POST /api/v1/aop/{aopId}/execute`. Requires `aops:read`. Status values are `running`, `completed`, or `failed`.", "tags": [ "aops" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include_messages", "in": "query", "required": false, "description": "When true, include conversation messages while the run is still in progress. Terminal runs include messages by default.", "schema": { "type": "boolean" } }, { "name": "organizationId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120, "description": "Required for session auth. Optional for API keys." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "thread_id", "status", "created_at", "updated_at", "conversation_asset" ], "properties": { "thread_id": { "type": "string" }, "status": { "type": "string", "description": "running, completed, or failed." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "conversation_asset": { "type": [ "object", "null" ], "additionalProperties": true } } } } } }, "400": { "description": "Invalid AOP configuration or request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" }, "403": { "description": "Forbidden. Missing OAuth scope." }, "404": { "description": "AOP or thread not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/webhook-events": { "get": { "operationId": "get_v1_webhook_events", "summary": "List Webhook Events", "description": "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.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "eventType", "in": "query", "required": false, "description": "Repeat or comma-separate supported webhook event keys.", "schema": { "type": "string" } }, { "name": "occurredSince", "in": "query", "required": false, "description": "Inclusive event occurrence lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the preceding page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/webhooks": { "get": { "operationId": "get_v1_webhooks", "summary": "List Developer Webhooks", "description": "List configured developer webhook subscriptions for the authenticated organization.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string", "default": "developer_v1" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient Credits" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } }, "post": { "operationId": "post_v1_webhooks", "summary": "Create Developer Webhook", "description": "Create a developer webhook subscription for the authenticated organization. The signing secret is returned only once.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "organizationId": { "type": "string", "description": "Optional for API-key requests and otherwise resolved by authentication." }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTP(S) callback URL." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "product.created", "product.updated", "product.deleted", "product.delisted", "product.price.changed", "product.inventory.changed", "product.enrichment.started", "product.enrichment.completed", "order.created", "order.updated", "order.deleted", "order.status.changed", "look.created", "look.deleted", "review.created", "review.updated", "review.status.changed", "settlement.created", "settlement.updated", "settlement.status.changed", "return.created", "return.updated", "return.status.changed", "account_statement.created", "account_statement.updated", "account_statement.status.changed", "account_statement.reconciliation.changed", "account_statement.transactions.synced", "account_statement.transactions.failed", "account_statement.sync.queued", "account_statement.sync.started", "account_statement.sync.completed", "account_statement.sync.failed", "account_statement.sync.unavailable" ] } }, "description": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Subscription created. The response contains the one-time signing secret." }, "400": { "description": "Invalid event, URL, or request payload." }, "401": { "description": "Unauthorized." }, "403": { "description": "Missing webhooks:manage scope." }, "500": { "description": "Internal server error." } } } }, "/api/v1/zalora/import": { "post": { "operationId": "post_v1_zalora_import", "summary": "Import Selected Zalora Products", "description": "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.\n\nReturns 202 with links.job for optional status checks and retrieval of Omni product IDs. Only one import may run per store at a time. This endpoint does not invoke an AOP, enrich products, or publish listings.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "productSetIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Zalora productSetIds to import. Values are trimmed and de-duplicated while preserving order." }, "storeId": { "description": "Connected Zalora store/account ID. Omit when the organization has exactly one Zalora store or one default Zalora store.", "type": "string", "minLength": 1, "maxLength": 255 }, "organizationId": { "description": "Required for session auth; derived from the credential for bearer auth.", "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "productSetIds" ], "additionalProperties": false }, "example": { "productSetIds": [ "1001", "1002" ], "storeId": "zalora-store-id" } } } }, "responses": { "202": { "description": "Jobs accepted for background processing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "status", "jobId", "data", "links" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted" ] }, "jobId": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "required": [ "success", "queued", "productSetIds", "jobIds", "succeededCount", "failedCount", "results" ], "properties": { "success": { "type": "boolean", "description": "True when all requested targets were accepted for processing. Does not mean processing completed." }, "queued": { "type": "boolean" }, "productSetIds": { "type": "array", "items": { "type": "string" } }, "jobIds": { "type": "array", "items": { "type": "string" } }, "succeededCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "storeId": { "type": "string" }, "correlations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "results": { "type": "array", "items": { "type": "object", "required": [ "productSetId", "success", "jobId" ], "properties": { "productSetId": { "type": "string" }, "success": { "type": "boolean" }, "jobId": { "type": "string" } } } } } } } } } } }, "400": { "description": "Invalid request or queue preparation failed. Inspect the error before resubmitting." }, "401": { "description": "Missing or invalid credentials." }, "403": { "description": "Missing scope, insufficient permission, organization mismatch, or inactive organization." }, "404": { "description": "Target not found in the authenticated organization." }, "409": { "description": "An import or enrichment job is already active for the target." }, "429": { "description": "Rate limit exceeded." } } }, "get": { "operationId": "get_v1_zalora_import", "summary": "Get Selected Zalora Import Status", "description": "Requires catalog:read. Follow the unchanged links.job URL returned by POST. Reads current state once without waiting.\n\n### Completion\n\ndata.status is pending, running, success, or error; data.terminal and data.success identify completion. data.productIds contains mapped Omni IDs for the supplied product sets. Failed imports remain explicit, including missingExternalIds. The top-level completed status describes this status request, not the import.\n\nKeep the original target IDs: the status lookup resolves those targets and does not prove that a modified selection was part of this job.", "tags": [ "developer-platform" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Required for session auth; derived from the credential for bearer auth.", "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "jobId", "in": "query", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "storeId", "in": "query", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "productSetIds", "in": "query", "required": true, "style": "form", "explode": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Zalora productSetIds to import. Values are trimmed and de-duplicated while preserving order." } } ], "responses": { "200": { "description": "Current import state; inspect data.terminal and data.success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "status", "jobId", "data", "links" ], "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "jobId": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "required": [ "id", "status", "terminal", "success", "productIds" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "zalora_import" ] }, "status": { "type": "string", "enum": [ "pending", "running", "success", "error" ] }, "terminal": { "type": "boolean" }, "success": { "type": "boolean" }, "productIds": { "type": "array", "items": { "type": "string" } }, "externalIds": { "type": "array", "items": { "type": "string" } }, "missingExternalIds": { "type": "array", "items": { "type": "string" } }, "storeId": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request or queue preparation failed. Inspect the error before resubmitting." }, "401": { "description": "Missing or invalid credentials." }, "403": { "description": "Missing scope, insufficient permission, organization mismatch, or inactive organization." }, "404": { "description": "Target not found in the authenticated organization." }, "409": { "description": "An import or enrichment job is already active for the target." }, "429": { "description": "Rate limit exceeded." } } } }, "/ucp/v1/checkout-sessions": { "post": { "operationId": "post_ucp_v1_checkout_sessions", "summary": "Create UCP Checkout Session", "description": "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`.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries.", "schema": { "type": "string", "maxLength": 180 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "line_items" ], "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "payment": { "type": "object", "additionalProperties": true }, "payment_rail": { "type": "string", "enum": [ "acp_stripe", "x402" ], "default": "acp_stripe" }, "metadata": { "type": "object", "additionalProperties": true } } }, "example": { "line_items": [ { "item": { "id": "00000000-0000-4000-8000-000000000001" }, "quantity": 1 } ], "buyer": { "email": "buyer@example.com" }, "payment_rail": "acp_stripe" } } } }, "responses": { "201": { "description": "UCP checkout session created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ucp": { "type": "object", "additionalProperties": true }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "409": { "description": "Insufficient inventory" }, "500": { "description": "Internal Server Error" } } } }, "/ucp/v1/checkout-sessions/{sessionId}": { "get": { "operationId": "get_ucp_v1_checkout_sessions_by_sessionid", "summary": "Get UCP Checkout Session", "description": "Fetch the current UCP checkout resource for a native agentic checkout session. Requires `UCP-Agent` and bearer authentication.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "UCP checkout session found.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "operationId": "patch_ucp_v1_checkout_sessions_by_sessionid", "summary": "Update UCP Checkout Session", "description": "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`.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "payment": { "type": "object", "additionalProperties": true }, "payment_rail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "UCP checkout session updated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal session or insufficient inventory" }, "500": { "description": "Internal Server Error" } } }, "put": { "operationId": "put_ucp_v1_checkout_sessions_by_sessionid", "summary": "Replace UCP Checkout Session Fields", "description": "UCP-compatible update method. Current behavior matches PATCH: provided fields are applied and omitted fields remain unchanged. Requires `UCP-Agent` and OAuth `checkout:write`.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "payment": { "type": "object", "additionalProperties": true }, "payment_rail": { "type": "string", "enum": [ "acp_stripe", "x402" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "UCP checkout session updated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal session or insufficient inventory" }, "500": { "description": "Internal Server Error" } } } }, "/ucp/v1/checkout-sessions/{sessionId}/cancel": { "post": { "operationId": "post_ucp_v1_checkout_sessions_by_sessionid_cancel", "summary": "Cancel UCP Checkout Session", "description": "Cancel a ready-for-payment UCP checkout session and release reserved inventory. Requires `UCP-Agent` and OAuth `checkout:write`.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "UCP checkout session cancelled.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal checkout session" }, "500": { "description": "Internal Server Error" } } } }, "/ucp/v1/checkout-sessions/{sessionId}/complete": { "post": { "operationId": "post_ucp_v1_checkout_sessions_by_sessionid_complete", "summary": "Complete UCP Checkout Session", "description": "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`.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries.", "schema": { "type": "string", "maxLength": 180 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "idempotency_key": { "type": "string", "maxLength": 180 }, "paymentProof": { "type": "object", "additionalProperties": true }, "payment": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Checkout completed and native order created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Settlement failed; the checkout remains ready for payment.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "status", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "OmniCommerce product UUID.", "maxLength": 160 }, "title": { "type": "string" }, "price": { "type": "integer" }, "image_url": { "type": "string" } } }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "buyer": { "type": "object", "additionalProperties": true }, "fulfillment": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "ready_for_complete", "completed", "canceled" ] }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payment": { "type": "object", "additionalProperties": true }, "order": { "type": "object", "additionalProperties": true }, "settlement": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Checkout session not found" }, "409": { "description": "Terminal or expired checkout session" }, "500": { "description": "Internal Server Error" } } } }, "/ucp/v1/orders/{orderId}": { "get": { "operationId": "get_ucp_v1_orders_by_orderid", "summary": "Get UCP Order", "description": "Fetch the native OmniCommerce order created by a completed UCP checkout session. Only `agentic` orders are exposed through this facade.", "tags": [ "ucp" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "UCP-Agent", "in": "header", "required": true, "description": "UCP agent identity, for example `agent.example/1.0`.", "schema": { "type": "string", "maxLength": 240 } }, { "name": "organizationId", "in": "query", "required": false, "description": "Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "UCP order found.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "ucp", "id", "line_items", "currency", "totals" ], "properties": { "ucp": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "label": { "type": "string" }, "checkout_id": { "type": "string" }, "permalink_url": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "fulfillment": { "type": "object", "additionalProperties": true }, "currency": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden or checkout not enabled" }, "404": { "description": "Order not found" }, "500": { "description": "Internal Server Error" } } } } }, "webhooks": { "productCreated": { "post": { "operationId": "product_created_webhook", "summary": "Product created", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "product webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.created" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productUpdated": { "post": { "operationId": "product_updated_webhook", "summary": "Product updated", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "product webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.updated" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productDeleted": { "post": { "operationId": "product_deleted_webhook", "summary": "Product deleted", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "product webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.deleted" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDeletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productDelisted": { "post": { "operationId": "product_delisted_webhook", "summary": "Product delisted", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "product webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.delisted" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDelistedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productPriceChanged": { "post": { "operationId": "product_price_changed_webhook", "summary": "Product price changed", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "product webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.price.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPriceChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productInventoryChanged": { "post": { "operationId": "product_inventory_changed_webhook", "summary": "Product inventory changed", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "product webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.inventory.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInventoryChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productEnrichmentStarted": { "post": { "operationId": "product_enrichment_started_webhook", "summary": "Product enrichment started", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "enrichment webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.enrichment.started" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEnrichmentStartedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "productEnrichmentCompleted": { "post": { "operationId": "product_enrichment_completed_webhook", "summary": "Product enrichment completed", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "enrichment webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "product.enrichment.completed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEnrichmentCompletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "lookCreated": { "post": { "operationId": "look_created_webhook", "summary": "Look created", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "look webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "look.created" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookCreatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "lookDeleted": { "post": { "operationId": "look_deleted_webhook", "summary": "Look deleted", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "look webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "look.deleted" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookDeletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "reviewCreated": { "post": { "operationId": "review_created_webhook", "summary": "Review created", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "review webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "review.created" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCreatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "reviewUpdated": { "post": { "operationId": "review_updated_webhook", "summary": "Review updated", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "review webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "review.updated" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewUpdatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "reviewStatusChanged": { "post": { "operationId": "review_status_changed_webhook", "summary": "Review status changed", "description": "OmniCommerce sends this event after the corresponding workspace resource changes. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id.", "tags": [ "review webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "review.status.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "orderCreated": { "post": { "operationId": "order_created_webhook", "summary": "Order created", "description": "OmniCommerce sends this provider-neutral event after the complete order aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and use resourceVersion to reject stale updates.", "tags": [ "order webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "order.created" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "orderUpdated": { "post": { "operationId": "order_updated_webhook", "summary": "Order updated", "description": "OmniCommerce sends this provider-neutral event after the complete order aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and use resourceVersion to reject stale updates.", "tags": [ "order webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "order.updated" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "orderStatusChanged": { "post": { "operationId": "order_status_changed_webhook", "summary": "Order status changed", "description": "OmniCommerce sends this provider-neutral event after the complete order aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and use resourceVersion to reject stale updates.", "tags": [ "order webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "order.status.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "orderDeleted": { "post": { "operationId": "order_deleted_webhook", "summary": "Order deleted", "description": "OmniCommerce sends this provider-neutral event after the complete order aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and use resourceVersion to reject stale updates.", "tags": [ "order webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "order.deleted" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDeletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "settlementCreated": { "post": { "operationId": "settlement_created_webhook", "summary": "Settlement created", "description": "OmniCommerce sends this provider-neutral event after marketplace finance evidence is normalized and the order settlement aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and reject stale resourceVersion values.", "tags": [ "settlement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "settlement.created" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementCreatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "settlementUpdated": { "post": { "operationId": "settlement_updated_webhook", "summary": "Settlement updated", "description": "OmniCommerce sends this provider-neutral event after marketplace finance evidence is normalized and the order settlement aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and reject stale resourceVersion values.", "tags": [ "settlement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "settlement.updated" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementUpdatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "settlementStatusChanged": { "post": { "operationId": "settlement_status_changed_webhook", "summary": "Settlement status changed", "description": "OmniCommerce sends this provider-neutral event after marketplace finance evidence is normalized and the order settlement aggregate is committed. Return any 2xx response after durably accepting it. Deliveries can be retried, so deduplicate with X-Omni-Event-Id and reject stale resourceVersion values.", "tags": [ "settlement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "settlement.status.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "returnCreated": { "post": { "operationId": "receiveReturnCreatedWebhookEvent", "summary": "Return Created", "description": "Sent after a normalized return and its SKU-level lines first commit.", "tags": [ "return webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "description": "Stable event id and recipient idempotency key.", "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 over timestamp.rawBody.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnCreatedWebhookEvent" } } } }, "responses": { "200": { "description": "Event durably accepted." }, "204": { "description": "Event durably accepted with no response body." } } } }, "returnUpdated": { "post": { "operationId": "receiveReturnUpdatedWebhookEvent", "summary": "Return Updated", "description": "Sent when normalized return amounts, identifiers, or line data change without a canonical status transition.", "tags": [ "return webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "description": "Stable event id and recipient idempotency key.", "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 over timestamp.rawBody.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnUpdatedWebhookEvent" } } } }, "responses": { "200": { "description": "Event durably accepted." }, "204": { "description": "Event durably accepted with no response body." } } } }, "returnStatusChanged": { "post": { "operationId": "receiveReturnStatusChangedWebhookEvent", "summary": "Return Status Changed", "description": "Sent when the provider-neutral return status changes.", "tags": [ "return webhooks" ], "security": [], "x-hidden": true, "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "description": "Stable event id and recipient idempotency key.", "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 over timestamp.rawBody.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnStatusChangedWebhookEvent" } } } }, "responses": { "200": { "description": "Event durably accepted." }, "204": { "description": "Event durably accepted with no response body." } } } }, "accountStatementCreated": { "post": { "operationId": "account_statement_created_webhook", "summary": "Account statement created", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.created" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementCreatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementUpdated": { "post": { "operationId": "account_statement_updated_webhook", "summary": "Account statement updated", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.updated" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementUpdatedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementStatusChanged": { "post": { "operationId": "account_statement_status_changed_webhook", "summary": "Account statement payment status changed", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.status.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementReconciliationChanged": { "post": { "operationId": "account_statement_reconciliation_changed_webhook", "summary": "Account statement reconciliation changed", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.reconciliation.changed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementReconciliationChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementTransactionsSynced": { "post": { "operationId": "account_statement_transactions_synced_webhook", "summary": "Account statement transactions refreshed", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.transactions.synced" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementTransactionsSyncedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementTransactionsFailed": { "post": { "operationId": "account_statement_transactions_failed_webhook", "summary": "Account statement transaction refresh failed", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.transactions.failed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementTransactionsFailedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementSyncQueued": { "post": { "operationId": "account_statement_sync_queued_webhook", "summary": "Account statement sync queued", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.sync.queued" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementSyncQueuedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementSyncStarted": { "post": { "operationId": "account_statement_sync_started_webhook", "summary": "Account statement sync started", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.sync.started" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementSyncStartedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementSyncCompleted": { "post": { "operationId": "account_statement_sync_completed_webhook", "summary": "Account statement sync completed", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.sync.completed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementSyncCompletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementSyncFailed": { "post": { "operationId": "account_statement_sync_failed_webhook", "summary": "Account statement sync failed", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.sync.failed" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementSyncFailedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } }, "accountStatementSyncUnavailable": { "post": { "operationId": "account_statement_sync_unavailable_webhook", "summary": "Account statement sync unavailable", "description": "Emitted from committed, organization- and store-scoped Account Statements state across all supported marketplaces. Amounts are decimal strings in the statement currency. Shopee released income is wallet income, not evidence of a bank withdrawal. Accept durably with 2xx and deduplicate X-Omni-Event-Id; resourceVersion orders each statement or sync run.", "tags": [ "account statement webhooks" ], "x-hidden": true, "security": [], "parameters": [ { "name": "X-Omni-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "account_statement.sync.unavailable" } }, { "name": "X-Omni-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Omni-Signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{rawBody}` using the subscription secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatementSyncUnavailableWebhookEvent" } } } }, "responses": { "2XX": { "description": "Event accepted." } } } } }, "components": { "schemas": { "ProductCountryCode": { "type": "string", "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "aq", "ar", "as", "at", "au", "aw", "ax", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bl", "bm", "bn", "bo", "bq", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv", "cw", "cx", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "eh", "er", "es", "et", "fi", "fj", "fk", "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gs", "gt", "gu", "gw", "gy", "hk", "hm", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in", "io", "iq", "ir", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "ki", "km", "kn", "kp", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li", "lk", "lr", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me", "mf", "mg", "mh", "mk", "ml", "mm", "mn", "mo", "mp", "mq", "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "nf", "ng", "ni", "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pm", "pn", "pr", "ps", "pt", "pw", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "sd", "se", "sg", "sh", "si", "sj", "sk", "sl", "sm", "sn", "so", "sr", "ss", "st", "sv", "sx", "sy", "sz", "tc", "td", "tf", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr", "tt", "tv", "tw", "tz", "ua", "ug", "um", "us", "uy", "uz", "va", "vc", "ve", "vg", "vi", "vn", "vu", "wf", "ws", "ye", "yt", "za", "zm", "zw" ], "description": "ISO 3166-1 alpha-2 country code, for example sg or my. Codes are trimmed and normalized to lowercase. Country names, custom values, and global are rejected. Select the country for the connected store explicitly." }, "ZaloraProductCountry": { "type": "string", "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "aq", "ar", "as", "at", "au", "aw", "ax", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bl", "bm", "bn", "bo", "bq", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv", "cw", "cx", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "eh", "er", "es", "et", "fi", "fj", "fk", "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gs", "gt", "gu", "gw", "gy", "hk", "hm", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in", "io", "iq", "ir", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "ki", "km", "kn", "kp", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li", "lk", "lr", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me", "mf", "mg", "mh", "mk", "ml", "mm", "mn", "mo", "mp", "mq", "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "nf", "ng", "ni", "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pm", "pn", "pr", "ps", "pt", "pw", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "sd", "se", "sg", "sh", "si", "sj", "sk", "sl", "sm", "sn", "so", "sr", "ss", "st", "sv", "sx", "sy", "sz", "tc", "td", "tf", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr", "tt", "tv", "tw", "tz", "ua", "ug", "um", "us", "uy", "uz", "va", "vc", "ve", "vg", "vi", "vn", "vu", "wf", "ws", "ye", "yt", "za", "zm", "zw", "global" ], "description": "Country code or the global connection region for a Zalora Global Seller Center store. This exception applies only to marketplaces.zalora.country; targetCountries continues to require ISO country codes." }, "CampaignPlan": { "type": "object", "properties": { "brief": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "objective": { "default": "", "type": "string", "maxLength": 8000 }, "brand": { "default": "", "type": "string", "maxLength": 160 }, "ownerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "approverId": { "type": "string", "minLength": 1, "maxLength": 160 }, "timezone": { "type": "string" }, "stores": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "marketplace", "country", "storeId" ], "additionalProperties": false } }, "serviceRequest": { "default": "", "type": "string", "maxLength": 300 }, "priority": { "default": "standard", "type": "string", "enum": [ "standard", "priority", "super_priority" ] }, "documentIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "reviewDueAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sourceCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceMarketplace": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "sourceCountry": { "type": "string", "maxLength": 80 }, "cleanupNotes": { "default": "", "type": "string", "maxLength": 8000 } }, "required": [ "name", "ownerId", "approverId", "timezone" ], "additionalProperties": false }, "windows": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "preparesAt": { "default": null, "description": "Preparation time: publish promotions with the future live start/end. Must be at or before startsAt.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "reviewNotes": { "default": "", "type": "string", "maxLength": 8000 } }, "required": [ "id", "name", "startsAt", "endsAt" ], "additionalProperties": false } }, "offers": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "windowId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotionId": { "description": "Existing draft promotion attached to this window; the campaign controls its live dates.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "promotion": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "kind": { "description": "Canonical OmniCommerce promotion mechanic: product discount, flash sale, voucher, gift with purchase, Buy-X-Get-Y, bundle deal, or Lazada-only free shipping and early bird price.", "type": "string", "enum": [ "product_discount", "flash_sale", "voucher", "gift_with_purchase", "buy_x_get_y", "bundle_deal", "free_shipping", "early_bird_price" ] }, "salesChannels": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "pdp", "live" ] } }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0 }, "storeDiscounts": { "description": "Patch discount terms for exact target store keys; unnamed stores remain unchanged. Null discountValue restores shared campaign terms for that store.", "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "storeKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "storeKey", "discountType", "discountValue" ], "additionalProperties": false } }, "targetStores": { "description": "Up to 100 connected stores for create (required) or update. Copy marketplace, country, and storeId from get_promotions targetStores or find_products marketplaceDetails. Do not concatenate a storeKeys string.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify", "amazon", "zalora", "ebay" ] }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "storeId": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "marketplace", "country", "storeId" ], "additionalProperties": false } }, "minSalePrice": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "maxDiscountAmount": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minSpend": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "voucherCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "claimStartsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "totalUsageLimit": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "perBuyerLimit": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "mechanicConfig": { "type": "object", "properties": { "voucherType": { "description": "Voucher subtype from get_promotions capabilities.voucherTypes. Browser AOP types (delivery=browser_aop) are writable Seller Center vouchers. Omit browserAutomation.aopId to use the built-in marketplace AOP.", "anyOf": [ { "type": "string", "enum": [ "shopee_shop", "shopee_product", "shopee_private", "shopee_live", "shopee_video", "shopee_new_buyer", "shopee_repeat_buyer", "shopee_campaign", "shopee_follow_prize", "shopee_exclusive_streamer", "shopee_welcome", "shopee_member_repeat_buyer", "shopee_exclusive", "shopee_redemption", "shopee_exclusive_creator", "lazada_store_follower", "lazada_regular", "lazada_store_new_buyer", "lazada_live", "lazada_offline", "lazada_co_funded", "lazada_welcome", "lazada_linked_member", "lazada_new_member", "lazada_member_exclusive", "lazada_points_redeemable", "tiktok_seller_coupon", "shopify_discount_code", "amazon_promotion_code", "zalora_seller_voucher", "ebay_coded_coupon" ] }, { "type": "null" } ] }, "voucherCampaign": { "description": "Campaign voucher targeting: exact campaignId/sessionId from Seller Center and termsAccepted only after the seller reviewed participation obligations. Required for shopee_campaign; nomination creates a draft awaiting marketplace review.", "type": "object", "properties": { "campaignId": { "type": "string", "pattern": "^[1-9]\\d{0,39}$" }, "sessionId": { "type": "string", "pattern": "^[1-9]\\d{0,39}$" }, "termsAccepted": { "type": "boolean" } }, "required": [ "campaignId", "sessionId", "termsAccepted" ], "additionalProperties": false }, "browserAutomation": { "anyOf": [ { "type": "object", "properties": { "aopId": { "type": "string", "minLength": 1, "maxLength": 160 }, "variableValues": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 160 }, "additionalProperties": { "type": "string", "maxLength": 8000 } }, "instructions": { "type": "string", "maxLength": 8000 } }, "additionalProperties": false }, { "type": "null" } ] }, "voucherScope": { "description": "shop = all products, products = selected assigned products. Repeat Buyer defaults to shop.", "type": "string", "enum": [ "products", "shop" ] }, "voucherReward": { "description": "Seller Center reward type. coins_cashback is a percentage greater than 3 and does not reduce salePrice.", "type": "string", "enum": [ "discount", "coins_cashback" ] }, "voucherAudience": { "type": "string", "enum": [ "general", "shop_follow" ] }, "repeatPurchaseMinCount": { "description": "Shopee Repeat Buyer: minimum completed shop orders, 1 or 2. Required for shopee_repeat_buyer.", "type": "integer", "minimum": 1, "maximum": 999 }, "repeatPurchaseLookbackDays": { "description": "Shopee Repeat Buyer: lookback window in days, one of 30, 90, 180 or 365. Required for shopee_repeat_buyer.", "type": "integer", "minimum": 1, "maximum": 365 }, "smartVoucher": { "description": "Shopee Smart Voucher toggle. Used by New Buyer and similar portal types.", "type": "boolean" }, "followPrizeExpiryDays": { "description": "Shopee Follow Prize: days after claim until expiry. Seller Center is 7.", "type": "integer", "minimum": 1, "maximum": 30 }, "videoDisplayMode": { "description": "Shopee Video display: shopee_video = all Shopee Video; creator_video = targeted creator videos only.", "type": "string", "enum": [ "shopee_video", "creator_video" ] }, "exclusiveCreatorUsernames": { "description": "Exclusive Creator Voucher: up to 15 Shopee usernames.", "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "exclusiveStreamerUsernames": { "description": "Exclusive Streamer Voucher: up to 15 Shopee usernames.", "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "voucherDisplayChannels": { "description": "Shopee display setting. [\"all\"] = display on all pages; [] = hidden/share by code.", "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "all", "feed", "live", "order_page", "followers", "offline" ] } }, "bundlePriceType": { "type": "string", "enum": [ "discount", "fixed_price" ] }, "bundleTiers": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "minimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "discountValue": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "minimumQuantity", "discountValue" ] } }, "thresholdType": { "type": "string", "enum": [ "item_quantity", "order_amount" ] }, "thresholdValue": { "type": "number", "exclusiveMinimum": 0 }, "giftType": { "type": "string", "enum": [ "gift", "sample" ] }, "giftQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "gifts": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "totalClaimLimit": { "type": "integer", "minimum": 1, "maximum": 99999 } }, "required": [ "productId", "totalClaimLimit" ], "additionalProperties": false } }, "buyQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "getQuantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "benefitProductIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "benefitType": { "type": "string", "enum": [ "free", "percentage", "fixed_amount" ] }, "benefitValue": { "type": "number", "minimum": 0 }, "maxApplicationsPerOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 999 }, "bundleMinimumQuantity": { "type": "integer", "minimum": 2, "maximum": 3000 }, "shippingDeliveryOption": { "description": "Free shipping delivery option. Lazada: STANDARD (default), ECONOMY, EXPRESS, SELLER_OWN_FLEET or P2P, as offered by the store.", "type": "string", "pattern": "^[A-Z0-9_]{1,40}$" }, "shippingBudget": { "description": "Free shipping: total shipping subsidy budget in the store currency. Omit for an unlimited budget.", "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false }, "productIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "reviewNotes": { "default": "", "type": "string", "maxLength": 8000 }, "excludedReason": { "default": "", "type": "string", "maxLength": 2000 }, "source": { "type": "object", "properties": { "sheet": { "type": "string", "maxLength": 160 }, "rows": { "maxItems": 10000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "headers": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "values": { "maxItems": 10000, "type": "array", "items": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 16000 } } } }, "required": [ "sheet", "rows", "headers", "values" ], "additionalProperties": false } }, "required": [ "id", "windowId", "promotion" ], "additionalProperties": false } } }, "required": [ "brief" ], "additionalProperties": false }, "ProductEnrichmentWebhookSnapshot": { "type": "object", "additionalProperties": false, "required": [ "jobId", "batchId", "workflow", "marketplace", "status" ], "properties": { "jobId": { "type": "string" }, "batchId": { "type": [ "string", "null" ] }, "workflow": { "type": "string", "enum": [ "listing_copy", "marketplace_taxonomy" ] }, "marketplace": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "pending_review", "applied" ] } } }, "ProductWebhookSnapshot": { "type": "object", "additionalProperties": true, "required": [ "id", "parentId", "type", "productFamilyId", "productFamilyName", "name", "description", "sku", "brand", "status", "price", "salePrice", "compareAtPrice", "costPrice", "costPriceCurrency", "mapPrice", "msrpPrice", "currency", "upc", "category", "tags", "inventory", "images", "variants", "variationSchema", "marketplaces", "promotions", "updatedAt", "createdAt" ], "properties": { "id": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "product", "variant" ] }, "productFamilyId": { "type": "string" }, "productFamilyName": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ], "description": "Catalog price in the legacy product event contract. Use currency with this value." }, "salePrice": { "type": [ "number", "null" ], "description": "Optional catalog sale price in the legacy product event contract." }, "compareAtPrice": { "type": [ "number", "null" ] }, "costPrice": { "type": [ "number", "null" ] }, "costPriceCurrency": { "type": [ "string", "null" ] }, "mapPrice": { "type": [ "number", "null" ] }, "msrpPrice": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "upc": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "inventory": { "type": "object", "additionalProperties": true, "properties": { "quantity": { "type": [ "number", "null" ] } } }, "images": { "type": "array", "items": {} }, "variants": { "type": "array", "items": {} }, "variationSchema": { "type": "object", "additionalProperties": true }, "marketplaces": { "type": "object", "additionalProperties": true }, "promotions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "LookProductWebhookSnapshot": { "type": "object", "additionalProperties": true, "required": [ "id", "name", "sku", "brand", "price", "currency", "imageUrl" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] } } }, "LookWebhookSnapshot": { "type": "object", "additionalProperties": true, "required": [ "id", "organizationId", "title", "status", "subject", "style", "season", "timeOfDay", "city", "additionalNotes", "stylePrompt", "heroImageTagId", "heroImageUrl", "createdBy", "createdAt", "updatedAt", "publishedAt", "productCount", "products" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "subject": { "type": [ "string", "null" ] }, "style": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "timeOfDay": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "additionalNotes": { "type": [ "string", "null" ] }, "stylePrompt": { "type": [ "string", "null" ] }, "heroImageTagId": { "type": [ "string", "null" ] }, "heroImageUrl": { "type": [ "string", "null" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "productCount": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/LookProductWebhookSnapshot" } } } }, "ReviewWebhookSnapshot": { "type": "object", "additionalProperties": false, "required": [ "id", "organizationId", "platform", "accountId", "productId", "orderId", "externalItemId", "externalReviewId", "externalOrderId", "kind", "status", "rating", "comment", "sellerReply", "canReply", "reviewedAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "platform": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "productId": { "type": [ "string", "null" ] }, "orderId": { "type": [ "string", "null" ] }, "externalItemId": { "type": [ "string", "null" ] }, "externalReviewId": { "type": "string" }, "externalOrderId": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "product_review", "solicitation" ] }, "status": { "type": "string", "enum": [ "open", "replied", "hidden", "handoff", "solicited", "ineligible" ] }, "rating": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ] }, "sellerReply": { "type": [ "string", "null" ] }, "canReply": { "type": "boolean" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductCreatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "product.created" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductWebhookSnapshot" } } } } }, "ProductUpdatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "product.updated" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductWebhookSnapshot" } } } } }, "ProductDeletedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "product.deleted" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductWebhookSnapshot" } } } } }, "ProductDelistedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "product.delisted" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductWebhookSnapshot" } } } } }, "ProductPriceChangedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "product.price.changed" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductWebhookSnapshot" } } } } }, "ProductInventoryChangedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "product.inventory.changed" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductWebhookSnapshot" } } } } }, "ProductEnrichmentStartedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "jobId", "batchId", "workflow", "marketplace", "status", "occurredAt", "data" ], "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string", "const": "product.enrichment.started" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "jobId": { "type": "string" }, "batchId": { "type": [ "string", "null" ] }, "workflow": { "type": "string", "enum": [ "listing_copy", "marketplace_taxonomy" ] }, "marketplace": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "pending_review", "applied" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ] }, "data": { "type": "object", "required": [ "enrichment" ], "properties": { "enrichment": { "$ref": "#/components/schemas/ProductEnrichmentWebhookSnapshot" } } } } }, "ProductEnrichmentCompletedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "productId", "jobId", "batchId", "workflow", "marketplace", "status", "occurredAt", "data" ], "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string", "const": "product.enrichment.completed" }, "organizationId": { "type": "string" }, "productId": { "type": "string" }, "jobId": { "type": "string" }, "batchId": { "type": [ "string", "null" ] }, "workflow": { "type": "string", "enum": [ "listing_copy", "marketplace_taxonomy" ] }, "marketplace": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "pending_review", "applied" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ] }, "data": { "type": "object", "required": [ "enrichment" ], "properties": { "enrichment": { "$ref": "#/components/schemas/ProductEnrichmentWebhookSnapshot" } } } } }, "LookCreatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "lookId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "look.created" }, "organizationId": { "type": "string" }, "lookId": { "type": "string" }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "look" ], "properties": { "look": { "$ref": "#/components/schemas/LookWebhookSnapshot" } } } } }, "LookDeletedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "lookId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "look.deleted" }, "organizationId": { "type": "string" }, "lookId": { "type": "string" }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "look" ], "properties": { "look": { "$ref": "#/components/schemas/LookWebhookSnapshot" } } } } }, "ReviewCreatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "reviewId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "review.created" }, "organizationId": { "type": "string" }, "reviewId": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "previousStatus": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "review" ], "properties": { "review": { "$ref": "#/components/schemas/ReviewWebhookSnapshot" } } } } }, "ReviewUpdatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "reviewId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "review.updated" }, "organizationId": { "type": "string" }, "reviewId": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "previousStatus": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "review" ], "properties": { "review": { "$ref": "#/components/schemas/ReviewWebhookSnapshot" } } } } }, "ReviewStatusChangedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "eventId", "eventType", "organizationId", "reviewId", "productId", "changedFields", "occurredAt", "data" ], "properties": { "eventId": { "type": "string", "description": "Stable event ID and recipient idempotency key." }, "eventType": { "type": "string", "const": "review.status.changed" }, "organizationId": { "type": "string" }, "reviewId": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "previousStatus": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ], "description": "Internal OmniCommerce workflow provenance when supplied." }, "data": { "type": "object", "additionalProperties": true, "required": [ "review" ], "properties": { "review": { "$ref": "#/components/schemas/ReviewWebhookSnapshot" } } } } }, "OrderWebhookInventory": { "type": "object", "required": [ "onHand", "locked", "available", "asOf" ], "properties": { "onHand": { "type": "integer", "minimum": 0 }, "locked": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 }, "asOf": { "type": "string", "format": "date-time" } }, "description": "Current OmniCommerce inventory captured with the order event, using the same stock authority as Inventory detail. Not a live marketplace stock read." }, "OrderWebhookItemIdentity": { "type": "object", "additionalProperties": true, "required": [ "id", "productId", "externalOrderItemId", "marketplaceItemId", "marketplaceVariantId", "sku", "sellerSku", "shopSku", "name", "status", "quantity" ], "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "externalOrderItemId": { "type": "string" }, "marketplaceItemId": { "type": [ "string", "null" ] }, "marketplaceVariantId": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "sellerSku": { "type": [ "string", "null" ] }, "shopSku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "minimum": 0 }, "inventory": { "oneOf": [ { "$ref": "#/components/schemas/OrderWebhookInventory" }, { "type": [ "null" ] } ], "default": null }, "inventoryUnavailableReason": { "type": [ "string", "null" ], "enum": [ "product_not_linked", "product_not_found", "variant_not_resolved", "inventory_unavailable", null ], "default": null } } }, "WebhookMoney": { "type": "object", "additionalProperties": true, "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "description": "Decimal monetary amount encoded as a JSON string." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code." } } }, "OrderWebhookSource": { "type": "object", "additionalProperties": true, "required": [ "system", "marketplace", "accountId", "providerEventId", "providerEventType" ], "properties": { "system": { "type": "string", "enum": [ "marketplace", "developer_api", "scheduled_sync", "internal" ] }, "marketplace": { "type": [ "string", "null" ] }, "accountId": { "type": [ "string", "null" ], "description": "Exact marketplace store/account identity. Null only for non-marketplace orders." }, "providerEventId": { "type": [ "string", "null" ] }, "providerEventType": { "type": [ "string", "null" ] } } }, "OrderWebhookSubject": { "type": "object", "additionalProperties": true, "required": [ "type", "id", "externalId", "externalNumber" ], "properties": { "type": { "type": "string", "const": "order" }, "id": { "type": "string" }, "externalId": { "type": [ "string", "null" ] }, "externalNumber": { "type": [ "string", "null" ] } } }, "OrderWebhookTotals": { "type": "object", "additionalProperties": true, "required": [ "subtotal", "discount", "shipping", "tax", "total" ], "properties": { "subtotal": { "$ref": "#/components/schemas/WebhookMoney" }, "discount": { "$ref": "#/components/schemas/WebhookMoney" }, "shipping": { "$ref": "#/components/schemas/WebhookMoney" }, "tax": { "$ref": "#/components/schemas/WebhookMoney" }, "total": { "$ref": "#/components/schemas/WebhookMoney" } } }, "OrderWebhookLineItem": { "type": "object", "additionalProperties": true, "required": [ "id", "productId", "externalOrderItemId", "marketplaceItemId", "marketplaceVariantId", "sku", "sellerSku", "shopSku", "name", "status", "quantity", "currency", "unitPrice", "paidPrice", "lineTotal", "unitCost" ], "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "externalOrderItemId": { "type": "string" }, "marketplaceItemId": { "type": [ "string", "null" ] }, "marketplaceVariantId": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "sellerSku": { "type": [ "string", "null" ] }, "shopSku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "minimum": 0 }, "inventory": { "oneOf": [ { "$ref": "#/components/schemas/OrderWebhookInventory" }, { "type": [ "null" ] } ], "default": null }, "inventoryUnavailableReason": { "type": [ "string", "null" ], "enum": [ "product_not_linked", "product_not_found", "variant_not_resolved", "inventory_unavailable", null ], "default": null }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unitPrice": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": [ "null" ] } ] }, "paidPrice": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": [ "null" ] } ] }, "lineTotal": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": [ "null" ] } ] }, "unitCost": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": [ "null" ] } ], "description": "Historical line cost snapshot when available; never a mutable catalog fallback." } } }, "OrderWebhookSnapshot": { "type": "object", "additionalProperties": true, "required": [ "id", "marketplace", "accountId", "externalOrderId", "externalOrderNumber", "status", "marketplaceStatus", "country", "currency", "totals", "itemCount", "quantity", "items", "placedAt", "sourceUpdatedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "marketplace": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "externalOrderId": { "type": "string" }, "externalOrderNumber": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "to_ship", "shipped", "completed", "pending", "return", "canceled" ] }, "marketplaceStatus": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "totals": { "$ref": "#/components/schemas/OrderWebhookTotals" }, "itemCount": { "type": "integer", "minimum": 0 }, "quantity": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderWebhookLineItem" } }, "placedAt": { "type": "string", "format": "date-time" }, "sourceUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrderWebhookTombstone": { "type": "object", "additionalProperties": true, "required": [ "id", "marketplace", "accountId", "externalOrderId", "externalOrderNumber", "deletedAt" ], "properties": { "id": { "type": "string" }, "marketplace": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "externalOrderId": { "type": "string" }, "externalOrderNumber": { "type": [ "string", "null" ] }, "deletedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderWebhookItemIdentity" }, "default": [] } } }, "OrderCreatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-01" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "order.created" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/OrderWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/OrderWebhookSnapshot" } } } } }, "OrderUpdatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-01" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "order.updated" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/OrderWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "order", "changedFields" ], "properties": { "order": { "$ref": "#/components/schemas/OrderWebhookSnapshot" }, "changedFields": { "type": "array", "items": { "type": "string" } } } } } }, "OrderStatusChangedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-01" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "order.status.changed" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/OrderWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "order", "previousStatus", "status", "marketplacePreviousStatus", "marketplaceStatus", "changedFields" ], "properties": { "order": { "$ref": "#/components/schemas/OrderWebhookSnapshot" }, "previousStatus": { "type": "string", "enum": [ "to_ship", "shipped", "completed", "pending", "return", "canceled" ] }, "status": { "type": "string", "enum": [ "to_ship", "shipped", "completed", "pending", "return", "canceled" ] }, "marketplacePreviousStatus": { "type": [ "string", "null" ] }, "marketplaceStatus": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } } } } } }, "OrderDeletedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-01" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "order.deleted" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/OrderWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/OrderWebhookTombstone" } } } } }, "SettlementWebhookSubject": { "type": "object", "additionalProperties": true, "required": [ "type", "id", "externalId", "externalNumber" ], "properties": { "type": { "type": "string", "const": "order_settlement" }, "id": { "type": "string" }, "externalId": { "type": [ "string", "null" ] }, "externalNumber": { "type": [ "string", "null" ] } } }, "SettlementEvidenceCounts": { "type": "object", "additionalProperties": true, "required": [ "estimated", "pending", "settled", "reversed", "voided" ], "properties": { "estimated": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "settled": { "type": "integer", "minimum": 0 }, "reversed": { "type": "integer", "minimum": 0 }, "voided": { "type": "integer", "minimum": 0 } } }, "SettlementFeeBreakdownItem": { "type": "object", "additionalProperties": true, "required": [ "feeType", "category", "amount" ], "properties": { "feeType": { "type": "string" }, "category": { "type": "string", "enum": [ "gross_sales", "refunds", "subsidies", "platform_fees", "fulfillment", "operating" ] }, "amount": { "$ref": "#/components/schemas/WebhookMoney" } } }, "SettlementPaymentReceived": { "type": "object", "additionalProperties": true, "required": [ "amount", "formulaId", "formulaVersion" ], "properties": { "amount": { "$ref": "#/components/schemas/WebhookMoney" }, "formulaId": { "type": "string" }, "formulaVersion": { "type": "string" } } }, "SettlementWebhookSnapshot": { "type": "object", "additionalProperties": true, "required": [ "id", "orderId", "marketplace", "accountId", "externalOrderId", "externalOrderNumber", "currency", "status", "grossSales", "refunds", "subsidies", "platformFees", "fulfillmentFees", "operatingFees", "marketplaceNet", "calculatedNet", "variance", "paymentReceived", "reconciliationStatus", "reconciliationExceptionReason", "settlementReference", "payoutReference", "feeBreakdown", "evidenceCounts", "sourceOccurredAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "marketplace": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "externalOrderId": { "type": "string" }, "externalOrderNumber": { "type": [ "string", "null" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "status": { "type": "string", "enum": [ "estimated", "pending", "partially_settled", "settled", "reversed", "voided" ] }, "grossSales": { "$ref": "#/components/schemas/WebhookMoney" }, "refunds": { "$ref": "#/components/schemas/WebhookMoney" }, "subsidies": { "$ref": "#/components/schemas/WebhookMoney" }, "platformFees": { "$ref": "#/components/schemas/WebhookMoney" }, "fulfillmentFees": { "$ref": "#/components/schemas/WebhookMoney" }, "operatingFees": { "$ref": "#/components/schemas/WebhookMoney" }, "marketplaceNet": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": "null" } ] }, "calculatedNet": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": "null" } ] }, "variance": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": "null" } ] }, "paymentReceived": { "oneOf": [ { "$ref": "#/components/schemas/SettlementPaymentReceived" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "reconciled", "excluded" ] }, "reconciliationExceptionReason": { "type": [ "string", "null" ], "enum": [ "missing_finance", "cancelled", "settlement_pending", "ledger_gross_mismatch" ] }, "settlementReference": { "type": [ "string", "null" ] }, "payoutReference": { "type": [ "string", "null" ] }, "feeBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementFeeBreakdownItem" } }, "evidenceCounts": { "$ref": "#/components/schemas/SettlementEvidenceCounts" }, "sourceOccurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SettlementCreatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-29" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "settlement.created" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/SettlementWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "settlement" ], "properties": { "settlement": { "$ref": "#/components/schemas/SettlementWebhookSnapshot" } } } } }, "SettlementUpdatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-29" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "settlement.updated" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/SettlementWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "settlement", "changedFields" ], "properties": { "settlement": { "$ref": "#/components/schemas/SettlementWebhookSnapshot" }, "changedFields": { "type": "array", "items": { "type": "string" } } } } } }, "SettlementStatusChangedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-29" }, "id": { "type": "string", "description": "Stable delivery event id." }, "type": { "type": "string", "const": "settlement.status.changed" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/SettlementWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "settlement", "previousStatus", "status", "changedFields" ], "properties": { "settlement": { "$ref": "#/components/schemas/SettlementWebhookSnapshot" }, "previousStatus": { "type": "string", "enum": [ "estimated", "pending", "partially_settled", "settled", "reversed", "voided" ] }, "status": { "type": "string", "enum": [ "estimated", "pending", "partially_settled", "settled", "reversed", "voided" ] }, "changedFields": { "type": "array", "items": { "type": "string" } } } } } }, "ReturnWebhookSubject": { "type": "object", "additionalProperties": true, "required": [ "type", "id", "externalId", "externalNumber" ], "properties": { "type": { "type": "string", "const": "return" }, "id": { "type": "string" }, "externalId": { "type": "string" }, "externalNumber": { "type": "null" } } }, "ReturnWebhookLineItem": { "type": "object", "additionalProperties": true, "required": [ "id", "productId", "externalReturnItemId", "marketplaceItemId", "marketplaceVariantId", "sku", "sellerSku", "shopSku", "name", "status", "quantity", "refundAmount" ], "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "externalReturnItemId": { "type": "string" }, "marketplaceItemId": { "type": [ "string", "null" ] }, "marketplaceVariantId": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "sellerSku": { "type": [ "string", "null" ] }, "shopSku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "minimum": 0 }, "refundAmount": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": "null" } ] } } }, "ReturnWebhookSnapshot": { "type": "object", "additionalProperties": true, "required": [ "id", "orderId", "marketplace", "accountId", "externalReturnId", "externalOrderId", "status", "marketplaceStatus", "country", "currency", "refundAmount", "itemCount", "quantity", "items", "sourceCreatedAt", "sourceUpdatedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "orderId": { "type": [ "string", "null" ] }, "marketplace": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "externalReturnId": { "type": "string" }, "externalOrderId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "requested", "approved", "in_transit", "received", "completed", "rejected", "cancelled", "unknown" ] }, "marketplaceStatus": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217." }, "refundAmount": { "oneOf": [ { "$ref": "#/components/schemas/WebhookMoney" }, { "type": "null" } ] }, "itemCount": { "type": "integer", "minimum": 0 }, "quantity": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnWebhookLineItem" } }, "sourceCreatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sourceUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ReturnCreatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-29" }, "id": { "type": "string" }, "type": { "type": "string", "const": "return.created" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/ReturnWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "return" ], "properties": { "return": { "$ref": "#/components/schemas/ReturnWebhookSnapshot" } } } } }, "ReturnUpdatedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-29" }, "id": { "type": "string" }, "type": { "type": "string", "const": "return.updated" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/ReturnWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "return", "changedFields" ], "properties": { "return": { "$ref": "#/components/schemas/ReturnWebhookSnapshot" }, "changedFields": { "type": "array", "items": { "type": "string" } } } } } }, "ReturnStatusChangedWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "id", "type", "occurredAt", "publishedAt", "organizationId", "resourceVersion", "source", "subject", "data" ], "properties": { "schemaVersion": { "type": "string", "const": "2026-08-29" }, "id": { "type": "string" }, "type": { "type": "string", "const": "return.status.changed" }, "occurredAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string" }, "resourceVersion": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/OrderWebhookSource" }, "subject": { "$ref": "#/components/schemas/ReturnWebhookSubject" }, "data": { "type": "object", "additionalProperties": true, "required": [ "return", "previousStatus", "status", "marketplacePreviousStatus", "marketplaceStatus", "changedFields" ], "properties": { "return": { "$ref": "#/components/schemas/ReturnWebhookSnapshot" }, "previousStatus": { "type": "string", "enum": [ "requested", "approved", "in_transit", "received", "completed", "rejected", "cancelled", "unknown" ] }, "status": { "type": "string", "enum": [ "requested", "approved", "in_transit", "received", "completed", "rejected", "cancelled", "unknown" ] }, "marketplacePreviousStatus": { "type": [ "string", "null" ] }, "marketplaceStatus": { "type": [ "string", "null" ] }, "changedFields": { "type": "array", "items": { "type": "string" } } } } } }, "AccountStatementCreatedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.created" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "statement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "statementNumber": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountBasis": { "type": "string", "enum": [ "payout", "released_income" ] }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statementAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentStatus": { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, "openingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "closingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "payoutAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "linesNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "adjustmentsNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "expectedAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "gap": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, "reconciliationBasis": { "type": "string", "enum": [ "balance movement", "released income", "payout" ] }, "orderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lineCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currencyMismatchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlinkedOrderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linesVerified": { "type": "boolean" }, "transactionRefreshStatus": { "type": "string", "enum": [ "pending", "complete", "failed" ] } }, "required": [ "id", "platform", "accountId", "statementNumber", "currency", "country", "amountBasis", "periodStart", "periodEnd", "statementAt", "dueDate", "paidAt", "paymentReference", "paymentStatus", "openingBalance", "closingBalance", "payoutAmount", "linesNet", "adjustmentsNet", "expectedAmount", "gap", "reconciliationStatus", "reconciliationBasis", "orderCount", "lineCount", "currencyMismatchCount", "unlinkedOrderCount", "linesVerified", "transactionRefreshStatus" ], "additionalProperties": false }, "previousPaymentStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, { "type": "null" } ] }, "previousReconciliationStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, { "type": "null" } ] }, "changedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "statement", "previousPaymentStatus", "previousReconciliationStatus", "changedFields" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementUpdatedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.updated" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "statement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "statementNumber": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountBasis": { "type": "string", "enum": [ "payout", "released_income" ] }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statementAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentStatus": { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, "openingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "closingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "payoutAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "linesNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "adjustmentsNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "expectedAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "gap": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, "reconciliationBasis": { "type": "string", "enum": [ "balance movement", "released income", "payout" ] }, "orderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lineCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currencyMismatchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlinkedOrderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linesVerified": { "type": "boolean" }, "transactionRefreshStatus": { "type": "string", "enum": [ "pending", "complete", "failed" ] } }, "required": [ "id", "platform", "accountId", "statementNumber", "currency", "country", "amountBasis", "periodStart", "periodEnd", "statementAt", "dueDate", "paidAt", "paymentReference", "paymentStatus", "openingBalance", "closingBalance", "payoutAmount", "linesNet", "adjustmentsNet", "expectedAmount", "gap", "reconciliationStatus", "reconciliationBasis", "orderCount", "lineCount", "currencyMismatchCount", "unlinkedOrderCount", "linesVerified", "transactionRefreshStatus" ], "additionalProperties": false }, "previousPaymentStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, { "type": "null" } ] }, "previousReconciliationStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, { "type": "null" } ] }, "changedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "statement", "previousPaymentStatus", "previousReconciliationStatus", "changedFields" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementStatusChangedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.status.changed" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "statement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "statementNumber": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountBasis": { "type": "string", "enum": [ "payout", "released_income" ] }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statementAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentStatus": { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, "openingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "closingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "payoutAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "linesNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "adjustmentsNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "expectedAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "gap": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, "reconciliationBasis": { "type": "string", "enum": [ "balance movement", "released income", "payout" ] }, "orderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lineCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currencyMismatchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlinkedOrderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linesVerified": { "type": "boolean" }, "transactionRefreshStatus": { "type": "string", "enum": [ "pending", "complete", "failed" ] } }, "required": [ "id", "platform", "accountId", "statementNumber", "currency", "country", "amountBasis", "periodStart", "periodEnd", "statementAt", "dueDate", "paidAt", "paymentReference", "paymentStatus", "openingBalance", "closingBalance", "payoutAmount", "linesNet", "adjustmentsNet", "expectedAmount", "gap", "reconciliationStatus", "reconciliationBasis", "orderCount", "lineCount", "currencyMismatchCount", "unlinkedOrderCount", "linesVerified", "transactionRefreshStatus" ], "additionalProperties": false }, "previousPaymentStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, { "type": "null" } ] }, "previousReconciliationStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, { "type": "null" } ] }, "changedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "statement", "previousPaymentStatus", "previousReconciliationStatus", "changedFields" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementReconciliationChangedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.reconciliation.changed" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "statement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "statementNumber": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountBasis": { "type": "string", "enum": [ "payout", "released_income" ] }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statementAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentStatus": { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, "openingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "closingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "payoutAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "linesNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "adjustmentsNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "expectedAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "gap": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, "reconciliationBasis": { "type": "string", "enum": [ "balance movement", "released income", "payout" ] }, "orderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lineCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currencyMismatchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlinkedOrderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linesVerified": { "type": "boolean" }, "transactionRefreshStatus": { "type": "string", "enum": [ "pending", "complete", "failed" ] } }, "required": [ "id", "platform", "accountId", "statementNumber", "currency", "country", "amountBasis", "periodStart", "periodEnd", "statementAt", "dueDate", "paidAt", "paymentReference", "paymentStatus", "openingBalance", "closingBalance", "payoutAmount", "linesNet", "adjustmentsNet", "expectedAmount", "gap", "reconciliationStatus", "reconciliationBasis", "orderCount", "lineCount", "currencyMismatchCount", "unlinkedOrderCount", "linesVerified", "transactionRefreshStatus" ], "additionalProperties": false }, "previousPaymentStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, { "type": "null" } ] }, "previousReconciliationStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, { "type": "null" } ] }, "changedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "statement", "previousPaymentStatus", "previousReconciliationStatus", "changedFields" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementTransactionsSyncedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.transactions.synced" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "statement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "statementNumber": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountBasis": { "type": "string", "enum": [ "payout", "released_income" ] }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statementAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentStatus": { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, "openingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "closingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "payoutAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "linesNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "adjustmentsNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "expectedAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "gap": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, "reconciliationBasis": { "type": "string", "enum": [ "balance movement", "released income", "payout" ] }, "orderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lineCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currencyMismatchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlinkedOrderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linesVerified": { "type": "boolean" }, "transactionRefreshStatus": { "type": "string", "enum": [ "pending", "complete", "failed" ] } }, "required": [ "id", "platform", "accountId", "statementNumber", "currency", "country", "amountBasis", "periodStart", "periodEnd", "statementAt", "dueDate", "paidAt", "paymentReference", "paymentStatus", "openingBalance", "closingBalance", "payoutAmount", "linesNet", "adjustmentsNet", "expectedAmount", "gap", "reconciliationStatus", "reconciliationBasis", "orderCount", "lineCount", "currencyMismatchCount", "unlinkedOrderCount", "linesVerified", "transactionRefreshStatus" ], "additionalProperties": false }, "previousPaymentStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, { "type": "null" } ] }, "previousReconciliationStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, { "type": "null" } ] }, "changedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "statement", "previousPaymentStatus", "previousReconciliationStatus", "changedFields" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementTransactionsFailedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.transactions.failed" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "statement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "statementNumber": { "type": "string", "minLength": 1 }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountBasis": { "type": "string", "enum": [ "payout", "released_income" ] }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statementAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentStatus": { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, "openingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "closingBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "payoutAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "linesNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "adjustmentsNet": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "expectedAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "gap": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, { "type": "null" } ] }, "reconciliationStatus": { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, "reconciliationBasis": { "type": "string", "enum": [ "balance movement", "released income", "payout" ] }, "orderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lineCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currencyMismatchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlinkedOrderCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linesVerified": { "type": "boolean" }, "transactionRefreshStatus": { "type": "string", "enum": [ "pending", "complete", "failed" ] } }, "required": [ "id", "platform", "accountId", "statementNumber", "currency", "country", "amountBasis", "periodStart", "periodEnd", "statementAt", "dueDate", "paidAt", "paymentReference", "paymentStatus", "openingBalance", "closingBalance", "payoutAmount", "linesNet", "adjustmentsNet", "expectedAmount", "gap", "reconciliationStatus", "reconciliationBasis", "orderCount", "lineCount", "currencyMismatchCount", "unlinkedOrderCount", "linesVerified", "transactionRefreshStatus" ], "additionalProperties": false }, "previousPaymentStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "unknown", "unpaid", "paid", "failed" ] }, { "type": "null" } ] }, "previousReconciliationStatus": { "anyOf": [ { "type": "string", "enum": [ "open", "currency_unknown", "partial", "unknown", "matched", "gap" ] }, { "type": "null" } ] }, "changedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "statement", "previousPaymentStatus", "previousReconciliationStatus", "changedFields" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementSyncQueuedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.sync.queued" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement_sync" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, "statementsSynced": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedStatements": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "platform", "accountId", "status", "statementsSynced", "failedStatements", "error" ], "additionalProperties": false }, "previousStatus": { "anyOf": [ { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, { "type": "null" } ] } }, "required": [ "sync", "previousStatus" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementSyncStartedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.sync.started" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement_sync" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, "statementsSynced": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedStatements": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "platform", "accountId", "status", "statementsSynced", "failedStatements", "error" ], "additionalProperties": false }, "previousStatus": { "anyOf": [ { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, { "type": "null" } ] } }, "required": [ "sync", "previousStatus" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementSyncCompletedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.sync.completed" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement_sync" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, "statementsSynced": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedStatements": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "platform", "accountId", "status", "statementsSynced", "failedStatements", "error" ], "additionalProperties": false }, "previousStatus": { "anyOf": [ { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, { "type": "null" } ] } }, "required": [ "sync", "previousStatus" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementSyncFailedWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.sync.failed" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement_sync" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, "statementsSynced": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedStatements": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "platform", "accountId", "status", "statementsSynced", "failedStatements", "error" ], "additionalProperties": false }, "previousStatus": { "anyOf": [ { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, { "type": "null" } ] } }, "required": [ "sync", "previousStatus" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false }, "AccountStatementSyncUnavailableWebhookEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "2026-10-06" }, "id": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "const": "account-statements.sync" }, "type": { "type": "string", "const": "account_statement.sync.unavailable" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "const": "account_statement_sync" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "type", "id" ], "additionalProperties": false }, "data": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "platform": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon", "ebay" ] }, "accountId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, "statementsSynced": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedStatements": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "platform", "accountId", "status", "statementsSynced", "failedStatements", "error" ], "additionalProperties": false }, "previousStatus": { "anyOf": [ { "type": "string", "enum": [ "queued", "running", "completed", "failed", "unavailable" ] }, { "type": "null" } ] } }, "required": [ "sync", "previousStatus" ], "additionalProperties": false } }, "required": [ "schemaVersion", "id", "organizationId", "occurredAt", "publishedAt", "resourceVersion", "source", "type", "subject", "data" ], "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows." } } } }