{ "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": "commerce", "description": "Root commerce discovery", "x-group": "Commerce" }, { "name": "developer-platform", "description": "Authenticated developer platform APIs", "x-group": "Developer Platform" }, { "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, and publish", "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": "settlements", "description": "settlements", "x-group": "Settlements" }, { "name": "ucp", "description": "Universal Commerce Protocol", "x-group": "UCP" } ], "paths": { "/api": { "get": { "operationId": "get_root", "summary": "API Root", "description": "Public API discovery root. Merchant payments are handled by organization-scoped checkout session endpoints.", "tags": [ "commerce" ], "security": [], "responses": { "200": { "description": "API root metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "resource", "service" ], "properties": { "ok": { "type": "boolean" }, "resource": { "type": "string" }, "service": { "type": "string" } } } } } }, "429": { "description": "Too many requests." } } } }, "/api/v1": { "get": { "operationId": "get_v1", "summary": "API v1 Root", "description": "Public API v1 discovery root. Merchant payments are handled by organization-scoped checkout session endpoints.", "tags": [ "commerce" ], "security": [], "responses": { "200": { "description": "API v1 root metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "resource", "service" ], "properties": { "ok": { "type": "boolean" }, "resource": { "type": "string" }, "service": { "type": "string" } } } } } }, "429": { "description": "Too many requests." } } } }, "/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" } } }, "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" } } }, "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" } } } }, "/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/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, and sync jobs.", "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. Supports product workflow jobs returned by POST /api/v1/products, bulk CSV import jobs returned by POST /api/v1/products/bulk-import, and Look generation jobs returned by POST /api/v1/looks. Completed or failed jobs are returned with their current terminal status.", "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" ] }, "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" ] }, "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" ] }, "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" ] } }, { "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" ] }, "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" ] }, "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" ] } }, { "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": "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 listed price.", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum listed price.", "schema": { "type": "number" } }, { "name": "in_stock", "in": "query", "required": false, "description": "Filter by stock availability.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc" ], "default": "relevance" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada" ] } }, { "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": "Filter by normalized order status group.", "schema": { "type": "string", "enum": [ "to_ship", "shipped", "completed", "pending", "return", "canceled" ] } }, { "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": "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" } } }, "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. Supports `status`, `currency`, `country`, `totalAmount`, and per-line `price` / `unitPrice` / `paidPrice` / `costPrice`. When `productId` is provided, missing price/currency may resolve from the product catalog; explicit `costPrice` upserts `product_data.costPrice` and is snapshotted on the line. Omitted `costPrice` never clears existing product cost. When `country` is empty, Omni may derive marketplace country from order currency (e.g. PHP→philippines; USD is not guessed). Reuses the same upsert path as agentic checkout completion. Requires `orders:write`. Re-posting the same `externalOrderId` updates the existing order instead of creating a duplicate — partners who store one row per SKU should reuse the marketplace order id as `externalOrderId` and put their unique row id on `items[].externalOrderItemId`. When `totalAmount` is omitted, the order total is recomputed from all lines after upsert.", "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}": { "patch": { "operationId": "patch_v1_orders_by_orderid", "summary": "Update Order", "description": "Update a native **agentic** order. Supports external order identifiers, status, currency, country, totalAmount, shippingFee, discountAmount, metadata, orderCreatedAt, and line-item upserts (externalOrderItemId, price / unitPrice / paidPrice / costPrice / currency / status / quantity). Matching externalOrderItemId updates a line; a new externalOrderItemId with productName + quantity inserts a line (multi-SKU append). When totalAmount is omitted and lines change, the order total is recomputed from all lines. When country is omitted and stored country is empty, Omni derives country from the resulting order currency when unambiguous. Requires `orders:write`. Marketplace orders (Shopee, Lazada, TikTok, Shopify) are rejected with HTTP 409 — those fields are marketplace-owned. Emits `order.status.changed` when status changes and `order.updated` for other field changes.", "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/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. Rules apply markup percent to canonical list price at publish/catalog 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`, or `amazon`.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "whatsapp", "zalora", "amazon" ] } }, { "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 that marks up canonical list price for a platform (optional store/country). Does not change Omni product prices. Requires `price_books:write`.", "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" ] }, "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 canonical list price." }, "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, 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 }, "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" ] }, "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" }, "rule": { "type": [ "object", "null" ] }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request" }, "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. Supports API key Bearer token authentication.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by product status.", "schema": { "type": "string", "enum": [ "draft", "active", "archived", "deleted" ] } }, { "name": "marketplace", "in": "query", "required": false, "description": "Filter by enabled marketplace.", "schema": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon" ] } }, { "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": "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" } }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer" }, "summary": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "statusCounts": { "type": "object" } } }, "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 and Enrich Product", "description": "Queue a single-product create/enrich workflow for the authenticated organization. The request mirrors bulk product import for one product: `product` contains developer-supplied fields, arbitrary extra fields are preserved for enrichment context, SKU is the unique upsert identifier, externally hosted HTTP(S) images are mirrored to managed R2 storage, and the API returns a job ID to poll with GET /api/v1/jobs/{jobId}. `targetMarketplaces` and `targetCountries` are optional; product creation and enrichment can run without marketplace publishing targets.", "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": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "url": { "type": "string", "description": "External HTTP(S) image URL." }, "alt": { "type": "string" }, "position": { "type": "integer" } }, "required": [ "url" ] } ] } } ], "description": "External HTTP(S) image URLs. Pipe-delimited strings and arrays are accepted. Images are mirrored to R2 before storage; 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": "Optional per-marketplace hints. Enabled marketplace keys can be used to derive target marketplaces/countries when top-level targets are omitted." } } }, "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" ] } }, "targetCountries": { "type": "array", "description": "Optional target country hints for marketplace/GEO workflows.", "items": { "type": "string" } }, "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": true }, "aco": { "type": "boolean", "default": true, "description": "When true, runs ACO generation after the product is written." }, "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." }, "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 ghost mannequin removal for eligible product images after ingestion." }, "autoAssignMarketplaceTaxonomy": { "type": "boolean", "default": false, "description": "When true and marketplace targets are provided, enrichment resolves marketplace categories, brands, and attributes in the same graph before the product is written." }, "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" }, "variants": [ { "sku": "TZVBGTB82269-BLUE", "price": "600", "variationAttributes": { "color": "BLUE" } } ], "additionalInstructions": "Exclude images that are size charts, maps, or cluttered supplier feed shots.", "workflow": { "aco": true, "sourceImagesAutomatically": false, "enableRichDescription": true, "skipBackgroundRemoval": false, "enableMannequinRemoval": true, "autoAssignMarketplaceTaxonomy": true, "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. Supports API key Bearer token authentication. The response includes generated Agentic Commerce Optimization (ACO) profile metadata, FAQs, localization content, intent queries, cultural notes, signals, sources, and claims when present.", "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" }, "images": { "type": "array", "items": { "type": "object" } }, "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" } } } } } }, "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": "object" } }, "highlights": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "marketplaces": { "type": "object" }, "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}/publish": { "post": { "operationId": "post_v1_products_by_productid_publish", "summary": "Publish Product", "description": "Queue marketplace publish jobs for a product by productId. OmniCommerce publishes to the marketplaces already enabled on the product and uses the product's store selection or a single/default connected store.", "tags": [ "developer-platform" ], "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." }, "visibility": { "type": "string", "enum": [ "live", "draft" ], "default": "live", "description": "Publish visibility mode." } } }, "example": { "visibility": "live" } } } }, "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" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "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 CSV", "description": "Queue a bulk CSV product import for the authenticated organization. Upload a CSV file with multipart/form-data or send JSON with inline `csvText` or a stored `documentId`. The API creates import rows, queues enrichment and product writes through Inngest, and returns a `bulk_...` job ID to poll with GET /api/v1/jobs/{jobId}. Cancel in-flight imports with POST /api/v1/jobs/{jobId}/cancel.", "tags": [ "products" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "targetMarketplaces", "targetCountries" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file containing product rows." }, "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." }, "targetMarketplaces": { "oneOf": [ { "type": "string", "description": "Comma-separated marketplace list, e.g. `shopee,lazada`." }, { "type": "array", "items": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon" ] } } ] }, "targetCountries": { "oneOf": [ { "type": "string", "description": "Comma-separated country list, e.g. `sg,my`." }, { "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": { "type": "string", "description": "JSON object mapping marketplace keys to connected store IDs." }, "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." }, "workflow": { "type": "string", "description": "JSON object with enrichment workflow options such as `sourceImagesAutomatically`, `enableRichDescription`, and `autoAssignMarketplaceTaxonomy`." } } } }, "application/json": { "schema": { "type": "object", "required": [ "targetMarketplaces", "targetCountries" ], "properties": { "organizationId": { "type": "string", "description": "Optional for API-key requests; required for session-authenticated requests across multiple organizations." }, "csvText": { "type": "string", "description": "Inline CSV text. Required unless `documentId` is provided." }, "documentId": { "type": "string", "description": "Existing uploaded CSV document ID for the organization." }, "fileName": { "type": "string" }, "selectedRowIndexes": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "lane": { "type": "string", "enum": [ "standard", "enterprise" ] }, "targetMarketplaces": { "type": "array", "items": { "type": "string", "enum": [ "shopee", "lazada", "tiktok", "shopify", "zalora", "amazon" ] }, "minItems": 1 }, "targetCountries": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "fieldMapping": { "type": "object", "additionalProperties": { "type": "string" } }, "dedupPolicy": { "type": "string", "enum": [ "keep_first", "keep_last", "merge_fields_prefer_non_empty", "fail_job" ] }, "autoApproveThreshold": { "type": [ "number", "null" ] }, "spendCeilingUsd": { "type": [ "number", "null" ] }, "marketplaceStoreSelections": { "type": "object", "additionalProperties": { "type": "string" } }, "model": { "type": "string" }, "workflow": { "type": "object", "additionalProperties": true } } }, "example": { "organizationId": "org_1", "csvText": "sku,title,price,images\nSKU-1,Sample product,19.90,https://cdn.example.com/sku-1.jpg\n", "targetMarketplaces": [ "shopee" ], "targetCountries": [ "sg" ], "fieldMapping": { "sku": "sku", "title": "title", "price": "price", "images": "images" } } } } }, "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 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 - CSV upload exceeds limit" }, "500": { "description": "Internal Server Error" } } } }, "/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", "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", "storeKeys" ], "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 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0, "description": "Positive discount amount or percentage (must be > 0)." }, "storeKeys": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Connected store keys as `marketplace:country:storeId`." }, "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." } } }, "example": { "name": "Christmas", "discountType": "fixed_amount", "discountValue": 12, "storeKeys": [ "shopee:singapore: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 }, "discountType": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discountValue": { "type": "number", "minimum": 0, "description": "Positive discount amount or percentage (must be > 0)." }, "storeKeys": { "type": "array", "minItems": 1, "items": { "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 } } } } } }, "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 } } }, "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}/sync": { "post": { "operationId": "post_v1_promotions_by_promotionid_sync", "summary": "Sync Promotion to Marketplaces", "description": "Queue marketplace push for assigned products (Shopee discount, Lazada voucher, TikTok activity, Shopify automatic discount). 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 }, "marketplace": { "type": "string", "enum": [ "lazada", "shopee", "tiktok", "shopify" ], "description": "Optional single marketplace. When omitted, syncs all promotion marketplaces." }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional product subset. When omitted, syncs all assigned products." } } }, "example": { "marketplace": "shopee" } } } }, "responses": { "202": { "description": "Sync queued.", "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/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": "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 listed price.", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum listed price.", "schema": { "type": "number" } }, { "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 order.", "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc" ], "default": "relevance" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada" ] } }, { "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": "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 listed price.", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum listed price.", "schema": { "type": "number" } }, { "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 order.", "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc" ], "default": "relevance" } }, { "name": "platform", "in": "query", "required": false, "description": "Marketplace platform filter.", "schema": { "type": "string", "enum": [ "shopee", "lazada" ] } }, { "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": { "post": { "operationId": "post_v1_settlements", "summary": "Apply Settlements", "description": "Apply marketplace-agnostic settlement lines to existing orders. Writes marketplace financial evidence, projects **settled** rows into the order finance ledger, and recomputes Payment received when a marketplace formula exists (Zalora today). Pending, reversed, and voided rows stay on evidence only and un-project any earlier developer-API ledger row for that sourceEventKey. This is not an order-price API: selling prices, COGS, and returns stay on `POST/PATCH /api/v1/orders`. Do not send `paymentReceived`. Requires `orders:write`. Match is organization + marketplace order platform + exact `externalOrderId` (and `externalOrderItemId` when the order has multiple lines). `accountId` is an exact store match, never a wildcard. `marketplace=zalora` matches orders imported from Zalora Seller Center (`platform=zalora`) as well as reconciliation-era agentic carts; ledger rows keep whichever platform the matched order has. If one `externalOrderId` exists under both, the line fails as ambiguous — pass `accountId` to disambiguate. **Zalora ITR parity:** send one `lines[]` entry per report row (`transactionType` such as Commission, Item Price Credit, ZAP Commitments, Payment Gateway Fee, shipping, penalties, credits — Omni maps fee types like the ITR parser). `settlementStatus=settled` is paid; `pending` is not. Payment received (Zalora) recomputes from Item Price Credit − ZAP − Commission ledger legs only; PG, shipping, and penalties still post to P&L when settled but are excluded from that formula, same as ITR. Item Price Credit here updates Payment received via the ledger without changing line `paidPrice`/`unitPrice` — PATCH `/api/v1/orders/{orderId}` when displayed prices must match. **Does not replace ITR apply for:** parsing spreadsheets, writing `paidPrice`/`unitPrice`, auto-marking returned/cancelled lines (and return inventory restock), SKU fallback matching, order currency/total rewrite, COGS currency rebase, or undo/redo. Do not apply the same fee lines through this API and the Zalora Item Transaction Report tool — `source_event_key` namespaces differ (`developer_api:…` vs `zalora_report:…`) and Payment received will double-count.", "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/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/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 product, order, look, and related commerce events.", "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" } } } }, "/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" } } } } }, "components": { "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." } } } }