{ "openapi": "3.0.0", "paths": { "/v1/organizations/{organizationId}/products": { "post": { "description": "API key scope: products:write.", "operationId": "ProductsController_create", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductDto" } } } }, "responses": { "201": { "description": "Product created.", "content": { "application/json": { "example": { "id": "22222222-2222-4222-8222-222222222222", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M", "barcode": "7891234567890", "baseUnitCode": "EA", "status": "active", "metadata": { "color": "black", "size": "M" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/ProductResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create a product in the selected organization", "tags": [ "Products" ] }, "get": { "description": "API key scope: products:read.", "operationId": "ProductsController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "sku", "required": false, "in": "query", "schema": { "example": "TSHIRT-BLACK-M", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "t-shirt", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Product id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Products page.", "content": { "application/json": { "example": { "items": [ { "id": "22222222-2222-4222-8222-222222222222", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M", "barcode": "7891234567890", "baseUnitCode": "EA", "status": "active", "metadata": { "color": "black", "size": "M" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/ProductsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List products in the selected organization", "tags": [ "Products" ] } }, "/v1/organizations/{organizationId}/products/{productId}": { "get": { "description": "API key scope: products:read.", "operationId": "ProductsController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product found.", "content": { "application/json": { "example": { "id": "22222222-2222-4222-8222-222222222222", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M", "barcode": "7891234567890", "baseUnitCode": "EA", "status": "active", "metadata": { "color": "black", "size": "M" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/ProductResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a product in the selected organization", "tags": [ "Products" ] }, "patch": { "description": "API key scope: products:write.", "operationId": "ProductsController_update", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductDto" } } } }, "responses": { "200": { "description": "Product updated.", "content": { "application/json": { "example": { "id": "22222222-2222-4222-8222-222222222222", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M", "barcode": "7891234567890", "baseUnitCode": "EA", "status": "active", "metadata": { "color": "black", "size": "M" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/ProductResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update a product in the selected organization", "tags": [ "Products" ] } }, "/v1/organizations/{organizationId}/products/{productId}/composition": { "get": { "description": "API key scope: products:read.", "operationId": "ProductsController_findComposition", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product composition found, or null when not configured.", "content": { "application/json": { "example": { "id": "23232323-2323-4232-8232-232323232323", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "kind": "kit", "status": "active", "metadata": { "sellableAs": "bundle" }, "components": [ { "id": "24242424-2424-4242-8242-242424242424", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "compositionId": "23232323-2323-4232-8232-232323232323", "componentProductId": "25252525-2525-4252-8252-252525252525", "quantityInBaseUnits": 2, "componentProduct": { "id": "25252525-2525-4252-8252-252525252525", "name": "Bundle component", "sku": "COMPONENT-001" }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" } ], "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ProductCompositionResponseDto" } ], "nullable": true } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a product composition", "tags": [ "Products" ] }, "put": { "description": "API key scope: products:write.", "operationId": "ProductsController_upsertComposition", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertProductCompositionDto" } } } }, "responses": { "200": { "description": "Product composition created or replaced.", "content": { "application/json": { "example": { "id": "23232323-2323-4232-8232-232323232323", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "kind": "kit", "status": "active", "metadata": { "sellableAs": "bundle" }, "components": [ { "id": "24242424-2424-4242-8242-242424242424", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "compositionId": "23232323-2323-4232-8232-232323232323", "componentProductId": "25252525-2525-4252-8252-252525252525", "quantityInBaseUnits": 2, "componentProduct": { "id": "25252525-2525-4252-8252-252525252525", "name": "Bundle component", "sku": "COMPONENT-001" }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" } ], "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/ProductCompositionResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create or replace a product composition", "tags": [ "Products" ] } }, "/v1/organizations/{organizationId}/locations": { "post": { "description": "API key scope: inventory:write.", "operationId": "LocationsController_create", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLocationDto" } } } }, "responses": { "201": { "description": "Location created.", "content": { "application/json": { "example": { "id": "33333333-3333-4333-8333-333333333333", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse", "status": "active", "addressLine1": "123 Market St", "addressLine2": null, "city": "Austin", "region": "TX", "postalCode": "78701", "countryCode": "US", "metadata": { "timezone": "America/Chicago" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/LocationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create a location in the selected organization", "tags": [ "Locations" ] }, "get": { "description": "API key scope: inventory:read.", "operationId": "LocationsController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "code", "required": false, "in": "query", "schema": { "example": "MAIN-WH", "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "warehouse", "store", "virtual" ] } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "warehouse", "type": "string" } }, { "name": "city", "required": false, "in": "query", "schema": { "example": "Austin", "type": "string" } }, { "name": "region", "required": false, "in": "query", "schema": { "example": "TX", "type": "string" } }, { "name": "countryCode", "required": false, "in": "query", "schema": { "minLength": 2, "maxLength": 2, "example": "US", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Location id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Locations page.", "content": { "application/json": { "example": { "items": [ { "id": "33333333-3333-4333-8333-333333333333", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse", "status": "active", "addressLine1": "123 Market St", "addressLine2": null, "city": "Austin", "region": "TX", "postalCode": "78701", "countryCode": "US", "metadata": { "timezone": "America/Chicago" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/LocationsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List locations in the selected organization", "tags": [ "Locations" ] } }, "/v1/organizations/{organizationId}/locations/{locationId}": { "get": { "description": "API key scope: inventory:read.", "operationId": "LocationsController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "locationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Location found.", "content": { "application/json": { "example": { "id": "33333333-3333-4333-8333-333333333333", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse", "status": "active", "addressLine1": "123 Market St", "addressLine2": null, "city": "Austin", "region": "TX", "postalCode": "78701", "countryCode": "US", "metadata": { "timezone": "America/Chicago" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/LocationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a location in the selected organization", "tags": [ "Locations" ] }, "patch": { "description": "API key scope: inventory:write.", "operationId": "LocationsController_update", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "locationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLocationDto" } } } }, "responses": { "200": { "description": "Location updated.", "content": { "application/json": { "example": { "id": "33333333-3333-4333-8333-333333333333", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse", "status": "active", "addressLine1": "123 Market St", "addressLine2": null, "city": "Austin", "region": "TX", "postalCode": "78701", "countryCode": "US", "metadata": { "timezone": "America/Chicago" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/LocationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update a location in the selected organization", "tags": [ "Locations" ] } }, "/v1/organizations/{organizationId}/inventory-owners": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventorySegmentsController_listOwners", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": false, "in": "query", "schema": { "example": "DEFAULT", "type": "string" } } ], "responses": { "200": { "description": "Inventory owners page.", "content": { "application/json": { "example": { "items": [ { "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Consignment Partner", "code": "PARTNER", "type": "external", "status": "active", "metadata": { "consignment": true }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryOwnersPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inventory owners", "tags": [ "Inventory Segments" ] }, "post": { "description": "API key scope: inventory:write.", "operationId": "InventorySegmentsController_createOwner", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInventoryOwnerDto" } } } }, "responses": { "201": { "description": "Inventory owner created.", "content": { "application/json": { "example": { "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Consignment Partner", "code": "PARTNER", "type": "external", "status": "active", "metadata": { "consignment": true }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryOwnerResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create an inventory owner", "tags": [ "Inventory Segments" ] } }, "/v1/organizations/{organizationId}/inventory-owners/{ownerId}": { "patch": { "description": "API key scope: inventory:write.", "operationId": "InventorySegmentsController_updateOwner", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "ownerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInventoryOwnerDto" } } } }, "responses": { "200": { "description": "Inventory owner updated.", "content": { "application/json": { "example": { "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Consignment Partner", "code": "PARTNER", "type": "external", "status": "active", "metadata": { "consignment": true }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryOwnerResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update an inventory owner", "tags": [ "Inventory Segments" ] } }, "/v1/organizations/{organizationId}/inventory-channels": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventorySegmentsController_listChannels", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": false, "in": "query", "schema": { "example": "DEFAULT", "type": "string" } } ], "responses": { "200": { "description": "Inventory channels page.", "content": { "application/json": { "example": { "items": [ { "id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Marketplace", "code": "MARKETPLACE", "type": "marketplace", "status": "active", "metadata": { "region": "US" }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryChannelsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inventory channels", "tags": [ "Inventory Segments" ] }, "post": { "description": "API key scope: inventory:write.", "operationId": "InventorySegmentsController_createChannel", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInventoryChannelDto" } } } }, "responses": { "201": { "description": "Inventory channel created.", "content": { "application/json": { "example": { "id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Marketplace", "code": "MARKETPLACE", "type": "marketplace", "status": "active", "metadata": { "region": "US" }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryChannelResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create an inventory channel", "tags": [ "Inventory Segments" ] } }, "/v1/organizations/{organizationId}/inventory-channels/{channelId}": { "patch": { "description": "API key scope: inventory:write.", "operationId": "InventorySegmentsController_updateChannel", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "channelId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInventoryChannelDto" } } } }, "responses": { "200": { "description": "Inventory channel updated.", "content": { "application/json": { "example": { "id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "name": "Marketplace", "code": "MARKETPLACE", "type": "marketplace", "status": "active", "metadata": { "region": "US" }, "createdAt": "2026-07-03T10:00:00.000Z", "updatedAt": "2026-07-03T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryChannelResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update an inventory channel", "tags": [ "Inventory Segments" ] } }, "/v1/organizations/{organizationId}/balances": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventoryBalancesController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "description": "Filter by product id.", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location id.", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "description": "Filter by inventory owner id.", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "description": "Filter by inventory channel id.", "schema": { "type": "string" } }, { "name": "sku", "required": false, "in": "query", "schema": { "example": "TSHIRT-BLACK-M", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Inventory balance id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory balances page.", "content": { "application/json": { "example": { "items": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryBalancesPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inventory balances in the selected organization", "tags": [ "Inventory Balances" ] } }, "/v1/organizations/{organizationId}/balances/{balanceId}": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventoryBalancesController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "balanceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory balance found.", "content": { "application/json": { "example": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get an inventory balance in the selected organization", "tags": [ "Inventory Balances" ] } }, "/v1/organizations/{organizationId}/balances/{balanceId}/explain": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventoryBalancesController_explain", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "balanceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory balance explanation.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ], "totals": { "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0 } }, "schema": { "$ref": "#/components/schemas/BalanceExplanationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Explain an inventory balance from stock ledger movements", "tags": [ "Inventory Balances" ] } }, "/v1/organizations/{organizationId}/movements": { "get": { "description": "API key scope: inventory:read.", "operationId": "StockLedgerController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "description": "Filter by product id.", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location id.", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "description": "Filter by inventory owner id.", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "description": "Filter by inventory channel id.", "schema": { "type": "string" } }, { "name": "operation", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] } }, { "name": "inventoryState", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] } }, { "name": "referenceType", "required": false, "in": "query", "schema": { "example": "reservation", "type": "string" } }, { "name": "referenceId", "required": false, "in": "query", "schema": { "example": "res_01JABC", "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Stock ledger id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stock ledger movements page.", "content": { "application/json": { "example": { "items": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/StockLedgerPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List stock ledger movements in the selected organization", "tags": [ "Stock Ledger" ] } }, "/v1/organizations/{organizationId}/lots": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventoryLotsController_findLots", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "lotCode", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "batchCode", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "expiresFrom", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-07-01T00:00:00.000Z", "type": "string" } }, { "name": "expiresTo", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-12-31T23:59:59.999Z", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory lots page.", "content": { "application/json": { "example": { "items": [ { "id": "12121212-1212-4212-8212-121212121212", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "receivedAt": "2026-07-01T12:00:00.000Z", "status": "active", "metadata": { "supplierLot": "SUP-A1" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryLotsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inventory lots in the selected organization", "tags": [ "Inventory Lots" ] } }, "/v1/organizations/{organizationId}/lots/{lotId}": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventoryLotsController_findLot", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "lotId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory lot found.", "content": { "application/json": { "example": { "id": "12121212-1212-4212-8212-121212121212", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "receivedAt": "2026-07-01T12:00:00.000Z", "status": "active", "metadata": { "supplierLot": "SUP-A1" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryLotResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get an inventory lot in the selected organization", "tags": [ "Inventory Lots" ] } }, "/v1/organizations/{organizationId}/lot-balances": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventoryLotsController_findLotBalances", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "lotId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory lot balances page.", "content": { "application/json": { "example": { "items": [ { "id": "13131313-1313-4313-8313-131313131313", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "receivedAt": "2026-07-01T12:00:00.000Z", "status": "active", "metadata": { "supplierLot": "SUP-A1" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryLotBalancesPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inventory balances broken down by lot", "tags": [ "Inventory Lots" ] } }, "/v1/organizations/{organizationId}/serials": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventorySerialsController_findSerials", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "lotId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "in_stock", "picked", "packed", "consumed", "written_off", "archived" ] } }, { "name": "serialNumber", "required": false, "in": "query", "schema": { "example": "SN-2026-0001", "type": "string" } } ], "responses": { "200": { "description": "Inventory serials page.", "content": { "application/json": { "example": { "items": [ { "id": "14141414-1414-4414-8414-141414141414", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "serialNumber": "SN-2026-0001", "status": "in_stock", "receivedAt": "2026-07-01T12:00:00.000Z", "consumedAt": null, "metadata": { "warranty": "standard" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "receivedAt": "2026-07-01T12:00:00.000Z", "status": "active", "metadata": { "supplierLot": "SUP-A1" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventorySerialsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inventory serials in the selected organization", "tags": [ "Inventory Serials" ] } }, "/v1/organizations/{organizationId}/serials/{serialId}": { "get": { "description": "API key scope: inventory:read.", "operationId": "InventorySerialsController_findSerial", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "serialId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory serial found.", "content": { "application/json": { "example": { "id": "14141414-1414-4414-8414-141414141414", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "serialNumber": "SN-2026-0001", "status": "in_stock", "receivedAt": "2026-07-01T12:00:00.000Z", "consumedAt": null, "metadata": { "warranty": "standard" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "receivedAt": "2026-07-01T12:00:00.000Z", "status": "active", "metadata": { "supplierLot": "SUP-A1" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" }, "createdAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventorySerialResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get an inventory serial in the selected organization", "tags": [ "Inventory Serials" ] } }, "/v1/organizations/{organizationId}/stock/receive": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_receive", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiveStockDto" } } } }, "responses": { "201": { "description": "Stock received with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Receive stock into a product location balance", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/adjust": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_adjust", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustStockDto" } } } }, "responses": { "201": { "description": "Stock adjusted with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Adjust one inventory state for a product location balance", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/fulfill": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_fulfill", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillStockDto" } } } }, "responses": { "201": { "description": "Stock fulfilled with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Fulfill stock out of a product location balance", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/write-off": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_writeOff", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteOffStockDto" } } } }, "responses": { "201": { "description": "Stock written off with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Write off stock permanently from a product location balance", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/return": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_returnStock", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnStockDto" } } } }, "responses": { "201": { "description": "Stock returned with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Return stock into a product location balance", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/move-state": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_moveState", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveInventoryStateDto" } } } }, "responses": { "201": { "description": "Stock moved between inventory states with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Move stock between inventory states without changing on-hand", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/reconcile": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_reconcile", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileStockDto" } } } }, "responses": { "201": { "description": "Stock reconciled with updated balance and ledger movements.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 10, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/StockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Reconcile a product location balance with a physical count", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/assemble": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_assemble", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssembleCompositionDto" } } } }, "responses": { "201": { "description": "Composition assembled with updated output and component balances.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 1, "available": 1, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "componentBalances": [ { "id": "56565656-5656-4565-8565-565656565656", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "25252525-2525-4252-8252-252525252525", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 8, "available": 8, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "25252525-2525-4252-8252-252525252525", "name": "Bundle component", "sku": "COMPONENT-001" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "composition_assemble_component", "inventoryState": "onHand", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" }, { "id": "89898989-8989-4898-8898-898989898989", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "composition_assemble_output", "inventoryState": "onHand", "quantity": 1, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 1, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/CompositionStockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Assemble a kit or bundle from component stock", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/stock/disassemble": { "post": { "description": "API key scope: inventory:write.", "operationId": "StockOperationsController_disassemble", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry stock write operations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisassembleCompositionDto" } } } }, "responses": { "201": { "description": "Composition disassembled with updated input and component balances.", "content": { "application/json": { "example": { "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 1, "available": 1, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "componentBalances": [ { "id": "56565656-5656-4565-8565-565656565656", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "25252525-2525-4252-8252-252525252525", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 8, "available": 8, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "25252525-2525-4252-8252-252525252525", "name": "Bundle component", "sku": "COMPONENT-001" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "composition_assemble_component", "inventoryState": "onHand", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" }, { "id": "89898989-8989-4898-8898-898989898989", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "composition_assemble_output", "inventoryState": "onHand", "quantity": 1, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 1, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/CompositionStockOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Disassemble a kit or bundle into component stock", "tags": [ "Stock Operations" ] } }, "/v1/organizations/{organizationId}/reservations": { "post": { "description": "API key scope: reservations:write.", "operationId": "ReservationsController_create", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry reservation creation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReservationDto" } } } }, "responses": { "201": { "description": "Reservation created with ledger movements.", "content": { "application/json": { "example": { "reservation": { "id": "66666666-6666-4666-8666-666666666666", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "quantity": 2, "status": "pending", "expiresAt": "2026-07-01T12:00:00.000Z", "referenceType": "checkout", "referenceId": "cart_01JABC", "metadata": { "channel": "web" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "reservation_create", "inventoryState": "reserved", "quantity": 2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 2, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/ReservationOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Reserve available stock for a product location", "tags": [ "Reservations" ] }, "get": { "description": "API key scope: reservations:read.", "operationId": "ReservationsController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "description": "Filter by product id.", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location id.", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "description": "Filter by inventory owner id.", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "description": "Filter by inventory channel id.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "committed", "released", "expired", "cancelled" ] } }, { "name": "referenceType", "required": false, "in": "query", "schema": { "example": "checkout", "type": "string" } }, { "name": "referenceId", "required": false, "in": "query", "schema": { "example": "cart_01JABC", "type": "string" } }, { "name": "expiresFrom", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-06-23T00:00:00.000Z", "type": "string" } }, { "name": "expiresTo", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-06-24T00:00:00.000Z", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Reservation id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reservations page.", "content": { "application/json": { "example": { "items": [ { "id": "66666666-6666-4666-8666-666666666666", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "quantity": 2, "status": "pending", "expiresAt": "2026-07-01T12:00:00.000Z", "referenceType": "checkout", "referenceId": "cart_01JABC", "metadata": { "channel": "web" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/ReservationsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List reservations in the selected organization", "tags": [ "Reservations" ] } }, "/v1/organizations/{organizationId}/reservations/{reservationId}": { "get": { "description": "API key scope: reservations:read.", "operationId": "ReservationsController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "reservationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reservation found.", "content": { "application/json": { "example": { "id": "66666666-6666-4666-8666-666666666666", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "quantity": 2, "status": "pending", "expiresAt": "2026-07-01T12:00:00.000Z", "referenceType": "checkout", "referenceId": "cart_01JABC", "metadata": { "channel": "web" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/ReservationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a reservation in the selected organization", "tags": [ "Reservations" ] } }, "/v1/organizations/{organizationId}/reservations/{reservationId}/commit": { "post": { "description": "API key scope: reservations:write.", "operationId": "ReservationsController_commit", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "reservationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry reservation commits.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Reservation committed with ledger movements.", "content": { "application/json": { "example": { "reservation": { "id": "66666666-6666-4666-8666-666666666666", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "quantity": 2, "status": "pending", "expiresAt": "2026-07-01T12:00:00.000Z", "referenceType": "checkout", "referenceId": "cart_01JABC", "metadata": { "channel": "web" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "reservation_create", "inventoryState": "reserved", "quantity": 2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 2, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/ReservationOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Commit a pending reservation", "tags": [ "Reservations" ] } }, "/v1/organizations/{organizationId}/reservations/{reservationId}/release": { "post": { "description": "API key scope: reservations:write.", "operationId": "ReservationsController_release", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "reservationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry reservation releases.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Reservation released with ledger movements.", "content": { "application/json": { "example": { "reservation": { "id": "66666666-6666-4666-8666-666666666666", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "quantity": 2, "status": "pending", "expiresAt": "2026-07-01T12:00:00.000Z", "referenceType": "checkout", "referenceId": "cart_01JABC", "metadata": { "channel": "web" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "reservation_create", "inventoryState": "reserved", "quantity": 2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 2, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/ReservationOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Release a pending reservation", "tags": [ "Reservations" ] } }, "/v1/organizations/{organizationId}/reservations/{reservationId}/cancel": { "post": { "description": "API key scope: reservations:write.", "operationId": "ReservationsController_cancel", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "reservationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry reservation cancellation.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Reservation cancelled with ledger movements.", "content": { "application/json": { "example": { "reservation": { "id": "66666666-6666-4666-8666-666666666666", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "quantity": 2, "status": "pending", "expiresAt": "2026-07-01T12:00:00.000Z", "referenceType": "checkout", "referenceId": "cart_01JABC", "metadata": { "channel": "web" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "reservation_create", "inventoryState": "reserved", "quantity": 2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 2, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/ReservationOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Cancel a pending or committed reservation", "tags": [ "Reservations" ] } }, "/v1/organizations/{organizationId}/transfers": { "post": { "description": "API key scope: transfers:write.", "operationId": "TransfersController_create", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry transfer creation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferDto" } } } }, "responses": { "201": { "description": "Transfer created with ledger movements.", "content": { "application/json": { "example": { "transfer": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 2, "shippedQuantity": 2, "receivedQuantity": 0, "pendingShipmentQuantity": 0, "pendingReceiveQuantity": 2, "status": "inTransit", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": "2026-06-29T10:00:00.000Z", "receivedAt": null, "cancelledAt": null, "closedAt": null, "closeReason": null, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "sourceBalance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 8, "available": 8, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "transfer_out", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/TransferSourceOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create an in-transit stock transfer between locations", "tags": [ "Transfers" ] }, "get": { "description": "API key scope: transfers:read.", "operationId": "TransfersController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "description": "Filter by product id.", "schema": { "type": "string" } }, { "name": "sourceLocationId", "required": false, "in": "query", "description": "Filter by source location id.", "schema": { "type": "string" } }, { "name": "destinationLocationId", "required": false, "in": "query", "description": "Filter by destination location id.", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "description": "Filter by inventory owner id.", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "description": "Filter by inventory channel id.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "inTransit", "received", "cancelled", "closed" ] } }, { "name": "referenceType", "required": false, "in": "query", "schema": { "example": "internal_transfer", "type": "string" } }, { "name": "referenceId", "required": false, "in": "query", "schema": { "example": "transfer_01JABC", "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-06-23T00:00:00.000Z", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-06-24T00:00:00.000Z", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Transfer id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transfers page.", "content": { "application/json": { "example": { "items": [ { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 2, "shippedQuantity": 2, "receivedQuantity": 0, "pendingShipmentQuantity": 0, "pendingReceiveQuantity": 2, "status": "inTransit", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": "2026-06-29T10:00:00.000Z", "receivedAt": null, "cancelledAt": null, "closedAt": null, "closeReason": null, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryTransfersPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List transfers in the selected organization", "tags": [ "Transfers" ] } }, "/v1/organizations/{organizationId}/transfers/{transferId}": { "get": { "description": "API key scope: transfers:read.", "operationId": "TransfersController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "transferId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transfer found.", "content": { "application/json": { "example": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 2, "shippedQuantity": 2, "receivedQuantity": 0, "pendingShipmentQuantity": 0, "pendingReceiveQuantity": 2, "status": "inTransit", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": "2026-06-29T10:00:00.000Z", "receivedAt": null, "cancelledAt": null, "closedAt": null, "closeReason": null, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryTransferResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a transfer in the selected organization", "tags": [ "Transfers" ] } }, "/v1/organizations/{organizationId}/transfers/{transferId}/ship": { "post": { "description": "API key scope: transfers:write.", "operationId": "TransfersController_ship", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "transferId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry transfer shipping.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "Optional partial ship payload. Omit the body to ship the full pending shipment quantity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipTransferDto" } } } }, "responses": { "201": { "description": "Transfer shipped with ledger movements.", "content": { "application/json": { "example": { "transfer": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 4, "shippedQuantity": 2, "receivedQuantity": 0, "pendingShipmentQuantity": 2, "pendingReceiveQuantity": 2, "status": "inTransit", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": null, "receivedAt": null, "cancelledAt": null, "closedAt": null, "closeReason": null, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "sourceBalance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 8, "available": 8, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "transfer_out", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Initial receipt", "referenceType": "transfer", "referenceId": "77777777-7777-4777-8777-777777777777", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/TransferSourceOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Ship a partial or full transfer from the source location", "tags": [ "Transfers" ] } }, "/v1/organizations/{organizationId}/transfers/{transferId}/receive": { "post": { "description": "API key scope: transfers:write.", "operationId": "TransfersController_receive", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "transferId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry transfer receiving.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "Optional partial receive payload. Omit the body to receive the full pending quantity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiveTransferDto" } } } }, "responses": { "201": { "description": "Transfer received with ledger movements.", "content": { "application/json": { "example": { "transfer": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 2, "shippedQuantity": 2, "receivedQuantity": 1, "pendingShipmentQuantity": 0, "pendingReceiveQuantity": 1, "status": "inTransit", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": "2026-06-29T10:00:00.000Z", "receivedAt": null, "cancelledAt": null, "closedAt": null, "closeReason": null, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "destinationBalance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "44444444-4444-4444-8444-444444444444", "onHand": 1, "available": 1, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "transfer_in", "inventoryState": "available", "quantity": 1, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 1, "reason": "Initial receipt", "referenceType": "transfer", "referenceId": "77777777-7777-4777-8777-777777777777", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/TransferDestinationOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Receive a partial or full in-transit transfer into the destination location", "tags": [ "Transfers" ] } }, "/v1/organizations/{organizationId}/transfers/{transferId}/close": { "post": { "description": "API key scope: transfers:write.", "operationId": "TransfersController_close", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "transferId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry transfer closing.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Auditable reason for closing the transfer with shipped or unshipped differences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseTransferDto" } } } }, "responses": { "201": { "description": "Transfer closed without ledger movements.", "content": { "application/json": { "example": { "transfer": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 4, "shippedQuantity": 2, "receivedQuantity": 1, "pendingShipmentQuantity": 2, "pendingReceiveQuantity": 1, "status": "closed", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": "2026-06-29T10:00:00.000Z", "receivedAt": null, "cancelledAt": null, "closedAt": "2026-06-29T11:00:00.000Z", "closeReason": "Source shortage confirmed during cycle count.", "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [] }, "schema": { "$ref": "#/components/schemas/TransferOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Close an in-transit transfer with auditable differences", "tags": [ "Transfers" ] } }, "/v1/organizations/{organizationId}/transfers/{transferId}/cancel": { "post": { "description": "API key scope: transfers:write.", "operationId": "TransfersController_cancel", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "transferId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry transfer cancellation.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Transfer cancelled with ledger movements.", "content": { "application/json": { "example": { "transfer": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "sourceLocationId": "33333333-3333-4333-8333-333333333333", "destinationLocationId": "44444444-4444-4444-8444-444444444444", "quantity": 2, "shippedQuantity": 2, "receivedQuantity": 0, "pendingShipmentQuantity": 0, "pendingReceiveQuantity": 2, "status": "inTransit", "referenceType": "internal_transfer", "referenceId": "transfer_01JABC", "metadata": { "channel": "panel" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "sourceLocation": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "destinationLocation": { "id": "44444444-4444-4444-8444-444444444444", "name": "Retail Store", "code": "STORE-1", "type": "store" }, "shippedAt": "2026-06-29T10:00:00.000Z", "receivedAt": null, "cancelledAt": null, "closedAt": null, "closeReason": null, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "sourceBalance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 8, "available": 8, "reserved": 0, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "transfer_out", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Initial receipt", "referenceType": "purchase_order", "referenceId": "po_01JABC", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/TransferSourceOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Cancel an in-transit transfer and return stock to the source", "tags": [ "Transfers" ] } }, "/v1/organizations/{organizationId}/inbounds": { "post": { "description": "API key scope: inventory:write.", "operationId": "InboundsController_create", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry inbound creation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboundDto" } } } }, "responses": { "201": { "description": "Inbound created with incoming ledger movement.", "content": { "application/json": { "example": { "inbound": { "id": "99999999-9999-4999-8999-999999999999", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "expectedQuantity": 20, "receivedQuantity": 5, "status": "partiallyReceived", "supplierName": "Acme Supplies", "supplierReference": "SUP-PO-1001", "externalOrderType": "purchase_order", "externalOrderId": "po_01JABC", "expectedAt": "2026-07-10T12:00:00.000Z", "receivedAt": null, "closedAt": null, "cancelledAt": null, "referenceType": "purchase_order", "referenceId": "po_01JABC", "metadata": { "receivingDock": "A" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 15, "available": 15, "reserved": 0, "committed": 0, "incoming": 15, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "inbound_receive", "inventoryState": "incoming", "quantity": -5, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 20, "balanceAfter": 15, "reason": "Inbound stock received", "referenceType": "inbound", "referenceId": "99999999-9999-4999-8999-999999999999", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/InboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create an expected inbound receipt", "tags": [ "Inbounds" ] }, "get": { "description": "API key scope: inventory:read.", "operationId": "InboundsController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "expected", "partiallyReceived", "received", "closed", "cancelled" ] } }, { "name": "productId", "required": false, "in": "query", "description": "Filter by product id.", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location id.", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "description": "Filter by inventory owner id.", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "description": "Filter by inventory channel id.", "schema": { "type": "string" } }, { "name": "externalOrderType", "required": false, "in": "query", "schema": { "example": "purchase_order", "type": "string" } }, { "name": "externalOrderId", "required": false, "in": "query", "schema": { "example": "po_01JABC", "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-06-29T00:00:00.000Z", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-06-30T00:00:00.000Z", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Inbound id cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inbounds page.", "content": { "application/json": { "example": { "items": [ { "id": "99999999-9999-4999-8999-999999999999", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "expectedQuantity": 20, "receivedQuantity": 5, "status": "partiallyReceived", "supplierName": "Acme Supplies", "supplierReference": "SUP-PO-1001", "externalOrderType": "purchase_order", "externalOrderId": "po_01JABC", "expectedAt": "2026-07-10T12:00:00.000Z", "receivedAt": null, "closedAt": null, "cancelledAt": null, "referenceType": "purchase_order", "referenceId": "po_01JABC", "metadata": { "receivingDock": "A" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryInboundsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List inbounds in the selected organization", "tags": [ "Inbounds" ] } }, "/v1/organizations/{organizationId}/inbounds/{inboundId}": { "get": { "description": "API key scope: inventory:read.", "operationId": "InboundsController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "inboundId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inbound found.", "content": { "application/json": { "example": { "id": "99999999-9999-4999-8999-999999999999", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "expectedQuantity": 20, "receivedQuantity": 5, "status": "partiallyReceived", "supplierName": "Acme Supplies", "supplierReference": "SUP-PO-1001", "externalOrderType": "purchase_order", "externalOrderId": "po_01JABC", "expectedAt": "2026-07-10T12:00:00.000Z", "receivedAt": null, "closedAt": null, "cancelledAt": null, "referenceType": "purchase_order", "referenceId": "po_01JABC", "metadata": { "receivingDock": "A" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryInboundResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get an inbound in the selected organization", "tags": [ "Inbounds" ] } }, "/v1/organizations/{organizationId}/inbounds/{inboundId}/receive": { "post": { "description": "API key scope: inventory:write.", "operationId": "InboundsController_receive", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "inboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry inbound receiving.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiveInboundDto" } } } }, "responses": { "201": { "description": "Inbound received with ledger movements.", "content": { "application/json": { "example": { "inbound": { "id": "99999999-9999-4999-8999-999999999999", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "expectedQuantity": 20, "receivedQuantity": 5, "status": "partiallyReceived", "supplierName": "Acme Supplies", "supplierReference": "SUP-PO-1001", "externalOrderType": "purchase_order", "externalOrderId": "po_01JABC", "expectedAt": "2026-07-10T12:00:00.000Z", "receivedAt": null, "closedAt": null, "cancelledAt": null, "referenceType": "purchase_order", "referenceId": "po_01JABC", "metadata": { "receivingDock": "A" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 15, "available": 15, "reserved": 0, "committed": 0, "incoming": 15, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "inbound_receive", "inventoryState": "incoming", "quantity": -5, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 20, "balanceAfter": 15, "reason": "Inbound stock received", "referenceType": "inbound", "referenceId": "99999999-9999-4999-8999-999999999999", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/InboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Receive a partial or full inbound quantity", "tags": [ "Inbounds" ] } }, "/v1/organizations/{organizationId}/inbounds/{inboundId}/close": { "post": { "description": "API key scope: inventory:write.", "operationId": "InboundsController_close", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "inboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry inbound closing.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Inbound closed with incoming ledger movement.", "content": { "application/json": { "example": { "inbound": { "id": "99999999-9999-4999-8999-999999999999", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "expectedQuantity": 20, "receivedQuantity": 5, "status": "partiallyReceived", "supplierName": "Acme Supplies", "supplierReference": "SUP-PO-1001", "externalOrderType": "purchase_order", "externalOrderId": "po_01JABC", "expectedAt": "2026-07-10T12:00:00.000Z", "receivedAt": null, "closedAt": null, "cancelledAt": null, "referenceType": "purchase_order", "referenceId": "po_01JABC", "metadata": { "receivingDock": "A" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 15, "available": 15, "reserved": 0, "committed": 0, "incoming": 15, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "inbound_receive", "inventoryState": "incoming", "quantity": -5, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 20, "balanceAfter": 15, "reason": "Inbound stock received", "referenceType": "inbound", "referenceId": "99999999-9999-4999-8999-999999999999", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/InboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Close an inbound and clear remaining expected quantity", "tags": [ "Inbounds" ] } }, "/v1/organizations/{organizationId}/inbounds/{inboundId}/cancel": { "post": { "description": "API key scope: inventory:write.", "operationId": "InboundsController_cancel", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "inboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry inbound cancellation.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Inbound cancelled with incoming ledger movement.", "content": { "application/json": { "example": { "inbound": { "id": "99999999-9999-4999-8999-999999999999", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "expectedQuantity": 20, "receivedQuantity": 5, "status": "partiallyReceived", "supplierName": "Acme Supplies", "supplierReference": "SUP-PO-1001", "externalOrderType": "purchase_order", "externalOrderId": "po_01JABC", "expectedAt": "2026-07-10T12:00:00.000Z", "receivedAt": null, "closedAt": null, "cancelledAt": null, "referenceType": "purchase_order", "referenceId": "po_01JABC", "metadata": { "receivingDock": "A" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 15, "available": 15, "reserved": 0, "committed": 0, "incoming": 15, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "inbound_receive", "inventoryState": "incoming", "quantity": -5, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 20, "balanceAfter": 15, "reason": "Inbound stock received", "referenceType": "inbound", "referenceId": "99999999-9999-4999-8999-999999999999", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/InboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Cancel an inbound before any quantity is received", "tags": [ "Inbounds" ] } }, "/v1/organizations/{organizationId}/outbounds": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_create", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound creation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutboundDto" } } } }, "responses": { "201": { "description": "Outbound created with allocation movements when stock exists.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create an outbound request and allocate available stock", "tags": [ "Outbounds" ] }, "get": { "description": "API key scope: inventory:read.", "operationId": "OutboundsController_findAll", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "backordered", "partiallyAllocated", "allocated", "partiallyPicked", "picked", "partiallyPacked", "packed", "partiallyFulfilled", "fulfilled", "cancelled" ] } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "externalOrderType", "required": false, "in": "query", "schema": { "example": "sales_order", "type": "string" } }, { "name": "externalOrderId", "required": false, "in": "query", "schema": { "example": "so_01JABC", "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } } ], "responses": { "200": { "description": "Outbounds page.", "content": { "application/json": { "example": { "items": [ { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventoryOutboundsPageResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List outbounds in the selected organization", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}": { "get": { "description": "API key scope: inventory:read.", "operationId": "OutboundsController_findOne", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Outbound found.", "content": { "application/json": { "example": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "schema": { "$ref": "#/components/schemas/InventoryOutboundResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get an outbound in the selected organization", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}/allocate": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_allocate", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound allocation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocateOutboundDto" } } } }, "responses": { "201": { "description": "Outbound allocated with ledger movements.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Allocate available stock to an outbound", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}/fulfill": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_fulfill", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound fulfillment.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillOutboundDto" } } } }, "responses": { "201": { "description": "Outbound fulfilled with ledger movements.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Fulfill allocated outbound stock", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}/pick": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_pick", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound picking.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgressOutboundDto" } } } }, "responses": { "201": { "description": "Outbound picked without changing inventory balances.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Pick allocated outbound stock", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}/pack": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_pack", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound packing.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgressOutboundDto" } } } }, "responses": { "201": { "description": "Outbound packed without changing inventory balances.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Pack picked outbound stock", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}/ship": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_ship", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound shipping.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgressOutboundDto" } } } }, "responses": { "201": { "description": "Outbound shipped with ledger movements.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization has exhausted an applicable monthly billing quota.", "content": { "application/json": { "examples": { "inventoryOperations": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for billable_inventory_operations", "requestId": "req_123", "details": { "entitlementKey": "billable_inventory_operations", "scope": "environment", "environment": "live", "configured": true, "limit": "2000", "used": "2000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } }, "apiRequests": { "value": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Ship packed outbound stock", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/outbounds/{outboundId}/cancel": { "post": { "description": "API key scope: inventory:write.", "operationId": "OutboundsController_cancel", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "outboundId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key used to safely retry outbound cancellation.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Outbound cancelled with ledger movements when needed.", "content": { "application/json": { "example": { "outbound": { "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "status": "partiallyPicked", "customerName": "Acme Customer", "externalOrderType": "sales_order", "externalOrderId": "so_01JABC", "expectedShipAt": "2026-07-10T12:00:00.000Z", "allocatedAt": "2026-06-29T10:05:00.000Z", "fulfilledAt": null, "cancelledAt": null, "referenceType": "sales_order", "referenceId": "so_01JABC", "metadata": { "channel": "web" }, "version": 1, "createdBy": null, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lines": [ { "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "outboundId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "requestedQuantity": 4, "allocatedQuantity": 2, "pickedQuantity": 1, "packedQuantity": 0, "fulfilledQuantity": 0, "pendingAllocationQuantity": 2, "pendingPickQuantity": 1, "pendingPackQuantity": 1, "pendingFulfillmentQuantity": 2, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "serials": [ { "id": "15151515-1515-4515-8515-151515151515", "serialId": "14141414-1414-4414-8414-141414141414", "pickedAt": "2026-07-01T12:05:00.000Z", "packedAt": null, "shippedAt": null, "serial": { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "picked", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" } ], "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:05:00.000Z" }, "balance": { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" }, "balances": [ { "id": "55555555-5555-4555-8555-555555555555", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "onHand": 10, "available": 8, "reserved": 0, "committed": 2, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 0, "version": 1, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ], "movements": [ { "id": "88888888-8888-4888-8888-888888888888", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212", "operation": "outbound_allocate", "inventoryState": "available", "quantity": -2, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 10, "balanceAfter": 8, "reason": "Allocate outbound stock", "referenceType": "outbound", "referenceId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "source": "api_key", "idempotencyKey": "receive-unique-key", "metadata": { "batch": "A1" }, "actor": { "type": "api_key", "id": "api-key-1", "label": "Public test integration" }, "product": { "id": "22222222-2222-4222-8222-222222222222", "name": "Black T-Shirt - Medium", "sku": "TSHIRT-BLACK-M" }, "location": { "id": "33333333-3333-4333-8333-333333333333", "name": "Main Warehouse", "code": "MAIN-WH", "type": "warehouse" }, "lot": { "id": "12121212-1212-4212-8212-121212121212", "lotCode": "LOT-2026-001", "batchCode": "BATCH-A", "expiresAt": "2027-07-01T00:00:00.000Z", "status": "active" }, "serials": [ { "id": "14141414-1414-4414-8414-141414141414", "serialNumber": "SN-2026-0001", "status": "in_stock", "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333", "lotId": "12121212-1212-4212-8212-121212121212" } ], "createdAt": "2026-06-29T10:00:00.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutboundOperationResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Cancel an outbound and release allocated pending stock", "tags": [ "Outbounds" ] } }, "/v1/organizations/{organizationId}/reports/inventory-snapshot": { "get": { "description": "API key scope: reports:read.", "operationId": "ReportsController_inventorySnapshot", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Status filter. Supported values depend on report type.", "schema": { "type": "string" } }, { "name": "operation", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] } }, { "name": "inventoryState", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque id cursor returned by the previous report page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory snapshot report page.", "content": { "application/json": { "example": { "items": [ { "id": "55555555-5555-4555-8555-555555555555", "productId": "22222222-2222-4222-8222-222222222222", "productName": "Black T-Shirt - Medium", "productSku": "TSHIRT-BLACK-M", "locationId": "33333333-3333-4333-8333-333333333333", "locationName": "Main Warehouse", "locationCode": "MAIN-WH", "ownerId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "ownerName": "Consignment Partner", "ownerCode": "PARTNER", "channelId": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "channelName": "Marketplace", "channelCode": "MARKETPLACE", "onHand": 10, "available": 8, "reserved": 2, "committed": 0, "incoming": 0, "damaged": 0, "qualityControl": 0, "safetyStock": 1, "updatedAt": "2026-07-06T12:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/InventorySnapshotReportResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List the current inventory snapshot report", "tags": [ "Reports" ] } }, "/v1/organizations/{organizationId}/reports/stock-movements": { "get": { "description": "API key scope: reports:read.", "operationId": "ReportsController_stockMovements", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Status filter. Supported values depend on report type.", "schema": { "type": "string" } }, { "name": "operation", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] } }, { "name": "inventoryState", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque id cursor returned by the previous report page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stock movements report page.", "content": { "application/json": { "example": { "items": [ { "id": "88888888-8888-4888-8888-888888888888", "createdAt": "2026-06-29T10:00:00.000Z", "productId": "22222222-2222-4222-8222-222222222222", "productName": "Black T-Shirt - Medium", "productSku": "TSHIRT-BLACK-M", "locationId": "33333333-3333-4333-8333-333333333333", "locationName": "Main Warehouse", "locationCode": "MAIN-WH", "ownerId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "ownerName": "Consignment Partner", "ownerCode": "PARTNER", "channelId": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "channelName": "Marketplace", "channelCode": "MARKETPLACE", "operation": "receive", "inventoryState": "onHand", "quantity": 10, "unitCode": "CASE", "unitQuantity": 1, "baseUnitCode": "EA", "balanceBefore": 0, "balanceAfter": 10, "referenceType": "purchase_order", "referenceId": "po_01JABC", "reason": "Initial receipt", "source": "api_key", "actorType": "api_key", "actorId": "api-key-1", "actorLabel": "Public test integration" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/StockMovementsReportResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List the stock movements report", "tags": [ "Reports" ] } }, "/v1/organizations/{organizationId}/reports/operations-summary": { "get": { "description": "API key scope: reports:read.", "operationId": "ReportsController_operationsSummary", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Status filter. Supported values depend on report type.", "schema": { "type": "string" } }, { "name": "operation", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] } }, { "name": "inventoryState", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque id cursor returned by the previous report page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operations summary report.", "content": { "application/json": { "example": { "items": [ { "operationType": "reservations", "status": "pending", "count": 2, "totalQuantity": 8, "completedQuantity": 0, "pendingQuantity": 8 }, { "operationType": "inbounds", "status": "partiallyReceived", "count": 1, "totalQuantity": 20, "completedQuantity": 12, "pendingQuantity": 8 } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/OperationsSummaryReportResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List operations summary by status", "tags": [ "Reports" ] } }, "/v1/organizations/{organizationId}/reports/exceptions": { "get": { "description": "API key scope: reports:read.", "operationId": "ReportsController_exceptions", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Status filter. Supported values depend on report type.", "schema": { "type": "string" } }, { "name": "operation", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] } }, { "name": "inventoryState", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque id cursor returned by the previous report page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operational exceptions report.", "content": { "application/json": { "example": { "items": [ { "id": "inbound:99999999-9999-4999-8999-999999999999", "exceptionType": "inbound_pending", "resourceType": "inbound", "resourceId": "99999999-9999-4999-8999-999999999999", "status": "partiallyReceived", "productId": "22222222-2222-4222-8222-222222222222", "productName": "Black T-Shirt - Medium", "productSku": "TSHIRT-BLACK-M", "locationId": "33333333-3333-4333-8333-333333333333", "locationName": "Main Warehouse", "locationCode": "MAIN-WH", "ownerId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "ownerName": "Consignment Partner", "ownerCode": "PARTNER", "channelId": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "channelName": "Marketplace", "channelCode": "MARKETPLACE", "quantity": 20, "completedQuantity": 12, "pendingQuantity": 8, "message": "Inbound is partiallyReceived with pending quantity.", "occurredAt": "2026-07-06T12:00:00.000Z" } ], "nextCursor": null }, "schema": { "$ref": "#/components/schemas/ExceptionsReportResponseDto" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List operational exceptions", "tags": [ "Reports" ] } }, "/v1/organizations/{organizationId}/report-exports": { "post": { "description": "API key scope: reports:export. Captures a temporary PostgreSQL snapshot and generates files on demand at download time.", "operationId": "ReportsController_createExport", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportExportDto" } } } }, "responses": { "200": { "description": "Report export job created and processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportExportJobResponseDto" }, "example": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "reportType": "inventory_snapshot", "format": "csv", "status": "completed", "filters": { "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333" }, "rowCount": 1, "downloadAvailable": true, "hasFile": true, "expiresAt": "2026-07-13T12:00:00.000Z", "requestedBy": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "completedAt": "2026-07-06T12:01:00.000Z", "errorCode": null, "createdAt": "2026-07-06T12:00:00.000Z", "updatedAt": "2026-07-06T12:01:00.000Z" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.\n\nThe organization plan does not allow the requested action.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for active_products", "requestId": "req_123", "details": { "entitlementKey": "active_products", "scope": "environment", "environment": "live", "configured": true, "limit": "100", "used": "100", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create a report export job", "tags": [ "Reports" ] }, "get": { "description": "API key scope: reports:export. Export jobs expose snapshot availability, not server-side file storage.", "operationId": "ReportsController_listExports", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "reportType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "inventory_snapshot", "stock_movements", "operations_summary", "exceptions" ] } }, { "name": "format", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report export jobs page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportExportJobsResponseDto" }, "example": { "items": [ { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "reportType": "inventory_snapshot", "format": "csv", "status": "completed", "filters": { "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333" }, "rowCount": 1, "downloadAvailable": true, "hasFile": true, "expiresAt": "2026-07-13T12:00:00.000Z", "requestedBy": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "completedAt": "2026-07-06T12:01:00.000Z", "errorCode": null, "createdAt": "2026-07-06T12:00:00.000Z", "updatedAt": "2026-07-06T12:01:00.000Z" } ], "nextCursor": null } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List report export jobs", "tags": [ "Reports" ] } }, "/v1/organizations/{organizationId}/report-exports/{exportId}": { "get": { "description": "API key scope: reports:export. Completed jobs are downloadable while their temporary snapshot has not expired.", "operationId": "ReportsController_getExport", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "exportId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report export job found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportExportJobResponseDto" }, "example": { "id": "77777777-7777-4777-8777-777777777777", "organizationId": "11111111-1111-4111-8111-111111111111", "environment": "test", "reportType": "inventory_snapshot", "format": "csv", "status": "completed", "filters": { "productId": "22222222-2222-4222-8222-222222222222", "locationId": "33333333-3333-4333-8333-333333333333" }, "rowCount": 1, "downloadAvailable": true, "hasFile": true, "expiresAt": "2026-07-13T12:00:00.000Z", "requestedBy": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "completedAt": "2026-07-06T12:01:00.000Z", "errorCode": null, "createdAt": "2026-07-06T12:00:00.000Z", "updatedAt": "2026-07-06T12:01:00.000Z" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a report export job", "tags": [ "Reports" ] }, "delete": { "description": "API key scope: reports:export. Deletes the report export history entry and its temporary snapshot only.", "operationId": "ReportsController_deleteExport", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "exportId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Report export job deleted." }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete a report export job", "tags": [ "Reports" ] } }, "/v1/organizations/{organizationId}/report-exports/{exportId}/download": { "get": { "description": "API key scope: reports:export. Generates the requested file on demand from the stored PostgreSQL snapshot.", "operationId": "ReportsController_downloadExport", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "Optional client request id returned in structured errors.", "required": false, "schema": { "type": "string" } }, { "name": "exportId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report export file generated on demand.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "The organization has exhausted its monthly public API request quota.", "content": { "application/json": { "example": { "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "Plan limit exceeded for api_requests", "requestId": "req_123", "details": { "entitlementKey": "api_requests", "scope": "environment", "environment": "live", "configured": true, "limit": "50000", "used": "50000", "requested": "1", "currentPlan": { "code": "free", "version": 1 }, "requiredPlan": { "code": "starter", "version": 1, "requiresOverride": false } } } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Download a completed report export file", "tags": [ "Reports" ] } } }, "info": { "title": "Skunivo Public API", "description": "Public Skunivo inventory API for developers and integrators. This contract contains only API key authenticated organization endpoints.", "version": "0.1", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.skunivo.buildwithus.dev", "description": "Test API" } ], "components": { "securitySchemes": { "ApiKey": { "scheme": "bearer", "bearerFormat": "API key", "type": "http", "description": "Use Authorization: Bearer skv_test_* or skv_live_* for public API access. API keys are scoped to one organization and environment." } }, "schemas": { "ProductResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "object", "nullable": true }, "baseUnitCode": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "name", "sku", "baseUnitCode", "status", "createdAt", "updatedAt" ] }, "CreateProductDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Black T-Shirt - Medium" }, "sku": { "type": "string", "example": "TSHIRT-BLACK-M" }, "barcode": { "type": "string", "example": "7891234567890" }, "baseUnitCode": { "type": "string", "example": "EA", "default": "EA" }, "metadata": { "type": "object", "example": { "color": "black", "size": "M" } } }, "required": [ "name", "sku" ] }, "ProductsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "ProductSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "id", "name", "sku" ] }, "ProductCompositionComponentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "compositionId": { "type": "string", "format": "uuid" }, "componentProductId": { "type": "string", "format": "uuid" }, "quantityInBaseUnits": { "type": "number", "minimum": 1 }, "componentProduct": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "compositionId", "componentProductId", "quantityInBaseUnits", "createdAt", "updatedAt" ] }, "ProductCompositionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "kit", "bundle" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCompositionComponentResponseDto" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "kind", "status", "components", "createdAt", "updatedAt" ] }, "ProductCompositionComponentDto": { "type": "object", "properties": { "componentProductId": { "type": "string", "description": "Component product id." }, "quantityInBaseUnits": { "type": "number", "minimum": 1, "description": "Quantity of the component product required in base units for one assembled product." } }, "required": [ "componentProductId", "quantityInBaseUnits" ] }, "UpsertProductCompositionDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "kit", "bundle" ], "example": "kit" }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active" }, "components": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ProductCompositionComponentDto" } }, "metadata": { "type": "object", "example": { "sellableAs": "bundle" } } }, "required": [ "kind", "components" ] }, "UpdateProductDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Black T-Shirt - Medium" }, "sku": { "type": "string", "example": "TSHIRT-BLACK-M" }, "barcode": { "type": "object", "example": "7891234567890", "nullable": true }, "baseUnitCode": { "type": "string", "example": "EA" }, "status": { "type": "string", "enum": [ "active", "archived" ], "example": "active" }, "metadata": { "type": "object", "example": { "color": "black", "size": "M" } } } }, "LocationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "store", "virtual" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "addressLine1": { "type": "object", "nullable": true }, "addressLine2": { "type": "object", "nullable": true }, "city": { "type": "object", "nullable": true }, "region": { "type": "object", "nullable": true }, "postalCode": { "type": "object", "nullable": true }, "countryCode": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "name", "code", "type", "status", "createdAt", "updatedAt" ] }, "CreateLocationDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Main Warehouse" }, "code": { "type": "string", "example": "MAIN-WH" }, "type": { "type": "string", "enum": [ "warehouse", "store", "virtual" ], "example": "warehouse" }, "addressLine1": { "type": "object", "example": "123 Market St" }, "addressLine2": { "type": "object", "example": "Suite 400" }, "city": { "type": "object", "example": "Austin" }, "region": { "type": "object", "example": "TX" }, "postalCode": { "type": "object", "example": "78701" }, "countryCode": { "type": "object", "example": "US", "minLength": 2, "maxLength": 2 }, "metadata": { "type": "object", "example": { "timezone": "America/Chicago" } } }, "required": [ "name", "code", "type" ] }, "LocationsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LocationResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "UpdateLocationDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Main Warehouse" }, "code": { "type": "string", "example": "MAIN-WH" }, "type": { "type": "string", "enum": [ "warehouse", "store", "virtual" ], "example": "warehouse" }, "status": { "type": "string", "enum": [ "active", "archived" ], "example": "active" }, "addressLine1": { "type": "object", "example": "123 Market St" }, "addressLine2": { "type": "object", "example": "Suite 400" }, "city": { "type": "object", "example": "Austin" }, "region": { "type": "object", "example": "TX" }, "postalCode": { "type": "object", "example": "78701" }, "countryCode": { "type": "object", "example": "US", "minLength": 2, "maxLength": 2 }, "metadata": { "type": "object", "example": { "timezone": "America/Chicago" } } } }, "InventoryOwnerResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string", "enum": [ "internal", "external" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "name", "code", "type", "status", "createdAt", "updatedAt" ] }, "InventoryOwnersPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryOwnerResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "CreateInventoryOwnerDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Default owner" }, "code": { "type": "string", "example": "DEFAULT" }, "type": { "type": "string", "enum": [ "internal", "external" ], "example": "internal" }, "metadata": { "type": "object", "example": { "consignment": false } } }, "required": [ "name", "code", "type" ] }, "UpdateInventoryOwnerDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Vendor stock owner" }, "type": { "type": "string", "enum": [ "internal", "external" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "example": { "consignment": true } } } }, "InventoryChannelResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string", "enum": [ "default", "ecommerce", "marketplace", "pos", "wholesale", "custom" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "name", "code", "type", "status", "createdAt", "updatedAt" ] }, "InventoryChannelsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryChannelResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "CreateInventoryChannelDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Default channel" }, "code": { "type": "string", "example": "DEFAULT" }, "type": { "type": "string", "enum": [ "default", "ecommerce", "marketplace", "pos", "wholesale", "custom" ], "example": "default" }, "metadata": { "type": "object", "example": { "marketplace": "web" } } }, "required": [ "name", "code", "type" ] }, "UpdateInventoryChannelDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Web store" }, "type": { "type": "string", "enum": [ "default", "ecommerce", "marketplace", "pos", "wholesale", "custom" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "example": { "marketplace": "web" } } } }, "InventoryLotResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "lotCode": { "type": "string" }, "batchCode": { "type": "object", "nullable": true }, "expiresAt": { "type": "object", "format": "date-time", "nullable": true }, "receivedAt": { "type": "object", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "lotCode", "status", "createdAt", "updatedAt" ] }, "InventoryLotsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryLotResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "LocationSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "store", "virtual" ] } }, "required": [ "id", "name", "code", "type" ] }, "InventoryOwnerSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "code", "type" ] }, "InventoryChannelSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "code", "type" ] }, "InventoryLotBalanceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "lotId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "onHand": { "type": "number" }, "available": { "type": "number" }, "reserved": { "type": "number" }, "committed": { "type": "number" }, "damaged": { "type": "number" }, "qualityControl": { "type": "number" }, "safetyStock": { "type": "number" }, "version": { "type": "number" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "lot": { "$ref": "#/components/schemas/InventoryLotResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "lotId", "ownerId", "channelId", "onHand", "available", "reserved", "committed", "damaged", "qualityControl", "safetyStock", "version", "createdAt", "updatedAt" ] }, "InventoryLotBalancesPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryLotBalanceResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "InventoryLotSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotCode": { "type": "string" }, "batchCode": { "type": "object", "nullable": true }, "expiresAt": { "type": "object", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "id", "lotCode", "status" ] }, "InventorySerialResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "lotId": { "type": "object", "format": "uuid", "nullable": true }, "serialNumber": { "type": "string" }, "status": { "type": "string", "enum": [ "in_stock", "picked", "packed", "consumed", "written_off", "archived" ] }, "receivedAt": { "type": "object", "format": "date-time", "nullable": true }, "consumedAt": { "type": "object", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "lot": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryLotSummaryResponseDto" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "ownerId", "channelId", "serialNumber", "status", "createdAt", "updatedAt" ] }, "InventorySerialsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySerialResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "InventoryBalanceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "onHand": { "type": "number" }, "available": { "type": "number" }, "reserved": { "type": "number" }, "committed": { "type": "number" }, "incoming": { "type": "number" }, "damaged": { "type": "number" }, "qualityControl": { "type": "number" }, "safetyStock": { "type": "number" }, "version": { "type": "number" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "ownerId", "channelId", "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock", "version", "createdAt", "updatedAt" ] }, "InventoryBalancesPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "ActorResponseDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key", "system" ] }, "id": { "type": "object", "format": "uuid", "nullable": true }, "label": { "type": "string" } }, "required": [ "type", "label" ] }, "InventorySerialSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNumber": { "type": "string" }, "status": { "type": "string", "enum": [ "in_stock", "picked", "packed", "consumed", "written_off", "archived" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "lotId": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "id", "serialNumber", "status", "productId", "locationId", "ownerId", "channelId" ] }, "StockLedgerResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "lotId": { "type": "object", "format": "uuid", "nullable": true }, "operation": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] }, "inventoryState": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] }, "quantity": { "type": "number" }, "unitCode": { "type": "object", "nullable": true }, "unitQuantity": { "type": "object", "nullable": true }, "baseUnitCode": { "type": "object", "nullable": true }, "balanceBefore": { "type": "number" }, "balanceAfter": { "type": "number" }, "reason": { "type": "object", "nullable": true }, "referenceType": { "type": "object", "nullable": true }, "referenceId": { "type": "object", "nullable": true }, "source": { "type": "object", "nullable": true }, "idempotencyKey": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdBy": { "type": "object", "format": "uuid", "nullable": true }, "actor": { "$ref": "#/components/schemas/ActorResponseDto" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "lot": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryLotSummaryResponseDto" } ] }, "serials": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySerialSummaryResponseDto" } }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "ownerId", "channelId", "operation", "inventoryState", "quantity", "balanceBefore", "balanceAfter", "actor", "serials", "createdAt" ] }, "BalanceExplanationResponseDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } } }, "required": [ "balance", "movements" ] }, "StockLedgerPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "CompositionStockOperationResponseDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } }, "componentBalances": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" } } }, "required": [ "balance", "movements", "componentBalances" ] }, "AssembleCompositionDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Composed product id to assemble." }, "locationId": { "type": "string", "description": "Location where components are consumed and output is created." }, "quantity": { "type": "number", "minimum": 1, "description": "Number of composed product units to assemble." }, "reason": { "type": "string", "example": "Assemble launch bundle" }, "referenceType": { "type": "string", "example": "work_order" }, "referenceId": { "type": "string", "example": "wo_01JABC" }, "metadata": { "type": "object", "example": { "batch": "KIT-A1" } } }, "required": [ "productId", "locationId", "quantity" ] }, "DisassembleCompositionDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Composed product id to assemble." }, "locationId": { "type": "string", "description": "Location where components are consumed and output is created." }, "quantity": { "type": "number", "minimum": 1, "description": "Number of composed product units to assemble." }, "reason": { "type": "string", "example": "Assemble launch bundle" }, "referenceType": { "type": "string", "example": "work_order" }, "referenceId": { "type": "string", "example": "wo_01JABC" }, "metadata": { "type": "object", "example": { "batch": "KIT-A1" } } }, "required": [ "productId", "locationId", "quantity" ] }, "StockOperationResponseDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } } }, "required": [ "balance", "movements" ] }, "ReceiptSerialDto": { "type": "object", "properties": { "serialNumber": { "type": "string", "example": "SN-2026-0001" }, "metadata": { "type": "object", "example": { "warranty": "standard" } } }, "required": [ "serialNumber" ] }, "ReceiveStockDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "unitCode": { "type": "string", "example": "CASE", "description": "Alternative unit code. When provided, unitQuantity is converted to base quantity." }, "unitQuantity": { "type": "number", "minimum": 1, "description": "Quantity in unitCode. The converted base quantity must match quantity." }, "productId": { "type": "string", "description": "Product id receiving stock." }, "locationId": { "type": "string", "description": "Location id receiving stock." }, "quantity": { "type": "number", "minimum": 1 }, "reason": { "type": "string", "example": "Initial stock receipt" }, "referenceType": { "type": "string", "example": "purchase_order" }, "referenceId": { "type": "string", "example": "po_01JABC" }, "metadata": { "type": "object", "example": { "batch": "A1" } }, "lotId": { "type": "string", "description": "Existing lot id to receive into." }, "lotCode": { "type": "string", "example": "LOT-2026-001" }, "batchCode": { "type": "string", "example": "BATCH-A" }, "expiresAt": { "format": "date-time", "type": "string", "example": "2027-07-01T00:00:00.000Z" }, "receivedAt": { "format": "date-time", "type": "string", "example": "2026-07-01T12:00:00.000Z" }, "lotMetadata": { "type": "object", "example": { "supplierLot": "SUP-A1" } }, "serials": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptSerialDto" } } }, "required": [ "productId", "locationId", "quantity" ] }, "AdjustStockDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Product id being adjusted." }, "locationId": { "type": "string", "description": "Location id being adjusted." }, "inventoryState": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] }, "quantityDelta": { "type": "number", "description": "Positive or negative integer adjustment." }, "reason": { "type": "string", "example": "Cycle count correction" }, "referenceType": { "type": "string", "example": "cycle_count" }, "referenceId": { "type": "string", "example": "count_01JABC" }, "metadata": { "type": "object", "example": { "countedBy": "warehouse-team" } } }, "required": [ "productId", "locationId", "inventoryState", "quantityDelta", "reason" ] }, "FulfillStockDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "serialIds": { "description": "Existing serial ids to apply to this operation.", "type": "array", "items": { "type": "string" } }, "serialNumbers": { "description": "Existing serial numbers to apply to this operation.", "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "example": "CASE", "description": "Alternative unit code. When provided, unitQuantity is converted to base quantity." }, "unitQuantity": { "type": "number", "minimum": 1, "description": "Quantity in unitCode. The converted base quantity must match quantity." }, "productId": { "type": "string", "description": "Product id leaving stock." }, "locationId": { "type": "string", "description": "Location id shipping or consuming stock." }, "quantity": { "type": "number", "minimum": 1 }, "sourceState": { "type": "string", "enum": [ "available", "committed" ], "description": "Inventory state to consume before decrementing on-hand stock." }, "reason": { "type": "string", "example": "Order shipped" }, "referenceType": { "type": "string", "example": "order" }, "referenceId": { "type": "string", "example": "ord_01JABC" }, "metadata": { "type": "object", "example": { "channel": "web" } }, "lotId": { "type": "string", "description": "Lot id to consume from." }, "lotStrategy": { "type": "string", "enum": [ "fefo" ], "description": "Automatic lot selection strategy. FEFO consumes earliest expiring stock first." } }, "required": [ "productId", "locationId", "quantity", "sourceState", "reason" ] }, "WriteOffStockDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "serialIds": { "description": "Existing serial ids to apply to this operation.", "type": "array", "items": { "type": "string" } }, "serialNumbers": { "description": "Existing serial numbers to apply to this operation.", "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "example": "CASE", "description": "Alternative unit code. When provided, unitQuantity is converted to base quantity." }, "unitQuantity": { "type": "number", "minimum": 1, "description": "Quantity in unitCode. The converted base quantity must match quantity." }, "productId": { "type": "string", "description": "Product id being written off." }, "locationId": { "type": "string", "description": "Location id where stock is being written off." }, "quantity": { "type": "number", "minimum": 1 }, "sourceState": { "type": "string", "enum": [ "available", "damaged", "qualityControl", "safetyStock" ], "description": "Physical state to consume before decrementing on-hand stock." }, "reason": { "type": "string", "example": "Damaged stock discarded" }, "referenceType": { "type": "string", "example": "scrap" }, "referenceId": { "type": "string", "example": "scrap_01JABC" }, "metadata": { "type": "object", "example": { "disposition": "destroyed" } }, "lotId": { "type": "string", "description": "Lot id to consume from." }, "lotStrategy": { "type": "string", "enum": [ "fefo" ], "description": "Automatic lot selection strategy. FEFO consumes earliest expiring stock first." } }, "required": [ "productId", "locationId", "quantity", "sourceState", "reason" ] }, "ReturnStockDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "unitCode": { "type": "string", "example": "CASE", "description": "Alternative unit code. When provided, unitQuantity is converted to base quantity." }, "unitQuantity": { "type": "number", "minimum": 1, "description": "Quantity in unitCode. The converted base quantity must match quantity." }, "productId": { "type": "string", "description": "Product id being returned to stock." }, "locationId": { "type": "string", "description": "Location id receiving returned stock." }, "quantity": { "type": "number", "minimum": 1 }, "destinationState": { "type": "string", "enum": [ "available", "qualityControl", "damaged" ], "description": "State receiving the returned stock." }, "reason": { "type": "string", "example": "Customer return received" }, "referenceType": { "type": "string", "example": "return" }, "referenceId": { "type": "string", "example": "ret_01JABC" }, "metadata": { "type": "object", "example": { "disposition": "inspect" } }, "lotId": { "type": "string", "description": "Existing lot id to return into." }, "lotCode": { "type": "string", "example": "LOT-2026-001" }, "batchCode": { "type": "string", "example": "BATCH-A" }, "expiresAt": { "format": "date-time", "type": "string", "example": "2027-07-01T00:00:00.000Z" }, "receivedAt": { "format": "date-time", "type": "string", "example": "2026-07-01T12:00:00.000Z" }, "lotMetadata": { "type": "object", "example": { "supplierLot": "SUP-A1" } }, "serials": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptSerialDto" } } }, "required": [ "productId", "locationId", "quantity", "destinationState", "reason" ] }, "MoveInventoryStateDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "serialIds": { "description": "Existing serial ids to apply to this operation.", "type": "array", "items": { "type": "string" } }, "serialNumbers": { "description": "Existing serial numbers to apply to this operation.", "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "example": "CASE", "description": "Alternative unit code. When provided, unitQuantity is converted to base quantity." }, "unitQuantity": { "type": "number", "minimum": 1, "description": "Quantity in unitCode. The converted base quantity must match quantity." }, "productId": { "type": "string", "description": "Product id being moved between states." }, "locationId": { "type": "string", "description": "Location id for the state movement." }, "quantity": { "type": "number", "minimum": 1 }, "sourceState": { "type": "string", "enum": [ "available", "reserved", "damaged", "qualityControl", "safetyStock" ] }, "destinationState": { "type": "string", "enum": [ "available", "reserved", "damaged", "qualityControl", "safetyStock" ] }, "reason": { "type": "string", "example": "Move returned stock to available" }, "referenceType": { "type": "string", "example": "inspection" }, "referenceId": { "type": "string", "example": "insp_01JABC" }, "metadata": { "type": "object", "example": { "inspectedBy": "warehouse-team" } }, "lotId": { "type": "string", "description": "Lot id to move between states." }, "lotStrategy": { "type": "string", "enum": [ "fefo" ], "description": "Automatic lot selection strategy. FEFO consumes earliest expiring stock first." } }, "required": [ "productId", "locationId", "quantity", "sourceState", "destinationState", "reason" ] }, "ReconcileStockDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Product id being counted." }, "locationId": { "type": "string", "description": "Location id being counted." }, "countedOnHand": { "type": "number", "minimum": 0, "description": "Physical on-hand count." }, "reason": { "type": "string", "example": "Physical count correction" }, "referenceType": { "type": "string", "example": "cycle_count" }, "referenceId": { "type": "string", "example": "count_01JABC" }, "metadata": { "type": "object", "example": { "countedBy": "warehouse-team" } } }, "required": [ "productId", "locationId", "countedOnHand", "reason" ] }, "InventoryInboundResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "expectedQuantity": { "type": "number" }, "receivedQuantity": { "type": "number" }, "status": { "type": "string", "enum": [ "expected", "partiallyReceived", "received", "closed", "cancelled" ] }, "supplierName": { "type": "object", "nullable": true }, "supplierReference": { "type": "object", "nullable": true }, "externalOrderType": { "type": "object", "nullable": true }, "externalOrderId": { "type": "object", "nullable": true }, "expectedAt": { "type": "object", "format": "date-time", "nullable": true }, "receivedAt": { "type": "object", "format": "date-time", "nullable": true }, "closedAt": { "type": "object", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "object", "format": "date-time", "nullable": true }, "referenceType": { "type": "object", "nullable": true }, "referenceId": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "version": { "type": "number" }, "createdBy": { "type": "object", "format": "uuid", "nullable": true }, "actor": { "$ref": "#/components/schemas/ActorResponseDto" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "ownerId", "channelId", "expectedQuantity", "receivedQuantity", "status", "version", "actor", "createdAt", "updatedAt" ] }, "InboundOperationResponseDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } }, "inbound": { "$ref": "#/components/schemas/InventoryInboundResponseDto" } }, "required": [ "balance", "movements", "inbound" ] }, "CreateInboundDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Product id expected in this inbound." }, "locationId": { "type": "string", "description": "Location id where stock is expected." }, "expectedQuantity": { "type": "number", "minimum": 1 }, "supplierName": { "type": "string", "example": "Acme Supplies" }, "supplierReference": { "type": "string", "example": "SUP-PO-1001" }, "externalOrderType": { "type": "string", "example": "purchase_order" }, "externalOrderId": { "type": "string", "example": "po_01JABC" }, "expectedAt": { "format": "date-time", "type": "string", "example": "2026-07-10T12:00:00.000Z" }, "referenceType": { "type": "string", "example": "inbound" }, "referenceId": { "type": "string", "example": "inb_01JABC" }, "metadata": { "type": "object", "example": { "receivingDock": "A" } } }, "required": [ "productId", "locationId", "expectedQuantity" ] }, "InventoryInboundsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryInboundResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "ReceiveInboundDto": { "type": "object", "properties": { "quantity": { "type": "number", "minimum": 1 }, "reason": { "type": "string", "example": "Inbound stock received" }, "metadata": { "type": "object", "example": { "dockDoor": "D-3" } }, "lotId": { "type": "string", "description": "Existing lot id to receive into." }, "lotCode": { "type": "string", "example": "LOT-2026-001" }, "batchCode": { "type": "string", "example": "BATCH-A" }, "expiresAt": { "format": "date-time", "type": "string", "example": "2027-07-01T00:00:00.000Z" }, "receivedAt": { "format": "date-time", "type": "string", "example": "2026-07-01T12:00:00.000Z" }, "lotMetadata": { "type": "object", "example": { "supplierLot": "SUP-A1" } }, "serials": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptSerialDto" } } }, "required": [ "quantity" ] }, "InventoryOutboundLineSerialResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialId": { "type": "string", "format": "uuid" }, "pickedAt": { "type": "object", "format": "date-time", "nullable": true }, "packedAt": { "type": "object", "format": "date-time", "nullable": true }, "shippedAt": { "type": "object", "format": "date-time", "nullable": true }, "serial": { "$ref": "#/components/schemas/InventorySerialSummaryResponseDto" } }, "required": [ "id", "serialId", "serial" ] }, "InventoryOutboundLineResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "outboundId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "requestedQuantity": { "type": "number" }, "allocatedQuantity": { "type": "number" }, "pickedQuantity": { "type": "number" }, "packedQuantity": { "type": "number" }, "fulfilledQuantity": { "type": "number" }, "pendingAllocationQuantity": { "type": "number" }, "pendingPickQuantity": { "type": "number" }, "pendingPackQuantity": { "type": "number" }, "pendingFulfillmentQuantity": { "type": "number" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "serials": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryOutboundLineSerialResponseDto" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "outboundId", "productId", "locationId", "ownerId", "channelId", "requestedQuantity", "allocatedQuantity", "pickedQuantity", "packedQuantity", "fulfilledQuantity", "pendingAllocationQuantity", "pendingPickQuantity", "pendingPackQuantity", "pendingFulfillmentQuantity", "serials", "createdAt", "updatedAt" ] }, "InventoryOutboundResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "requestedQuantity": { "type": "number" }, "allocatedQuantity": { "type": "number" }, "pickedQuantity": { "type": "number" }, "packedQuantity": { "type": "number" }, "fulfilledQuantity": { "type": "number" }, "pendingAllocationQuantity": { "type": "number" }, "pendingPickQuantity": { "type": "number" }, "pendingPackQuantity": { "type": "number" }, "pendingFulfillmentQuantity": { "type": "number" }, "status": { "type": "string", "enum": [ "backordered", "partiallyAllocated", "allocated", "partiallyPicked", "picked", "partiallyPacked", "packed", "partiallyFulfilled", "fulfilled", "cancelled" ] }, "customerName": { "type": "object", "nullable": true }, "externalOrderType": { "type": "object", "nullable": true }, "externalOrderId": { "type": "object", "nullable": true }, "expectedShipAt": { "type": "object", "format": "date-time", "nullable": true }, "allocatedAt": { "type": "object", "format": "date-time", "nullable": true }, "fulfilledAt": { "type": "object", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "object", "format": "date-time", "nullable": true }, "referenceType": { "type": "object", "nullable": true }, "referenceId": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "version": { "type": "number" }, "createdBy": { "type": "object", "format": "uuid", "nullable": true }, "actor": { "$ref": "#/components/schemas/ActorResponseDto" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryOutboundLineResponseDto" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "ownerId", "channelId", "requestedQuantity", "allocatedQuantity", "pickedQuantity", "packedQuantity", "fulfilledQuantity", "pendingAllocationQuantity", "pendingPickQuantity", "pendingPackQuantity", "pendingFulfillmentQuantity", "status", "version", "actor", "lines", "createdAt", "updatedAt" ] }, "OutboundOperationResponseDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } }, "outbound": { "$ref": "#/components/schemas/InventoryOutboundResponseDto" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" } } }, "required": [ "balance", "movements", "outbound", "balances" ] }, "CreateOutboundLineDto": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product id requested for this outbound line." }, "locationId": { "type": "string", "description": "Location id where this line should ship from." }, "requestedQuantity": { "type": "number", "minimum": 1 } }, "required": [ "productId", "locationId", "requestedQuantity" ] }, "CreateOutboundDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Product id requested in this outbound. Required when lines is omitted." }, "locationId": { "type": "string", "description": "Location id where stock should ship from. Required when lines is omitted." }, "requestedQuantity": { "type": "number", "minimum": 1, "description": "Requested quantity. Required when lines is omitted." }, "lines": { "description": "Line-level products, origin locations, and requested quantities. When present, parent quantities are aggregated from lines.", "type": "array", "items": { "$ref": "#/components/schemas/CreateOutboundLineDto" } }, "customerName": { "type": "string", "example": "Acme Customer" }, "externalOrderType": { "type": "string", "example": "sales_order" }, "externalOrderId": { "type": "string", "example": "so_01JABC" }, "expectedShipAt": { "format": "date-time", "type": "string", "example": "2026-07-10T12:00:00.000Z" }, "referenceType": { "type": "string", "example": "outbound" }, "referenceId": { "type": "string", "example": "out_01JABC" }, "metadata": { "type": "object", "example": { "channel": "web" } } } }, "InventoryOutboundsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryOutboundResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "AllocateOutboundDto": { "type": "object", "properties": { "quantity": { "type": "number", "minimum": 1, "description": "Quantity to allocate. Omit to allocate as much pending quantity as available stock allows." } } }, "FulfillOutboundDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "serialIds": { "description": "Existing serial ids to apply to this operation.", "type": "array", "items": { "type": "string" } }, "serialNumbers": { "description": "Existing serial numbers to apply to this operation.", "type": "array", "items": { "type": "string" } }, "quantity": { "type": "number", "minimum": 1, "description": "Quantity to fulfill. Omit to fulfill all allocated pending quantity." }, "reason": { "type": "string", "example": "Shipment created" }, "metadata": { "type": "object", "example": { "carrier": "UPS" } } } }, "ProgressOutboundLineDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "serialIds": { "description": "Existing serial ids to apply to this operation.", "type": "array", "items": { "type": "string" } }, "serialNumbers": { "description": "Existing serial numbers to apply to this operation.", "type": "array", "items": { "type": "string" } }, "lineId": { "type": "string", "description": "Outbound line id to progress." }, "quantity": { "type": "number", "minimum": 1 }, "lotId": { "type": "string", "description": "Lot id to consume from for this line." }, "lotStrategy": { "type": "string", "enum": [ "fefo" ], "description": "Automatic lot selection strategy. FEFO consumes earliest expiring stock first." } }, "required": [ "lineId", "quantity" ] }, "ProgressOutboundDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "serialIds": { "description": "Existing serial ids to apply to this operation.", "type": "array", "items": { "type": "string" } }, "serialNumbers": { "description": "Existing serial numbers to apply to this operation.", "type": "array", "items": { "type": "string" } }, "quantity": { "type": "number", "minimum": 1, "description": "Quantity to progress across lines. Omit to progress all currently eligible quantity." }, "lines": { "description": "Line-level quantities to progress. Do not combine with quantity.", "type": "array", "items": { "$ref": "#/components/schemas/ProgressOutboundLineDto" } }, "reason": { "type": "string", "example": "Picked from bin A-01" }, "metadata": { "type": "object", "example": { "carrier": "UPS" } }, "lotId": { "type": "string", "description": "Lot id to consume from." }, "lotStrategy": { "type": "string", "enum": [ "fefo" ], "description": "Automatic lot selection strategy. FEFO consumes earliest expiring stock first." } } }, "ReservationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "committed", "released", "expired", "cancelled" ] }, "expiresAt": { "format": "date-time", "type": "string" }, "referenceType": { "type": "object", "nullable": true }, "referenceId": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdBy": { "type": "object", "format": "uuid", "nullable": true }, "actor": { "$ref": "#/components/schemas/ActorResponseDto" }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "location": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "locationId", "ownerId", "channelId", "quantity", "status", "expiresAt", "actor", "createdAt", "updatedAt" ] }, "ReservationOperationResponseDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } }, "reservation": { "$ref": "#/components/schemas/ReservationResponseDto" } }, "required": [ "balance", "movements", "reservation" ] }, "CreateReservationDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Product id to reserve." }, "locationId": { "type": "string", "description": "Location id reserving stock." }, "quantity": { "type": "number", "minimum": 1 }, "expiresAt": { "format": "date-time", "type": "string", "description": "Date and time when the reservation should expire.", "example": "2026-06-23T18:30:00.000Z" }, "referenceType": { "type": "string", "example": "checkout" }, "referenceId": { "type": "string", "example": "cart_01JABC" }, "metadata": { "type": "object", "example": { "channel": "web" } } }, "required": [ "productId", "locationId", "quantity", "expiresAt" ] }, "ReservationsPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReservationResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "InventoryTransferResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "productId": { "type": "string", "format": "uuid" }, "sourceLocationId": { "type": "string", "format": "uuid" }, "destinationLocationId": { "type": "string", "format": "uuid" }, "ownerId": { "type": "string", "format": "uuid" }, "channelId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number" }, "shippedQuantity": { "type": "number" }, "receivedQuantity": { "type": "number" }, "pendingShipmentQuantity": { "type": "number" }, "pendingReceiveQuantity": { "type": "number" }, "status": { "type": "string", "enum": [ "inTransit", "received", "cancelled", "closed" ] }, "referenceType": { "type": "object", "nullable": true }, "referenceId": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdBy": { "type": "object", "format": "uuid", "nullable": true }, "actor": { "$ref": "#/components/schemas/ActorResponseDto" }, "shippedAt": { "type": "object", "format": "date-time", "nullable": true }, "receivedAt": { "type": "object", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "object", "format": "date-time", "nullable": true }, "closedAt": { "type": "object", "format": "date-time", "nullable": true }, "closeReason": { "type": "object", "nullable": true }, "product": { "$ref": "#/components/schemas/ProductSummaryResponseDto" }, "sourceLocation": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "destinationLocation": { "$ref": "#/components/schemas/LocationSummaryResponseDto" }, "owner": { "$ref": "#/components/schemas/InventoryOwnerSummaryResponseDto" }, "channel": { "$ref": "#/components/schemas/InventoryChannelSummaryResponseDto" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "productId", "sourceLocationId", "destinationLocationId", "ownerId", "channelId", "quantity", "shippedQuantity", "receivedQuantity", "pendingShipmentQuantity", "pendingReceiveQuantity", "status", "actor", "createdAt", "updatedAt" ] }, "TransferSourceOperationResponseDto": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/InventoryTransferResponseDto" }, "sourceBalance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } } }, "required": [ "transfer", "sourceBalance", "movements" ] }, "CreateTransferDto": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "Inventory owner id. Defaults to the organization default owner." }, "channelId": { "type": "string", "description": "Inventory channel id. Defaults to the organization default channel." }, "productId": { "type": "string", "description": "Product id to transfer." }, "sourceLocationId": { "type": "string", "description": "Location id where stock leaves from." }, "destinationLocationId": { "type": "string", "description": "Location id where stock is received into." }, "quantity": { "type": "number", "minimum": 1 }, "shipQuantity": { "type": "number", "minimum": 1, "description": "Quantity to ship immediately. Omit to ship the full transfer quantity." }, "referenceType": { "type": "string", "example": "internal_transfer" }, "referenceId": { "type": "string", "example": "transfer_01JABC" }, "metadata": { "type": "object", "example": { "channel": "panel" } } }, "required": [ "productId", "sourceLocationId", "destinationLocationId", "quantity" ] }, "InventoryTransfersPageResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryTransferResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "ShipTransferDto": { "type": "object", "properties": { "quantity": { "type": "number", "minimum": 1, "description": "Quantity to ship. Omit to ship the full pending shipment quantity." } } }, "TransferDestinationOperationResponseDto": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/InventoryTransferResponseDto" }, "destinationBalance": { "$ref": "#/components/schemas/InventoryBalanceResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } } }, "required": [ "transfer", "destinationBalance", "movements" ] }, "ReceiveTransferDto": { "type": "object", "properties": { "quantity": { "type": "number", "minimum": 1, "description": "Quantity to receive. Omit to receive the full pending transfer quantity." } } }, "TransferOperationResponseDto": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/InventoryTransferResponseDto" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockLedgerResponseDto" } } }, "required": [ "transfer", "movements" ] }, "CloseTransferDto": { "type": "object", "properties": { "reason": { "type": "string", "example": "Source shortage confirmed during cycle count.", "maxLength": 240, "description": "Auditable reason for closing the transfer with differences." } }, "required": [ "reason" ] }, "ReportExportJobResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "reportType": { "type": "string", "enum": [ "inventory_snapshot", "stock_movements", "operations_summary", "exceptions" ] }, "format": { "type": "string", "enum": [ "csv", "xlsx" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "filters": { "type": "object", "nullable": true, "additionalProperties": true }, "rowCount": { "type": "number", "description": "Number of rows captured in the temporary export snapshot.", "minimum": 0 }, "downloadAvailable": { "type": "boolean", "description": "Whether the completed snapshot is still available for on-demand file generation." }, "hasFile": { "type": "boolean", "description": "Deprecated compatibility alias for downloadAvailable. No server-side file is stored." }, "expiresAt": { "format": "date-time", "type": "string" }, "requestedBy": { "type": "object", "nullable": true }, "completedAt": { "type": "object", "format": "date-time", "nullable": true }, "errorCode": { "type": "object", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "environment", "reportType", "format", "status", "rowCount", "downloadAvailable", "hasFile", "expiresAt", "createdAt", "updatedAt" ] }, "ListReportExportJobsResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReportExportJobResponseDto" } }, "nextCursor": { "type": "object", "nullable": true } }, "required": [ "items" ] }, "InventorySnapshotReportRowResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "locationId": { "type": "string", "format": "uuid" }, "locationName": { "type": "string" }, "locationCode": { "type": "string" }, "ownerId": { "type": "string", "format": "uuid" }, "ownerName": { "type": "string" }, "ownerCode": { "type": "string" }, "channelId": { "type": "string", "format": "uuid" }, "channelName": { "type": "string" }, "channelCode": { "type": "string" }, "onHand": { "type": "number" }, "available": { "type": "number" }, "reserved": { "type": "number" }, "committed": { "type": "number" }, "incoming": { "type": "number" }, "damaged": { "type": "number" }, "qualityControl": { "type": "number" }, "safetyStock": { "type": "number" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "productId", "productName", "productSku", "locationId", "locationName", "locationCode", "ownerId", "ownerName", "ownerCode", "channelId", "channelName", "channelCode", "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock", "updatedAt" ] }, "InventorySnapshotReportResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySnapshotReportRowResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "StockMovementsReportRowResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "format": "date-time", "type": "string" }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "locationId": { "type": "string", "format": "uuid" }, "locationName": { "type": "string" }, "locationCode": { "type": "string" }, "ownerId": { "type": "string", "format": "uuid" }, "ownerName": { "type": "string" }, "ownerCode": { "type": "string" }, "channelId": { "type": "string", "format": "uuid" }, "channelName": { "type": "string" }, "channelCode": { "type": "string" }, "operation": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] }, "inventoryState": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] }, "quantity": { "type": "number" }, "unitCode": { "type": "object", "nullable": true }, "unitQuantity": { "type": "object", "nullable": true }, "baseUnitCode": { "type": "object", "nullable": true }, "balanceBefore": { "type": "number" }, "balanceAfter": { "type": "number" }, "referenceType": { "type": "object", "nullable": true }, "referenceId": { "type": "object", "nullable": true }, "reason": { "type": "object", "nullable": true }, "source": { "type": "object", "nullable": true }, "actorType": { "type": "string", "enum": [ "user", "api_key", "system" ], "nullable": true }, "actorId": { "type": "object", "format": "uuid", "nullable": true }, "actorLabel": { "type": "object", "nullable": true } }, "required": [ "id", "createdAt", "productId", "productName", "productSku", "locationId", "locationName", "locationCode", "ownerId", "ownerName", "ownerCode", "channelId", "channelName", "channelCode", "operation", "inventoryState", "quantity", "balanceBefore", "balanceAfter" ] }, "StockMovementsReportResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StockMovementsReportRowResponseDto" } }, "nextCursor": { "type": "object", "format": "uuid", "nullable": true } }, "required": [ "items" ] }, "OperationsSummaryReportRowResponseDto": { "type": "object", "properties": { "operationType": { "type": "string" }, "status": { "type": "string" }, "count": { "type": "number" }, "totalQuantity": { "type": "number" }, "completedQuantity": { "type": "number" }, "pendingQuantity": { "type": "number" } }, "required": [ "operationType", "status", "count", "totalQuantity", "completedQuantity", "pendingQuantity" ] }, "OperationsSummaryReportResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OperationsSummaryReportRowResponseDto" } }, "nextCursor": { "type": "object", "nullable": true } }, "required": [ "items" ] }, "ExceptionsReportRowResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "exceptionType": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "locationId": { "type": "object", "format": "uuid", "nullable": true }, "locationName": { "type": "object", "nullable": true }, "locationCode": { "type": "object", "nullable": true }, "ownerId": { "type": "string", "format": "uuid" }, "ownerName": { "type": "string" }, "ownerCode": { "type": "string" }, "channelId": { "type": "string", "format": "uuid" }, "channelName": { "type": "string" }, "channelCode": { "type": "string" }, "quantity": { "type": "number" }, "completedQuantity": { "type": "number" }, "pendingQuantity": { "type": "number" }, "message": { "type": "string" }, "occurredAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "exceptionType", "resourceType", "resourceId", "status", "productId", "productName", "productSku", "ownerId", "ownerName", "ownerCode", "channelId", "channelName", "channelCode", "quantity", "completedQuantity", "pendingQuantity", "message", "occurredAt" ] }, "ExceptionsReportResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionsReportRowResponseDto" } }, "nextCursor": { "type": "object", "nullable": true } }, "required": [ "items" ] }, "ReportExportFiltersDto": { "type": "object", "properties": { "createdFrom": { "type": "string", "format": "date-time" }, "createdTo": { "type": "string", "format": "date-time" }, "productId": { "type": "string" }, "locationId": { "type": "string" }, "ownerId": { "type": "string" }, "channelId": { "type": "string" }, "status": { "type": "string" }, "operation": { "type": "string", "enum": [ "receive", "adjust", "fulfill", "write_off", "return_stock", "move_state", "reconcile", "reserve", "commit", "release", "reservation_cancel", "expire", "transfer_out", "transfer_in", "transfer_cancel", "transfer_close", "inbound_expect", "inbound_receive", "inbound_close", "inbound_cancel", "outbound_allocate", "outbound_pick", "outbound_pack", "outbound_ship", "outbound_fulfill", "outbound_cancel", "composition_assemble_component", "composition_assemble_output", "composition_disassemble_input", "composition_disassemble_component" ] }, "inventoryState": { "type": "string", "enum": [ "onHand", "available", "reserved", "committed", "incoming", "damaged", "qualityControl", "safetyStock" ] }, "limit": { "type": "number", "minimum": 1, "maximum": 5000, "default": 5000 } } }, "CreateReportExportDto": { "type": "object", "properties": { "reportType": { "type": "string", "enum": [ "inventory_snapshot", "stock_movements", "operations_summary", "exceptions" ] }, "format": { "type": "string", "enum": [ "csv", "xlsx" ] }, "filters": { "$ref": "#/components/schemas/ReportExportFiltersDto" } }, "required": [ "reportType", "format" ] } } }, "security": [ { "ApiKey": [] } ] }