{
  "openapi": "3.0.0",
  "info": {
    "title": "BetterData SCM API",
    "version": "1.0.0",
    "description": "Complete API documentation for BetterData's Supply Chain Management platform. Build powerful integrations with our REST APIs for forecasting, inventory, transfers, planning, and operations.",
    "contact": {
      "name": "BetterData Support",
      "email": "support@betterdata.co",
      "url": "https://betterdata.co/company/contact"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3000/api",
      "description": "Production API"
    },
    {
      "url": "http://localhost:3000/api",
      "description": "Local Development"
    },
    {
      "url": "https://api.betterdata.co/api",
      "description": "Production API"
    }
  ],
  "tags": [
    {
      "name": "Products",
      "description": "Product and catalog management"
    },
    {
      "name": "Inventory",
      "description": "Inventory levels, adjustments, and analytics"
    },
    {
      "name": "Forecasting",
      "description": "Demand forecasting and scenarios"
    },
    {
      "name": "Transfers",
      "description": "Transfer recommendations and execution"
    },
    {
      "name": "Planning",
      "description": "Planning recommendations and KPIs"
    },
    {
      "name": "Shipments",
      "description": "Shipment management and tracking"
    },
    {
      "name": "Wholesale Bookings",
      "description": "Wholesale booking management"
    },
    {
      "name": "Dashboard",
      "description": "Dashboard widgets and layouts"
    },
    {
      "name": "Reports",
      "description": "Analytics and reporting endpoints"
    },
    {
      "name": "Alerts",
      "description": "Alert configuration and management"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "List Products",
        "description": "Get a list of products for the authenticated organization",
        "operationId": "listProducts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            },
            "description": "Items per page"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "Create Product",
        "description": "Create a new product",
        "operationId": "createProduct",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateProductRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Product created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "Get Product",
        "description": "Get a specific product by ID",
        "operationId": "getProduct",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      },
      "patch": {
        "tags": [
          "Products"
        ],
        "summary": "Update Product",
        "description": "Update a product",
        "operationId": "updateProduct",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateProductRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Product updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/forecast/scenarios": {
      "get": {
        "tags": [
          "Forecasting"
        ],
        "summary": "List Forecast Scenarios",
        "description": "Get list of forecast scenarios",
        "operationId": "listForecastScenarios",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of scenarios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ForecastScenario"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Forecasting"
        ],
        "summary": "Create Forecast Scenario",
        "description": "Create a new forecast scenario",
        "operationId": "createForecastScenario",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateForecastScenarioRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scenario created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastScenario"
                }
              }
            }
          }
        }
      }
    },
    "/transfers/recommendations": {
      "get": {
        "tags": [
          "Transfers"
        ],
        "summary": "List Transfer Recommendations",
        "description": "Get transfer recommendations",
        "operationId": "listTransferRecommendations",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "rejected",
                "executed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TransferRecommendation"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/transfers/recommendations/{id}/approve": {
      "post": {
        "tags": [
          "Transfers"
        ],
        "summary": "Approve Transfer Recommendation",
        "description": "Approve a transfer recommendation",
        "operationId": "approveTransferRecommendation",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommendation approved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferRecommendation"
                }
              }
            }
          }
        }
      }
    },
    "/dashboard/widgets/inventory-summary": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Get Inventory Summary Widget",
        "description": "Get inventory summary data for dashboard widget",
        "operationId": "getInventorySummaryWidget",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "locationId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inventory summary data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventorySummary"
                }
              }
            }
          }
        }
      }
    },
    "/reports/expiry-risk": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Get Expiry Risk Report",
        "description": "Get expiry risk and action report",
        "operationId": "getExpiryRiskReport",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "locationId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expiry risk report data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ExpiryRiskItem"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/planning/recommendations": {
      "get": {
        "tags": [
          "Planning"
        ],
        "summary": "Get Planning Recommendations",
        "description": "Get planning recommendations and KPIs",
        "operationId": "getPlanningRecommendations",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "locationId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Planning recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlanningRecommendation"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/inventory": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "List Inventory Items",
        "description": "Get a list of inventory items with search and filtering",
        "operationId": "listInventory",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            },
            "description": "Maximum number of results"
          },
          {
            "name": "locationId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by location"
          }
        ],
        "responses": {
          "200": {
            "description": "List of inventory items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InventoryItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/inventory/channel-location": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "Get Channel-Location Inventory",
        "description": "Get inventory levels by channel and location",
        "operationId": "getChannelLocationInventory",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "locationId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Location ID"
          },
          {
            "name": "channelId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Channel ID"
          },
          {
            "name": "sku",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Product SKU"
          }
        ],
        "responses": {
          "200": {
            "description": "Channel-location inventory data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChannelLocationInventory"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required parameter"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/inventory/availability": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "Check Inventory Availability",
        "description": "Get inventory availability (ATP - Available to Promise) with optional filters",
        "operationId": "getInventoryAvailability",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "locationId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by location"
          },
          {
            "name": "productMasterId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by product"
          },
          {
            "name": "lotId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by lot"
          },
          {
            "name": "binId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by bin"
          },
          {
            "name": "includeExpired",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include expired stock"
          },
          {
            "name": "includeRecalled",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include recalled stock"
          },
          {
            "name": "includeOnHold",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include held stock"
          },
          {
            "name": "summary",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Return aggregated summary instead of stock lines"
          },
          {
            "name": "includeStockLines",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include stock lines when summary=true"
          }
        ],
        "responses": {
          "200": {
            "description": "Availability data",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "summary"
                          ]
                        },
                        "data": {
                          "$ref": "#/components/schemas/AvailabilitySummary"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "stockLines"
                          ]
                        },
                        "count": {
                          "type": "integer"
                        },
                        "totals": {
                          "$ref": "#/components/schemas/AvailabilityTotals"
                        },
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/StockLine"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/inventory/availability/check": {
      "post": {
        "tags": [
          "Inventory"
        ],
        "summary": "Batch Availability Check",
        "description": "Check availability for multiple items at once",
        "operationId": "checkInventoryAvailability",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "sku",
                        "locationId",
                        "quantity"
                      ],
                      "properties": {
                        "sku": {
                          "type": "string"
                        },
                        "locationId": {
                          "type": "string"
                        },
                        "quantity": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Availability check results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AvailabilityCheckResult"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/inventory/adjustments": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "Get Adjustment History",
        "description": "Get stock history and adjustment records",
        "operationId": "getAdjustmentHistory",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "inventoryItemId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by inventory item"
          },
          {
            "name": "productMasterId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by product"
          },
          {
            "name": "locationId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by location"
          },
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Filter from date"
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Filter to date"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Maximum results"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Offset for pagination"
          }
        ],
        "responses": {
          "200": {
            "description": "Adjustment history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StockHistoryEntry"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Inventory"
        ],
        "summary": "Create Inventory Adjustment",
        "description": "Adjust inventory quantity for a stock line",
        "operationId": "createInventoryAdjustment",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "inventoryItemId",
                  "newQtyOnHand",
                  "reasonCodeId"
                ],
                "properties": {
                  "inventoryItemId": {
                    "type": "string"
                  },
                  "newQtyOnHand": {
                    "type": "number"
                  },
                  "reasonCodeId": {
                    "type": "string"
                  },
                  "comment": {
                    "type": "string"
                  },
                  "rootCause": {
                    "type": "string",
                    "description": "Required for healthcare large negative adjustments"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Adjustment created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "transaction": {
                      "$ref": "#/components/schemas/StockTransaction"
                    },
                    "inventoryItem": {
                      "$ref": "#/components/schemas/InventoryItem"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or adjustment failed"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/inventory/cycle-count": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "Get Cycle Count Data",
        "description": "Get cycle count data (products, batches, or suggestions)",
        "operationId": "getCycleCountData",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "locationId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Location ID (required unless mode=abc-config)"
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all-products",
                "batches",
                "to-resolve",
                "suggestions",
                "abc-config"
              ],
              "default": "all-products"
            },
            "description": "Data mode"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search filter (for all-products mode)"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Batch status filter (for batches mode)"
          }
        ],
        "responses": {
          "200": {
            "description": "Cycle count data",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "all-products"
                          ]
                        },
                        "products": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CycleCountProduct"
                          }
                        },
                        "count": {
                          "type": "integer"
                        },
                        "overdueCount": {
                          "type": "integer"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "batches"
                          ]
                        },
                        "batches": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CycleCountBatch"
                          }
                        },
                        "count": {
                          "type": "integer"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing required parameter"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/inventory-levels": {
      "post": {
        "tags": [
          "Inventory"
        ],
        "summary": "Create Inventory Level",
        "description": "Create or update inventory level (min/max/reorder quantities)",
        "operationId": "createInventoryLevel",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "productMasterId",
                  "locationId"
                ],
                "properties": {
                  "productMasterId": {
                    "type": "string",
                    "description": "Product Master ID (or productId for legacy)"
                  },
                  "productId": {
                    "type": "string",
                    "description": "Legacy Product ID (deprecated)"
                  },
                  "locationId": {
                    "type": "string"
                  },
                  "minQuantity": {
                    "type": "number",
                    "description": "Minimum quantity (must be ≤ reorder ≤ max)"
                  },
                  "reorderQuantity": {
                    "type": "number",
                    "description": "Reorder point (must be ≥ min and ≤ max)"
                  },
                  "maxQuantity": {
                    "type": "number",
                    "description": "Maximum quantity (must be ≥ reorder)"
                  },
                  "status": {
                    "type": "string",
                    "default": "Supported"
                  },
                  "abcClass": {
                    "type": "string"
                  },
                  "expectedLeadTimeDays": {
                    "type": "integer"
                  },
                  "replenishmentPeriodDays": {
                    "type": "integer"
                  },
                  "forecastPeriodDays": {
                    "type": "integer"
                  },
                  "forecastQuantity": {
                    "type": "number"
                  },
                  "preferredBinLocationId": {
                    "type": "string"
                  },
                  "replenishmentLocationId": {
                    "type": "string"
                  },
                  "comments": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inventory level created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryLevel"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g., min > reorder > max)"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Product or location not found"
          }
        }
      }
    },
    "/inventory-levels/{id}": {
      "patch": {
        "tags": [
          "Inventory"
        ],
        "summary": "Update Inventory Level",
        "description": "Update inventory level settings",
        "operationId": "updateInventoryLevel",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "minQuantity": {
                    "type": "number"
                  },
                  "reorderQuantity": {
                    "type": "number"
                  },
                  "maxQuantity": {
                    "type": "number"
                  },
                  "status": {
                    "type": "string"
                  },
                  "abcClass": {
                    "type": "string"
                  },
                  "comments": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inventory level updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryLevel"
                }
              }
            }
          },
          "404": {
            "description": "Inventory level not found"
          }
        }
      },
      "delete": {
        "tags": [
          "Inventory"
        ],
        "summary": "Delete Inventory Level",
        "description": "Delete an inventory level",
        "operationId": "deleteInventoryLevel",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inventory level deleted"
          },
          "404": {
            "description": "Inventory level not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API key or JWT token. Get your API key from Admin → Integrations → API Keys"
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "organizationId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateProductRequest": {
        "type": "object",
        "required": [
          "sku",
          "name"
        ],
        "properties": {
          "sku": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "UpdateProductRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "InventoryLevel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "productMasterId": {
            "type": "string"
          },
          "productId": {
            "type": "string",
            "description": "Legacy field"
          },
          "locationId": {
            "type": "string"
          },
          "inventoryId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "default": "Supported"
          },
          "abcClass": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C"
            ]
          },
          "minQuantity": {
            "type": "number"
          },
          "reorderQuantity": {
            "type": "number"
          },
          "maxQuantity": {
            "type": "number"
          },
          "expectedLeadTimeDays": {
            "type": "integer"
          },
          "replenishmentPeriodDays": {
            "type": "integer"
          },
          "forecastPeriodDays": {
            "type": "integer"
          },
          "forecastQuantity": {
            "type": "number"
          },
          "preferredBinLocationId": {
            "type": "string"
          },
          "replenishmentLocationId": {
            "type": "string"
          },
          "comments": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "productMaster": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "globalSku": {
                "type": "string"
              },
              "productName": {
                "type": "string"
              }
            }
          }
        }
      },
      "ForecastScenario": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateForecastScenarioRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "TransferRecommendation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "fromLocationId": {
            "type": "string"
          },
          "toLocationId": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "executed"
            ]
          }
        }
      },
      "InventorySummary": {
        "type": "object",
        "properties": {
          "totalValue": {
            "type": "number"
          },
          "quantityOnHand": {
            "type": "integer"
          },
          "quantityAvailable": {
            "type": "integer"
          },
          "quantityReserved": {
            "type": "integer"
          }
        }
      },
      "ExpiryRiskItem": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string"
          },
          "lotNumber": {
            "type": "string"
          },
          "expiryDate": {
            "type": "string",
            "format": "date"
          },
          "quantity": {
            "type": "integer"
          },
          "daysUntilExpiry": {
            "type": "integer"
          }
        }
      },
      "PlanningRecommendation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "recommendation": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "totalPages": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "InventoryItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "productId": {
            "type": "string"
          },
          "productMasterId": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "lotId": {
            "type": "string"
          },
          "binId": {
            "type": "string"
          },
          "qtyOnHand": {
            "type": "number"
          },
          "qtyAvailable": {
            "type": "number"
          },
          "qtyReserved": {
            "type": "number"
          },
          "expiryDate": {
            "type": "string",
            "format": "date"
          },
          "abcClass": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C"
            ]
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          }
        }
      },
      "ChannelLocationInventory": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "channelId": {
            "type": "string"
          },
          "quantityOnHand": {
            "type": "integer"
          },
          "quantityAvailable": {
            "type": "integer"
          },
          "quantityReserved": {
            "type": "integer"
          }
        }
      },
      "StockLine": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "productMasterId": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "lotId": {
            "type": "string"
          },
          "binId": {
            "type": "string"
          },
          "qtyOnHand": {
            "type": "number"
          },
          "qtyAvailable": {
            "type": "number"
          },
          "qtyOnHold": {
            "type": "number"
          },
          "qtyPicked": {
            "type": "number"
          },
          "qtyRecalled": {
            "type": "number"
          },
          "qtyExpired": {
            "type": "number"
          }
        }
      },
      "AvailabilitySummary": {
        "type": "object",
        "properties": {
          "productMasterId": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "totalOnHand": {
            "type": "number"
          },
          "totalAvailable": {
            "type": "number"
          },
          "totalOnHold": {
            "type": "number"
          },
          "totalPicked": {
            "type": "number"
          },
          "stockLines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockLine"
            }
          }
        }
      },
      "AvailabilityTotals": {
        "type": "object",
        "properties": {
          "totalOnHand": {
            "type": "number"
          },
          "totalAvailable": {
            "type": "number"
          },
          "totalOnHold": {
            "type": "number"
          },
          "totalPicked": {
            "type": "number"
          },
          "totalRecalled": {
            "type": "number"
          },
          "totalExpired": {
            "type": "number"
          }
        }
      },
      "AvailabilityCheckResult": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "requestedQuantity": {
            "type": "number"
          },
          "availableQuantity": {
            "type": "number"
          },
          "isAvailable": {
            "type": "boolean"
          }
        }
      },
      "StockHistoryEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "inventoryItemId": {
            "type": "string"
          },
          "transactionType": {
            "type": "string"
          },
          "deltaQty": {
            "type": "number"
          },
          "qtyBefore": {
            "type": "number"
          },
          "qtyAfter": {
            "type": "number"
          },
          "reasonCode": {
            "type": "string"
          },
          "comment": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          }
        }
      },
      "StockTransaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "inventoryItemId": {
            "type": "string"
          },
          "transactionType": {
            "type": "string"
          },
          "deltaQty": {
            "type": "number"
          },
          "reasonCodeId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CycleCountProduct": {
        "type": "object",
        "properties": {
          "productMasterId": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "productName": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "lastCountedDate": {
            "type": "string",
            "format": "date"
          },
          "nextCountDate": {
            "type": "string",
            "format": "date"
          },
          "isOverdue": {
            "type": "boolean"
          },
          "abcClass": {
            "type": "string"
          },
          "currentQty": {
            "type": "number"
          }
        }
      },
      "CycleCountBatch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "assigneeId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "itemCount": {
            "type": "integer"
          }
        }
      }
    }
  }
}