{ "openapi": "3.0.3", "info": { "title": "StateSet Sync Server API", "description": "Multi-tenant order orchestration and integration platform.", "contact": { "name": "Stateset Inc." }, "license": { "name": "BUSL-1.1" }, "version": "1.0.0" }, "paths": { "/v1/tenants/{tenant_id}/acp/orders": { "post": { "tags": [ "acp" ], "summary": "Process an ACP order - creates in StateSet and routes to fulfillment/ERP", "operationId": "process_acp_order", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpOrderRequest" } } }, "required": true }, "responses": { "201": { "description": "Order accepted and processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpOrderResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "424": { "description": "Required integration not configured" }, "502": { "description": "Downstream service error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/acp/orders/async": { "post": { "tags": [ "acp" ], "summary": "Process ACP order asynchronously as a background job", "operationId": "process_acp_order_async", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpOrderRequest" } } }, "required": true }, "responses": { "202": { "description": "Order accepted for async processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpJobResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/acp/orders/batch": { "post": { "tags": [ "acp" ], "summary": "Batch process multiple ACP orders", "operationId": "process_acp_orders_batch", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpBatchRequest" } } }, "required": true }, "responses": { "202": { "description": "Batch accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpJobResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/agent/execute": { "post": { "tags": [ "agent" ], "summary": "Execute a tool by name with parameters.", "operationId": "execute_tool", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteToolRequest" } } }, "required": true }, "responses": { "200": { "description": "Tool execution result" }, "401": { "description": "Unauthorized" }, "404": { "description": "Tool not found" }, "428": { "description": "Confirmation required for mutating tools" } }, "security": [ { "api_key": [] }, { "bearer_auth": [] } ] } }, "/v1/tenants/{tenant_id}/audit-logs": { "get": { "tags": [ "audit" ], "summary": "List audit-log entries scoped to the caller's tenant.", "description": "This is the self-service sibling of `/v1/admin/audit-logs`. The\ntenant_id filter is pinned to the authenticated tenant at the SQL\nlayer \u2014 a client cannot widen their view by passing a different\n`tenant_id` query param; it simply isn't accepted. Useful when an\nagent needs to answer \"what did I do in the last hour\" without\nreaching for platform admin credentials.", "operationId": "list_tenant_audit_logs", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant id (must match the authenticated tenant)", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "event_type", "in": "query", "description": "Filter by event type", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "resource_type", "in": "query", "description": "Filter by resource type", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "actor_email", "in": "query", "description": "Filter by actor email", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Audit logs for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/cart/orders": { "post": { "tags": [ "cart" ], "summary": "Create an order in Cart.com", "operationId": "cart_create_order", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartComOrderCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Order created in Cart.com", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartComOrderCreateResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "424": { "description": "Cart.com integration not configured" }, "502": { "description": "Cart.com API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/dcl/batches": { "post": { "tags": [ "dcl" ], "summary": "Create a batch of orders in DCL", "operationId": "dcl_create_batch", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclBatchCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclBatchSubmissionResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "424": { "description": "DCL integration not configured" }, "502": { "description": "DCL API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/dcl/po-receipts": { "post": { "tags": [ "dcl" ], "summary": "Fetch PO receipts from DCL", "operationId": "dcl_fetch_po_receipts", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclPoReceiptsRequest" } } }, "required": true }, "responses": { "200": { "description": "PO receipts retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclPoReceiptsResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "DCL integration not configured" }, "502": { "description": "DCL API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/dcl/po-receipts/item-receipts": { "post": { "tags": [ "dcl" ], "summary": "Create an item receipt in NetSuite from a DCL PO receipt", "operationId": "dcl_create_item_receipt", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclItemReceiptCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Item receipt created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteRecordResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "DCL or NetSuite integration not configured" }, "502": { "description": "API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/dcl/tracking": { "post": { "tags": [ "dcl" ], "summary": "Fetch tracking information from DCL", "operationId": "dcl_fetch_tracking", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclTrackingRequest" } } }, "required": true }, "responses": { "200": { "description": "Tracking data retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DclTrackingResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "DCL integration not configured" }, "502": { "description": "DCL API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/integrations": { "get": { "tags": [ "integrations" ], "summary": "List integrations for a tenant, including last sync + circuit breaker snapshots.", "operationId": "list_integrations", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Integration summaries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSummary" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/integrations/health": { "get": { "tags": [ "integrations" ], "summary": "Run health checks for configured integrations for a tenant.", "operationId": "get_integrations_health", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Integration health checks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationHealthCheck" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/inventory": { "get": { "tags": [ "inventory" ], "summary": "Get consolidated inventory across all locations", "operationId": "get_consolidated_inventory", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "sku", "in": "query", "description": "SKU to look up", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory data retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidatedInventoryResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/inventory/adjustments": { "get": { "tags": [ "inventory" ], "summary": "List inventory adjustments (audit trail)", "operationId": "list_inventory_adjustments", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "sku", "in": "query", "description": "Filter by SKU", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "location", "in": "query", "description": "Filter by location", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "source", "in": "query", "description": "Filter by source system", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "reason", "in": "query", "description": "Filter by adjustment reason", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "reference_type", "in": "query", "description": "Filter by reference type (order, webhook, sync_job, reservation)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "reference_id", "in": "query", "description": "Filter by reference id", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "since", "in": "query", "description": "Filter by created_at (RFC3339 timestamp)", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Inventory adjustments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crate.http.pagination.PaginatedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/inventory/alerts": { "get": { "tags": [ "inventory" ], "summary": "Check low stock alerts", "operationId": "get_low_stock_alerts", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "threshold", "in": "query", "description": "Stock threshold (default: 10)", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } } ], "responses": { "200": { "description": "Low stock alerts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LowStockAlertResponse" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/inventory/reservations": { "post": { "tags": [ "inventory" ], "summary": "Reserve inventory for an order", "operationId": "reserve_inventory", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryReservationRequest" } } }, "required": true }, "responses": { "200": { "description": "Inventory reserved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryReservationResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Insufficient inventory" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/inventory/reservations/{reservation_id}": { "delete": { "tags": [ "inventory" ], "summary": "Release inventory reservation", "operationId": "release_inventory_reservation", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "reservation_id", "in": "path", "description": "Reservation ID to release", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reservation released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Reservation not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/jobs": { "get": { "tags": [ "jobs" ], "summary": "List background jobs for a tenant", "operationId": "list_jobs", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "state", "in": "query", "description": "Filter by job state (queued, running, succeeded, failed, retry_pending)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "job_type", "in": "query", "description": "Filter by job type (e.g. shopify_sync)", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crate.http.pagination.PaginatedResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/jobs/summary": { "get": { "tags": [ "jobs" ], "summary": "Summarize job state counts for a tenant (dashboard helper).", "operationId": "get_jobs_summary", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crate.http.jobs.TenantJobSummary" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/jobs/throughput": { "get": { "tags": [ "jobs" ], "summary": "Job throughput analytics for dashboard charts.", "operationId": "get_jobs_throughput", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "hours", "in": "query", "description": "Lookback window in hours (1-168, default 24)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "bucket_minutes", "in": "query", "description": "Bucket width in minutes (5-240, default 60)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Job throughput buckets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobThroughputResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/jobs/{job_id}": { "get": { "tags": [ "jobs" ], "summary": "Get status of a background job", "operationId": "get_job_status", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "description": "Job UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInfo" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Job not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/jobs/{job_id}/cancel": { "post": { "tags": [ "jobs" ], "summary": "Cancel a queued job (operator tooling).", "operationId": "cancel_job", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "description": "Job identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobRequest" } } }, "required": true }, "responses": { "200": { "description": "Job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInfo" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Job not found" }, "409": { "description": "Job not cancellable" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/jobs/{job_id}/retry": { "post": { "tags": [ "jobs" ], "summary": "Manually retry a failed/cancelled job (operator tooling).", "operationId": "manual_retry_job", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "description": "Job identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job queued for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInfo" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Job not found" }, "409": { "description": "Job not retryable" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/mcp": { "post": { "tags": [ "agent" ], "summary": "Handle a JSON-RPC 2.0 request against the MCP surface for a tenant.", "operationId": "handle", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRequest" } } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpResponse" } } } }, "204": { "description": "Notification accepted" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] }, { "bearer_auth": [] } ] } }, "/v1/tenants/{tenant_id}/netsuite/cash-sales": { "post": { "tags": [ "netsuite" ], "summary": "Create a NetSuite cash sale", "operationId": "netsuite_create_cash_sale", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteCashSaleCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Cash sale created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteRecordResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "NetSuite integration not configured" }, "502": { "description": "NetSuite API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/netsuite/custom-fields/batch": { "post": { "tags": [ "netsuite" ], "summary": "Batch update custom fields on NetSuite orders", "operationId": "netsuite_update_custom_field_batch", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteCustomFieldBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "424": { "description": "NetSuite integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/netsuite/item-fulfillments": { "post": { "tags": [ "netsuite" ], "summary": "Create a NetSuite item fulfillment", "operationId": "netsuite_create_item_fulfillment", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteItemFulfillmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Item fulfillment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteRecordResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "NetSuite integration not configured" }, "502": { "description": "NetSuite API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/netsuite/sales-orders": { "post": { "tags": [ "netsuite" ], "summary": "Create a NetSuite sales order", "operationId": "netsuite_create_sales_order", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteSalesOrderCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Sales order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteRecordResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "NetSuite integration not configured" }, "502": { "description": "NetSuite API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/netsuite/sales-orders/search": { "post": { "tags": [ "netsuite" ], "summary": "Search NetSuite sales orders", "operationId": "netsuite_fetch_sales_orders", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteSalesOrderQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Sales orders found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteSalesOrderQueryResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "NetSuite integration not configured" }, "502": { "description": "NetSuite API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/netsuite/suiteql": { "post": { "tags": [ "netsuite" ], "summary": "Execute a SuiteQL query against NetSuite", "operationId": "netsuite_run_suiteql", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteSuiteQlRequest" } } }, "required": true }, "responses": { "200": { "description": "Query executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetSuiteSuiteQlResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Invalid SuiteQL query" }, "424": { "description": "NetSuite integration not configured" }, "502": { "description": "NetSuite API error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/orders": { "get": { "tags": [ "orders" ], "summary": "List orders with filtering and pagination", "operationId": "list_orders", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "status", "in": "query", "description": "Filter by order status", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "created_after", "in": "query", "description": "Filter by creation date (ISO 8601)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "created_before", "in": "query", "description": "Filter by creation date (ISO 8601)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "order_number", "in": "query", "description": "Search by order number", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "shopify_order_id", "in": "query", "description": "Search by Shopify order ID", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "tags", "in": "query", "description": "Filter by tags (comma-separated)", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "orders" ], "summary": "Create a new order in StateSet", "operationId": "create_stateset_order", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }, "required": true }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/orders/batch": { "post": { "tags": [ "orders" ], "summary": "Create multiple orders in one request.", "operationId": "create_stateset_orders_batch", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "When true, validates and previews results without creating orders", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrdersBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch processed with one or more failures", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrdersBatchResponse" } } } }, "201": { "description": "All orders created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrdersBatchResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/orders/{order_id}": { "get": { "tags": [ "orders" ], "summary": "Get a single order by ID", "operationId": "get_order", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "description": "Order UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Order not found" } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "orders" ], "summary": "Delete an order", "operationId": "delete_order", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "description": "Order UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOrderResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Order not found" }, "409": { "description": "Order cannot be deleted (already fulfilled)" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/orders/{order_id}/fulfillment": { "post": { "tags": [ "orders" ], "summary": "Update fulfillment status for an order", "operationId": "update_fulfillment", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "description": "Order UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFulfillmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Fulfillment updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Order not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/orders/{order_id}/tracking": { "post": { "tags": [ "orders" ], "summary": "Update tracking information for an order", "operationId": "update_tracking", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "description": "Order UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTrackingRequest" } } }, "required": true }, "responses": { "200": { "description": "Tracking updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Order not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/products/catalog-feed": { "post": { "tags": [ "products" ], "summary": "Generate or publish a product catalog feed for ChatGPT, TikTok Shop, Google Shopping, or a generic channel.", "operationId": "publish_catalog_feed", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCatalogFeedBody" } } }, "required": true }, "responses": { "200": { "description": "Catalog feed generated or delivered" }, "401": { "description": "Unauthorized" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/schedules": { "get": { "tags": [ "schedules" ], "summary": "List schedules for a tenant.", "operationId": "list_schedules", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Schedules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "schedules" ], "summary": "Create a schedule for a tenant.", "operationId": "create_schedule", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Schedule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleInfo" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/schedules/{schedule_id}": { "delete": { "tags": [ "schedules" ], "summary": "Delete a schedule.", "operationId": "delete_schedule", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "path", "description": "Schedule identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule deleted", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Schedule not found" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] }, "patch": { "tags": [ "schedules" ], "summary": "Update an existing schedule.", "operationId": "update_schedule", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "path", "description": "Schedule identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Schedule updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleInfo" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Schedule not found" }, "422": { "description": "Validation error" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/shopify/webhooks/register": { "post": { "tags": [ "shopify" ], "summary": "Register Shopify webhooks for order events", "operationId": "register_shopify_webhooks", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopifyWebhookRegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhooks registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "Shopify integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/all": { "post": { "tags": [ "sync" ], "summary": "Trigger a comprehensive sync across one or more channels.", "operationId": "trigger_sync_all", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncAllRequest" } } }, "required": true }, "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/amazon": { "post": { "tags": [ "sync" ], "summary": "Trigger Amazon order sync", "operationId": "trigger_amazon_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "Amazon integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/batch": { "post": { "tags": [ "sync" ], "summary": "Trigger multiple sync channels in a single API call.", "operationId": "trigger_batch_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSyncRequest" } } }, "required": true }, "responses": { "202": { "description": "Batch sync jobs queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSyncResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/dcl": { "post": { "tags": [ "sync" ], "summary": "Trigger DCL order synchronization", "operationId": "trigger_dcl_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "DCL integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/ebay": { "post": { "tags": [ "sync" ], "summary": "Trigger eBay order sync", "operationId": "trigger_ebay_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "eBay integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/etsy": { "post": { "tags": [ "sync" ], "summary": "Trigger Etsy order sync", "operationId": "trigger_etsy_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "Etsy integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/fishbowl": { "post": { "tags": [ "sync" ], "summary": "Trigger Fishbowl / Tri-Pac order submission, shipment, receipt, and inventory sync", "operationId": "trigger_fishbowl_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "Fishbowl integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/inventory": { "post": { "tags": [ "sync" ], "summary": "Trigger inventory sync across all platforms", "operationId": "trigger_inventory_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Optional warehouse/location filter", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "source", "in": "query", "description": "Optional source filter (shopify, netsuite)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "force_full", "in": "query", "description": "Force full sync instead of incremental", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/netsuite": { "post": { "tags": [ "sync" ], "summary": "Trigger NetSuite order synchronization", "operationId": "trigger_netsuite_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "NetSuite integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/plan/dry-run": { "post": { "tags": [ "sync" ], "summary": "Build and dry-run a typed commerce sync plan without side effects.", "operationId": "dry_run_sync_plan", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceSyncPlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Sync plan validated and dry-run execution returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crate.orchestrators.SyncPlanExecution" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/plan/execute": { "post": { "tags": [ "sync" ], "summary": "Execute a typed commerce sync plan using the configured tenant orchestrators.", "operationId": "execute_sync_plan_handler", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceSyncPlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Sync plan executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crate.orchestrators.SyncPlanExecution" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/plan/queue": { "post": { "tags": [ "sync" ], "summary": "Queue a typed commerce sync plan for background execution.", "operationId": "queue_sync_plan_execution", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceSyncPlanRequest" } } }, "required": true }, "responses": { "202": { "description": "Sync plan execution job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/products": { "post": { "tags": [ "products" ], "summary": "Trigger a product sync from a source platform.", "operationId": "trigger_product_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSyncBody" } } }, "required": true }, "responses": { "202": { "description": "Product sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Unsupported product sync source" }, "424": { "description": "Required integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/returns": { "post": { "tags": [ "sync" ], "summary": "Trigger return/refund processing sync.", "operationId": "trigger_returns_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Return sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "Database not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/shopify": { "post": { "tags": [ "sync" ], "operationId": "trigger_shopify_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "financial_status", "in": "query", "description": "Optional Shopify financial status filter", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "fulfillment_status", "in": "query", "description": "Optional Shopify fulfillment status filter", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "status", "in": "query", "description": "Optional Shopify order status filter", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "since_id", "in": "query", "description": "Optional Shopify since_id cursor override", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "updated_at_min", "in": "query", "description": "Optional updated_at_min timestamp (RFC3339)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "updated_at_max", "in": "query", "description": "Optional updated_at_max timestamp (RFC3339)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "limit", "in": "query", "description": "Optional page size (1-250)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "424": { "description": "Shopify integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/shopware": { "post": { "tags": [ "sync" ], "summary": "Trigger Shopware order sync", "operationId": "trigger_shopware_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "Shopware integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/stateset-api": { "post": { "tags": [ "sync" ], "summary": "Trigger StateSet API ERP order synchronization", "operationId": "trigger_stateset_api_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "401": { "description": "Unauthorized" }, "424": { "description": "StateSet API integration not configured" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/tiktok": { "post": { "tags": [ "sync" ], "summary": "Trigger TikTok order sync", "operationId": "trigger_tiktok_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "TikTok integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/walmart": { "post": { "tags": [ "sync" ], "summary": "Trigger Walmart order sync", "operationId": "trigger_walmart_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "Walmart integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/sync/woocommerce": { "post": { "tags": [ "sync" ], "summary": "Trigger WooCommerce order sync", "operationId": "trigger_woocommerce_sync", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueuedResponse" } } } }, "400": { "description": "WooCommerce integration not configured" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhook-events": { "get": { "tags": [ "webhook_events" ], "summary": "List webhook events for a tenant (most recent first).", "operationId": "list_webhook_events", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "state", "in": "query", "description": "Filter by processing state (queued, running, succeeded, failed)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "source", "in": "query", "description": "Filter by webhook source (e.g. shopify, acp)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "topic", "in": "query", "description": "Filter by exact topic (e.g. orders/create)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "topic_prefix", "in": "query", "description": "Filter by topic prefix (e.g. orders/)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "shopify_order_id", "in": "query", "description": "Filter by Shopify order id (Shopify webhooks only)", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Webhook events page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhook-events/replay": { "post": { "tags": [ "webhook_events" ], "summary": "Replay multiple webhook events in one request (operator tooling).", "operationId": "replay_webhook_events", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max events to replay (1-200), default 50", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "state", "in": "query", "description": "Filter by processing state (default failed)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "source", "in": "query", "description": "Filter by source (e.g. acp, shopify)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "topic", "in": "query", "description": "Filter by exact topic", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "topic_prefix", "in": "query", "description": "Filter by topic prefix", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "shopify_order_id", "in": "query", "description": "Filter by Shopify order id", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "dry_run", "in": "query", "description": "Preview replay candidates without queueing", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "max_per_source", "in": "query", "description": "Optional cap per source (1-200)", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } ], "responses": { "202": { "description": "Webhook replays queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayWebhookEventsResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid replay filter" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhook-events/replay-by-id": { "post": { "tags": [ "webhook_events" ], "summary": "Replay specific webhook events by id (operator tooling).", "operationId": "replay_webhook_events_by_id", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayWebhookEventsByIdRequest" } } }, "required": true }, "responses": { "202": { "description": "Webhook replays queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayWebhookEventsByIdResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid replay request" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhook-events/summary": { "get": { "tags": [ "webhook_events" ], "summary": "Summarize webhook event state counts for a tenant (dashboard helper).", "operationId": "get_webhook_events_summary", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook event summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantWebhookEventSummary" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhook-events/{webhook_id}": { "get": { "tags": [ "webhook_events" ], "summary": "Get a single webhook event (includes payload).", "operationId": "get_webhook_event", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook event identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook event detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventDetail" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Webhook event not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhook-events/{webhook_id}/replay": { "post": { "tags": [ "webhook_events" ], "summary": "Replay a webhook event (operator tooling).", "operationId": "replay_webhook_event", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook event identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Webhook replay queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplayResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Webhook event not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "List registered webhooks for a tenant", "operationId": "list_webhooks", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of registered webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhooks/acp/orders": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming ACP (Agentic Commerce Protocol) webhooks", "description": "These come from ACP handlers when orders are placed via AI agents (ChatGPT, etc.)", "operationId": "handle_acp_order_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpOrderEventPayload" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhooks/amazon": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming Amazon SNS webhooks.", "description": "Amazon (SP-API) notifications are commonly delivered via SNS. This endpoint verifies the\nSNS signature using the signing certificate referenced in the message.", "operationId": "handle_amazon_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" }, "503": { "description": "Signature verification unavailable" } } } }, "/v1/tenants/{tenant_id}/webhooks/by-id/{webhook_id}": { "delete": { "tags": [ "webhooks" ], "summary": "Delete/deactivate a webhook", "operationId": "delete_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook deactivated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Webhook not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhooks/ebay": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming eBay webhooks.", "operationId": "handle_ebay_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } }, "/v1/tenants/{tenant_id}/webhooks/etsy": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming Etsy webhooks.", "operationId": "handle_etsy_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } }, "/v1/tenants/{tenant_id}/webhooks/register": { "post": { "tags": [ "webhooks" ], "summary": "Register a new webhook", "operationId": "register_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Webhook registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Tenant not found" } }, "security": [ { "api_key": [] } ] } }, "/v1/tenants/{tenant_id}/webhooks/shopify": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming Shopify webhooks", "operationId": "handle_shopify_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } }, "/v1/tenants/{tenant_id}/webhooks/shopware": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming Shopware webhooks.", "operationId": "handle_shopware_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } }, "/v1/tenants/{tenant_id}/webhooks/tiktok": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming TikTok Shop webhooks.", "operationId": "handle_tiktok_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } }, "/v1/tenants/{tenant_id}/webhooks/walmart": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming Walmart Marketplace webhooks.", "operationId": "handle_walmart_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } }, "/v1/tenants/{tenant_id}/webhooks/woocommerce": { "post": { "tags": [ "webhooks" ], "summary": "Handle incoming WooCommerce webhooks.", "operationId": "handle_woocommerce_webhook", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid request payload or signature" } } } } }, "components": { "schemas": { "AdminTenantSummary": { "type": "object", "required": [ "id", "enabled", "inMemory", "hasDbConfig", "status", "integrations", "apiKeys" ], "properties": { "apiKeys": { "$ref": "#/components/schemas/ApiKeyCounts" }, "displayName": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "hasDbConfig": { "type": "boolean", "description": "Whether a DB config blob exists (tenant can be loaded on boot)." }, "id": { "type": "string" }, "inMemory": { "type": "boolean", "description": "Whether this tenant is loaded into the running process." }, "integrations": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "description": "`active`, `pending_config`, `disabled`, `error`" } } }, "ApiKeyCounts": { "type": "object", "required": [ "total", "active" ], "properties": { "active": { "type": "integer", "format": "int64", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "BatchSyncChannelResult": { "type": "object", "required": [ "channel", "status" ], "properties": { "channel": { "type": "string" }, "error": { "type": "string", "nullable": true }, "jobId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" } } }, "BatchSyncRequest": { "type": "object", "description": "Request body for the batch sync trigger.", "required": [ "channels" ], "properties": { "channels": { "type": "array", "items": { "type": "string" }, "description": "Channels to sync. Accepts: shopify, netsuite, dcl, amazon, tiktok, walmart, ebay, etsy, woocommerce, shopware, inventory, products, returns." } } }, "BatchSyncResponse": { "type": "object", "description": "Response for the batch sync trigger.", "required": [ "results", "total", "queued", "failed" ], "properties": { "failed": { "type": "integer", "description": "How many failed to queue.", "minimum": 0 }, "queued": { "type": "integer", "description": "How many were successfully queued.", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchSyncChannelResult" }, "description": "One entry per requested channel with its job ID (or error reason)." }, "total": { "type": "integer", "description": "Total channels requested.", "minimum": 0 } } }, "BulkUpdateOnboardingActionItemRequest": { "type": "object", "required": [ "actionId", "status" ], "properties": { "actionId": { "type": "string" }, "note": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "One of: pending, in_progress, done, blocked" } } }, "BulkUpdateOnboardingActionsError": { "type": "object", "required": [ "actionId", "message" ], "properties": { "actionId": { "type": "string" }, "message": { "type": "string" } } }, "BulkUpdateOnboardingActionsRequest": { "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/BulkUpdateOnboardingActionItemRequest" } }, "skipUnknown": { "type": "boolean", "description": "When true, unknown actions are skipped instead of counted as failures.", "nullable": true } } }, "BulkUpdateOnboardingActionsResponse": { "type": "object", "required": [ "attempted", "updated", "failed", "skipped" ], "properties": { "attempted": { "type": "integer", "format": "int32", "minimum": 0 }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/BulkUpdateOnboardingActionsError" } }, "failed": { "type": "integer", "format": "int32", "minimum": 0 }, "skipped": { "type": "integer", "format": "int32", "minimum": 0 }, "updated": { "type": "integer", "format": "int32", "minimum": 0 } } }, "CreateOrderBatchError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } } }, "CreateOrderBatchResult": { "type": "object", "required": [ "index", "shopifyOrderId", "success", "action" ], "properties": { "action": { "type": "string", "description": "Result action:\n- `created_or_reused` for live writes.\n- `would_create` / `would_reuse_existing` for dry-run previews.\n- `failed` when validation or write fails." }, "error": { "allOf": [ { "$ref": "#/components/schemas/CreateOrderBatchError" } ], "nullable": true }, "index": { "type": "integer", "description": "Input index of this order in the original request array.", "minimum": 0 }, "shopifyOrderId": { "type": "string", "description": "Shopify order id from input." }, "statesetOrderId": { "type": "string", "format": "uuid", "description": "Created/reused StateSet order id on success.", "nullable": true }, "success": { "type": "boolean", "description": "True when creation succeeded (or was idempotently resolved)." } } }, "CreateOrderRequest": { "type": "object", "description": "Request to create a new order in StateSet", "required": [ "shopifyOrderId", "lineItems", "createdAt", "orderNumber" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Order creation timestamp" }, "externalOrderId": { "type": "string", "description": "Source order ID on the external channel/platform.", "nullable": true }, "externalPlatform": { "type": "string", "description": "External channel/platform for non-Shopify orders.", "nullable": true }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineItem" }, "description": "Order line items" }, "locationId": { "type": "string", "description": "Location ID for fulfillment", "nullable": true }, "netsuiteId": { "type": "string", "description": "NetSuite order ID if synced", "nullable": true }, "orderNumber": { "type": "string", "description": "Order number", "example": "M-1001" }, "shopifyOrderId": { "type": "string", "description": "Legacy canonical order ID field used by existing StateSet/order storage.\n\nFor non-Shopify channels, prefer also sending `externalPlatform` and\n`externalOrderId`; the orchestrator will store the canonical key as\n`{platform}:{externalOrderId}` while preserving backwards compatibility.", "example": "1234567890" }, "sourceOrderPayload": { "description": "Raw upstream order payload snapshot, persisted for downstream sync jobs.", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Order tags for filtering/categorization" }, "workflowId": { "type": "string", "format": "uuid", "description": "Workflow ID for tracking", "nullable": true } } }, "CreateOrderResponse": { "type": "object", "description": "Response after creating an order", "required": [ "statesetOrderId" ], "properties": { "statesetOrderId": { "type": "string", "format": "uuid", "description": "Unique StateSet order ID" } } }, "CreateOrdersBatchRequest": { "type": "object", "properties": { "dryRun": { "type": "boolean", "description": "Validate and preview batch execution without writing any orders." }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/CreateOrderRequest" }, "description": "Orders to create in sequence." }, "stopOnError": { "type": "boolean", "description": "Stop processing after the first failed item." } } }, "CreateOrdersBatchResponse": { "type": "object", "required": [ "total", "succeeded", "failed", "dryRun", "completed", "results" ], "properties": { "completed": { "type": "boolean", "description": "Whether every input entry was attempted." }, "dryRun": { "type": "boolean", "description": "True when the request executed in dry-run mode (no writes performed)." }, "failed": { "type": "integer", "description": "Number of failed orders.", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CreateOrderBatchResult" }, "description": "Per-order result details." }, "succeeded": { "type": "integer", "description": "Number of successfully created/reused orders.", "minimum": 0 }, "total": { "type": "integer", "description": "Number of input orders.", "minimum": 0 } } }, "CreateTenantRequest": { "type": "object", "required": [ "id" ], "properties": { "config": { "description": "Optional full TenantConfig JSON. When provided, the tenant is loaded immediately.", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "nullable": true }, "id": { "type": "string" } } }, "ExecuteToolRequest": { "type": "object", "required": [ "tool", "params" ], "properties": { "confirm": { "type": "boolean" }, "params": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "sessionId": { "type": "string", "nullable": true }, "tool": { "type": "string" } } }, "IntegrationConnectionTestResult": { "type": "object", "required": [ "integration", "configured", "success" ], "properties": { "configured": { "type": "boolean" }, "details": { "type": "string", "nullable": true }, "integration": { "type": "string" }, "latencyMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "success": { "type": "boolean" } } }, "JobDiagnosticsSummary": { "type": "object", "required": [ "total", "succeeded", "failed", "running", "queued" ], "properties": { "failed": { "type": "integer", "minimum": 0 }, "queued": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "JobInfo": { "type": "object", "required": [ "jobId", "tenantId", "jobType", "state", "createdAt", "retryCount", "maxRetries" ], "properties": { "claimedBy": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "jobId": { "type": "string", "format": "uuid" }, "jobType": { "$ref": "#/components/schemas/JobKind" }, "leaseExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "maxRetries": { "type": "integer", "format": "int32" }, "nextRetryAt": { "type": "string", "format": "date-time", "nullable": true }, "result": { "nullable": true }, "retryCount": { "type": "integer", "format": "int32" }, "scheduleId": { "type": "string", "format": "uuid", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "state": { "$ref": "#/components/schemas/JobState" }, "tenantId": { "type": "string" } } }, "JobThroughputBucket": { "type": "object", "required": [ "bucketStart", "jobsCreated", "jobsSucceeded", "jobsFailed", "jobsFinished" ], "properties": { "bucketStart": { "type": "string", "format": "date-time" }, "jobsCreated": { "type": "integer", "format": "int64", "minimum": 0 }, "jobsFailed": { "type": "integer", "format": "int64", "minimum": 0 }, "jobsFinished": { "type": "integer", "format": "int64", "minimum": 0 }, "jobsSucceeded": { "type": "integer", "format": "int64", "minimum": 0 } } }, "JobThroughputResponse": { "type": "object", "required": [ "tenantId", "generatedAt", "windowHours", "bucketMinutes", "scannedJobs", "partial", "buckets", "totals" ], "properties": { "bucketMinutes": { "type": "integer", "format": "int32", "minimum": 0 }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/JobThroughputBucket" } }, "generatedAt": { "type": "string", "format": "date-time" }, "partial": { "type": "boolean" }, "scannedJobs": { "type": "integer", "format": "int64", "minimum": 0 }, "tenantId": { "type": "string" }, "totalJobsHint": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "totals": { "$ref": "#/components/schemas/JobThroughputTotals" }, "windowHours": { "type": "integer", "format": "int32", "minimum": 0 } } }, "JobThroughputTotals": { "type": "object", "required": [ "jobsCreated", "jobsSucceeded", "jobsFailed", "jobsFinished" ], "properties": { "jobsCreated": { "type": "integer", "format": "int64", "minimum": 0 }, "jobsFailed": { "type": "integer", "format": "int64", "minimum": 0 }, "jobsFinished": { "type": "integer", "format": "int64", "minimum": 0 }, "jobsSucceeded": { "type": "integer", "format": "int64", "minimum": 0 } } }, "McpError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "nullable": true }, "message": { "type": "string" } } }, "McpRequest": { "type": "object", "required": [ "method" ], "properties": { "id": { "nullable": true }, "jsonrpc": { "type": "string" }, "method": { "type": "string" }, "params": {} } }, "McpResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/McpError" } ], "nullable": true }, "id": { "nullable": true }, "jsonrpc": { "type": "string" }, "result": { "nullable": true } } }, "OnboardingActionHistoryEntry": { "type": "object", "required": [ "id", "tenantId", "actionId", "status", "updatedAt" ], "properties": { "actionId": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "note": { "type": "string", "nullable": true }, "previousStatus": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string", "nullable": true } } }, "OnboardingActionHistoryQuery": { "type": "object", "properties": { "actionId": { "type": "string", "nullable": true }, "limit": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } }, "OnboardingActionItem": { "type": "object", "required": [ "id", "title", "priority", "category", "required", "completed", "workflowStatus" ], "properties": { "apiEndpoint": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Logical bucket for grouping/remediation workflows." }, "completed": { "type": "boolean" }, "details": { "type": "string", "nullable": true }, "docsPath": { "type": "string", "nullable": true }, "id": { "type": "string" }, "note": { "type": "string", "nullable": true }, "priority": { "type": "string", "description": "Priority bucket: `p0`, `p1`, `p2`, `p3`." }, "required": { "type": "boolean" }, "title": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedBy": { "type": "string", "nullable": true }, "workflowStatus": { "type": "string", "description": "Operator workflow status: `pending`, `in_progress`, `done`, `blocked`." } } }, "OnboardingActionState": { "type": "object", "required": [ "tenantId", "actionId", "status", "updatedAt" ], "properties": { "actionId": { "type": "string" }, "note": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string", "nullable": true } } }, "OnboardingGuideReadiness": { "type": "object", "required": [ "id", "title", "docPath", "ready" ], "properties": { "docPath": { "type": "string", "description": "Relative documentation path in this repository." }, "id": { "type": "string", "description": "Stable guide identifier." }, "missingRequirements": { "type": "array", "items": { "type": "string" } }, "ready": { "type": "boolean", "description": "Whether this guide can be executed immediately with current tenant configuration." }, "title": { "type": "string" } } }, "OnboardingPortfolioQuery": { "type": "object", "properties": { "hasBlockers": { "type": "boolean", "description": "Optional blocker filter: true = only tenants with blockers, false = only without blockers.", "nullable": true }, "highRiskThreshold": { "type": "integer", "format": "int32", "description": "Threshold used to count high-risk tenants in summary (default 70).", "nullable": true, "minimum": 0 }, "includeIntegrationTests": { "type": "boolean", "description": "When true, executes live integration health checks per tenant.\nThis can increase latency significantly for large tenant sets.", "nullable": true }, "integration": { "type": "string", "description": "Optional integration filter (e.g., `shopify`, `netsuite`, `dcl`).", "nullable": true }, "minBlockedActionAgeHours": { "type": "integer", "format": "int64", "description": "Optional minimum age (hours) for oldest blocked action filter.", "nullable": true, "minimum": 0 }, "minRiskScore": { "type": "integer", "format": "int32", "description": "Optional minimum risk score filter (0-100).", "nullable": true, "minimum": 0 }, "overdueGoLive": { "type": "boolean", "description": "Optional go-live filter: true = only overdue go-live targets, false = only non-overdue.", "nullable": true }, "ownerAssigned": { "type": "boolean", "description": "Optional ownership filter: true = only assigned owners, false = only unassigned.", "nullable": true }, "readinessStatus": { "type": "string", "description": "Optional readiness status filter: `ready`, `attention_required`, `not_ready`.", "nullable": true }, "sortBy": { "type": "string", "description": "Sort key: `risk`, `score`, or `tenant_id` (default `risk`).", "nullable": true }, "sortOrder": { "type": "string", "description": "Sort direction: `asc` or `desc` (default `desc`).", "nullable": true }, "staleBlockerHoursThreshold": { "type": "integer", "format": "int64", "description": "Threshold used to count stale-blocker tenants in summary (default 24h).", "nullable": true, "minimum": 0 } } }, "OnboardingPortfolioSummary": { "type": "object", "required": [ "generatedAt", "includeIntegrationTests", "highRiskThreshold", "staleBlockerHoursThreshold", "totalTenants", "readyTenants", "attentionRequiredTenants", "notReadyTenants", "highRiskTenants", "staleBlockerTenants", "unassignedOwnerTenants", "overdueGoLiveTenants" ], "properties": { "attentionRequiredTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "generatedAt": { "type": "string", "format": "date-time" }, "highRiskTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "highRiskThreshold": { "type": "integer", "format": "int32", "minimum": 0 }, "includeIntegrationTests": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenantOnboardingPortfolioItem" } }, "notReadyTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "overdueGoLiveTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "readyTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "staleBlockerHoursThreshold": { "type": "integer", "format": "int64", "minimum": 0 }, "staleBlockerTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "totalTenants": { "type": "integer", "format": "int32", "minimum": 0 }, "unassignedOwnerTenants": { "type": "integer", "format": "int32", "minimum": 0 } } }, "OnboardingReadinessCheck": { "type": "object", "required": [ "id", "label", "status", "required" ], "properties": { "details": { "type": "string", "nullable": true }, "id": { "type": "string", "description": "Stable identifier for automation and dashboard rendering." }, "label": { "type": "string", "description": "Human-readable check title." }, "required": { "type": "boolean", "description": "Whether this check must pass for production onboarding readiness." }, "status": { "type": "string", "description": "`pass`, `warn`, or `fail`." } } }, "SyncAllRequest": { "type": "object", "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SyncChannel" }, "description": "Ordered list of channels to run. If omitted, the server uses direction defaults." }, "direction": { "$ref": "#/components/schemas/SyncDirection" }, "failFast": { "type": "boolean", "description": "Stop immediately when a step fails." }, "includeInventory": { "type": "boolean", "description": "Run inventory synchronization after channel sync." }, "productSource": { "type": "string", "description": "Restrict catalog sync source: shopify | netsuite | both | all.", "nullable": true } } }, "SyncChannel": { "type": "string", "enum": [ "shopify", "netsuite", "dcl", "capacity", "fishbowl", "luminous", "stateset_api", "amazon", "tiktok", "walmart", "ebay", "etsy", "woocommerce", "shopware", "bigcommerce", "adobe_commerce", "mercadolibre", "alibaba", "rakuten", "zalando", "shopee", "lazada", "coupang", "flipkart", "shein", "temu", "products" ] }, "SyncDirection": { "type": "string", "enum": [ "all", "inbound", "outbound" ] }, "TenantDiagnostics": { "type": "object", "description": "One-stop troubleshooting endpoint for a tenant.", "required": [ "tenantId", "inMemory", "integrations", "circuitBreakers", "apiKeyCount", "recentJobs" ], "properties": { "apiKeyCount": { "type": "integer", "format": "int64", "minimum": 0 }, "circuitBreakers": { "type": "object", "additionalProperties": { "type": "string" } }, "inMemory": { "type": "boolean" }, "integrations": { "type": "array", "items": { "type": "string" } }, "recentJobs": { "$ref": "#/components/schemas/JobDiagnosticsSummary" }, "scheduleCount": { "type": "integer", "format": "int64", "nullable": true }, "tenantId": { "type": "string" } } }, "TenantOnboardingActionHistory": { "type": "object", "required": [ "tenantId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingActionHistoryEntry" } }, "tenantId": { "type": "string" } } }, "TenantOnboardingActionPlan": { "type": "object", "required": [ "tenantId", "generatedAt", "readinessStatus", "readinessScore", "readinessGrade", "totalActions", "completedActions", "remainingActions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingActionItem" } }, "completedActions": { "type": "integer", "format": "int32", "minimum": 0 }, "generatedAt": { "type": "string", "format": "date-time" }, "readinessGrade": { "type": "string" }, "readinessScore": { "type": "integer", "format": "int32", "minimum": 0 }, "readinessStatus": { "type": "string" }, "remainingActions": { "type": "integer", "format": "int32", "minimum": 0 }, "tenantId": { "type": "string" }, "totalActions": { "type": "integer", "format": "int32", "minimum": 0 } } }, "TenantOnboardingPortfolioItem": { "type": "object", "required": [ "tenantId", "tenantStatus", "enabled", "inMemory", "readinessStatus", "readinessScore", "readinessGrade", "riskScore", "requiredFailures", "requiredWarnings", "blockedActions", "inProgressActions", "pendingActions", "doneActions" ], "properties": { "blockedActions": { "type": "integer", "format": "int32", "minimum": 0 }, "blockers": { "type": "array", "items": { "type": "string" } }, "displayName": { "type": "string", "nullable": true }, "doneActions": { "type": "integer", "format": "int32", "minimum": 0 }, "enabled": { "type": "boolean" }, "goLiveTargetAt": { "type": "string", "format": "date-time", "nullable": true }, "goLiveTargetDaysRemaining": { "type": "integer", "format": "int64", "nullable": true }, "inMemory": { "type": "boolean" }, "inProgressActions": { "type": "integer", "format": "int32", "minimum": 0 }, "integrations": { "type": "array", "items": { "type": "string" } }, "nextActionId": { "type": "string", "nullable": true }, "nextActionTitle": { "type": "string", "nullable": true }, "oldestBlockedActionAgeHours": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "oldestBlockedActionAt": { "type": "string", "format": "date-time", "nullable": true }, "ownerEmail": { "type": "string", "nullable": true }, "ownerName": { "type": "string", "nullable": true }, "pendingActions": { "type": "integer", "format": "int32", "minimum": 0 }, "profileNotes": { "type": "string", "nullable": true }, "readinessGrade": { "type": "string" }, "readinessScore": { "type": "integer", "format": "int32", "minimum": 0 }, "readinessStatus": { "type": "string" }, "requiredFailures": { "type": "integer", "format": "int32", "minimum": 0 }, "requiredWarnings": { "type": "integer", "format": "int32", "minimum": 0 }, "riskScore": { "type": "integer", "format": "int32", "description": "0-100 risk score, where higher means higher operational risk.", "minimum": 0 }, "tenantId": { "type": "string" }, "tenantStatus": { "type": "string" } } }, "TenantOnboardingProfile": { "type": "object", "required": [ "tenantId", "updatedAt" ], "properties": { "goLiveTargetAt": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "nullable": true }, "ownerEmail": { "type": "string", "nullable": true }, "ownerName": { "type": "string", "nullable": true }, "primaryIntegration": { "type": "string", "nullable": true }, "syncDirection": { "type": "string", "nullable": true }, "syncEntities": { "type": "array", "items": { "type": "string" } }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string", "nullable": true } } }, "TenantOnboardingReadinessReport": { "type": "object", "required": [ "tenantId", "generatedAt", "overallStatus", "score", "grade" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingReadinessCheck" } }, "configuredIntegrations": { "type": "array", "items": { "type": "string" } }, "generatedAt": { "type": "string", "format": "date-time" }, "grade": { "type": "string", "description": "Letter grade (e.g., `A+`, `B`, `C-`)." }, "guides": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingGuideReadiness" } }, "integrationTests": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationConnectionTestResult" } }, "overallStatus": { "type": "string", "description": "`ready`, `attention_required`, `not_ready`" }, "score": { "type": "integer", "format": "int32", "description": "0-100 readiness score.", "minimum": 0 }, "tenantId": { "type": "string" } } }, "UpdateOnboardingActionRequest": { "type": "object", "required": [ "status" ], "properties": { "note": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "One of: pending, in_progress, done, blocked" } } }, "UpdateTenantRequest": { "type": "object", "properties": { "config": { "nullable": true }, "displayName": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "nullable": true } } }, "UpsertTenantOnboardingProfileRequest": { "type": "object", "properties": { "goLiveTargetAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "ownerEmail": { "type": "string", "nullable": true }, "ownerName": { "type": "string", "nullable": true }, "primaryIntegration": { "type": "string", "nullable": true }, "syncDirection": { "type": "string", "nullable": true }, "syncEntities": { "type": "array", "items": { "type": "string" }, "nullable": true } } } }, "securitySchemes": { "admin_key": { "type": "apiKey", "in": "header", "name": "x-stateset-admin-key", "description": "Platform admin key. Send as the `x-stateset-admin-key` header." }, "api_key": { "type": "apiKey", "in": "header", "name": "x-stateset-api-key", "description": "Tenant API key. Send as the `x-stateset-api-key` header." }, "bearer_auth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "servers": [ { "url": "https://api.sync.stateset.com" } ] }