> ## Documentation Index > Fetch the complete documentation index at: https://docs.joinluminous.com/llms.txt > Use this file to discover all available pages before exploring further. # Inventory stock > Get a paginated list of inventory stock levels with various filter options. For detailed information about the filtering system and available operators, refer to the [Filter System Documentation](/filters). ## ⚠️ Important: Default Sorting and Pagination **By default, results are sorted by `updated_at` in descending order.** This field changes frequently as stock levels are updated, which can cause issues when paginating through results: - Items may be skipped or duplicated between pages - The same item may appear on multiple pages - Some items may never appear if they're updated while you're paginating **Recommendation:** When pulling all stocks or paginating through large datasets, use a more stable sort field such as: - `product.id:asc` - Sort by product ID (most stable) - `product.sku:asc` - Sort by product SKU - `product.name:asc` - Sort by product name Example: `?sort=product.id:asc&per_page=100` ## Available Sort Fields - `product.id` - Sort by product ID - `product.sku` - Sort by product SKU - `product.name` - Sort by product name - `updated_at` - Sort by last stock update date (default: `updated_at:desc`) Sort format: `field:direction` where direction is `asc` (ascending) or `desc` (descending). Examples: - `?sort=product.id:asc` - Sort by product ID ascending - `?sort=product.sku:desc` - Sort by product SKU descending - `?sort=product.name:asc` - Sort by product name ascending - `?sort=updated_at:asc` - Sort by update date ascending (overrides default) ## Available Filters ### Inventory Filters - `location`: Filter by location ID - `warehouse_ids`: Filter by warehouse ID(s), comma-separated - `warehouse_group_ids`: Filter by warehouse group ID(s), comma-separated - `qty_onhand`: Filter by quantity on hand - `qty_pending`: Filter by pending quantity - `qty_available`: Filter by available quantity - `qty_incoming`: Filter by incoming quantity - `qty_backordered`: Filter by quantity backordered - `qty_available_via_assembly`: Filter by quantity available via assembly - `qty_recoverable_via_disassembly`: Filter by quantity recoverable via disassembly - `qty_outstanding`: Filter by quantity outstanding - `updated_at`: Filter by last stock update date - `discontinued`: Filter by discontinued status (0 = not discontinued, 1 = discontinued, 2+ = all) - `sku`: Filter by SKU (searches product name, internal SKU, UPC, and alternate SKUs) - `product_name`: Filter by product name - `category_id`: Filter by category ID(s), comma-separated - `subcategory_ids`: Filter by subcategory ID(s), comma-separated ### Product String Filters - `product.name`: Product name - `product.description`: Product description - `product.sku`: Product SKU (searches both internal SKU and alternate SKUs) - `product.upc`: Product UPC/Barcode - `product.tag`: Product tags - `product.q`: General search matches name OR upc OR sku - `product.category.name`: Filter by category name - `product.sub_category.name`: Filter by sub-category name - `product.supplier.name`: Filter by supplier name ### Product Integer Filters - `product.id`: Filter by product ID - `product.category.id`: Filter by category ID - `product.sub_category.id`: Filter by sub-category ID - `product.supplier.id`: Filter by supplier ID - `product_type_id`: Filter by product type ID ### Product String Filters (Product Type) - `product_type`: Filter by product type ### Product Float Filters - `product.retail_price`: Product retail price - `product.wholesale_price`: Product wholesale price - `product.product_weight`: Product weight - `product.product_length`: Product length (in inches) - `product.product_width`: Product width (in inches) - `product.product_height`: Product height (in inches) - `product.box_length`: Box length (in inches) - `product.box_width`: Box width (in inches) - `product.box_height`: Box height (in inches) - `product.carton_length`: Carton length (in inches) - `product.carton_width`: Carton width (in inches) - `product.carton_height`: Carton height (in inches) - `product.shipping_length`: Shipping length (in inches) - `product.shipping_width`: Shipping width (in inches) - `product.shipping_height`: Shipping height (in inches) - `product.pallet_length`: Pallet length (in inches) - `product.pallet_width`: Pallet width (in inches) - `product.pallet_height`: Pallet height (in inches) ### Product String Filters (Dimension Weights) - `product.box_weight`: Box weight - `product.carton_weight`: Carton weight - `product.shipping_weight`: Shipping weight - `product.pallet_weight`: Pallet weight ### Product Boolean Filters - `product.sellable`: If the product is sellable or not - `product.discontinued`: If the product is discontinued ### Product DateTime Filters - `product.created_at`: When the product was created - `product.updated_at`: When the product was last updated ## Examples ``` # Find stock for products by SKU ?product.sku[eq]=SKU-001 # Find stock for products by multiple SKUs ?product.sku[in]=SKU-001,SKU-002,SKU-003 # Find stock for specific product by ID ?product.id[eq]=12345 # Find stock for multiple products by ID ?product.id[in]=12345,67890,11111 # Find stock for products in specific price range ?product.retail_price[gte]=50.00&product.retail_price[lte]=100.00 # Find stock for recently updated products ?product.updated_at[gte]=2024-01-01 00:00:00 # Find stock for products where name contains "Partial text" ?product.name[contains]=Partial text # Find stock for products in specific category and location ?product.category.name[eq]=Electronics&location=123 # Find stock for products from specific supplier in certain warehouses ?product.supplier.name[contains]=Acme&warehouse_ids=1,2,3 # Find stock with specific quantity levels ?qty_onhand[gte]=100&qty_available[gt]=0 # Find stock with low inventory ?qty_onhand[lte]=10 # Find stock with pending quantities ?qty_pending[gt]=0 # Find stock with incoming inventory ?qty_incoming[gte]=50 # Find stock with backordered quantities ?qty_backordered[gt]=0 # Find stock with assembly availability ?qty_available_via_assembly[gte]=10 # Find stock recoverable via disassembly ?qty_recoverable_via_disassembly[gt]=5 # Find stock with outstanding quantities ?qty_outstanding[gt]=0 # Find stock updated after a specific date ?updated_at[gte]=2024-01-01 00:00:00 # Find stock by product type ?product_type[eq]=KIT # Find stock by product type ID ?product_type_id[eq]=1 # Find stock for sellable products only ?product.sellable=1 # Find stock for discontinued products ?product.discontinued=1 # Search across multiple product fields ?product.q[contains]=laptop # Sort examples (recommended for pagination) # Sort by product ID for stable pagination ?sort=product.id:asc&per_page=100 # Sort by product SKU ?sort=product.sku:asc # Sort by product name ?sort=product.name:asc # Sort by update date ascending (overrides default DESC) ?sort=updated_at:asc # Combine sorting with filters ?product.category.id[eq]=5&sort=product.name:asc&per_page=50 ``` ## OpenAPI ````yaml /api-reference/build.yaml get /inventory/stocks openapi: 3.0.0 info: title: Luminous API version: 1.0.0 description: API documentation for Luminous servers: - url: https://{companyName}.api.joinluminous.com/external/api/v1 variables: companyName: default: companyName description: Your company-specific subdomain security: [] tags: - name: Products description: Get and manage products - name: Pricing description: Manage price schedules, levels, and customizations - name: BOMs description: Manage Bills of Materials (BOMs) - name: Labels description: Label rendering via Labelary ZPL service - name: Companies description: Manage business accounts and their associated data - name: Contacts description: Manage contact information for individuals - name: Suppliers description: Manage suppliers (factories) — vendors used on purchase orders - name: Supplier SKUs description: Manage per-supplier SKU and unit-cost overrides for products - name: Locations description: Manage warehouses and locations - name: Inventory description: Get and adjust product stock levels - name: Lots description: Create, update, and delete product lots (batches) - name: Transfer Orders description: Manage transfer orders - name: Fulfillment Orders description: Manage fulfillment orders and picklists - name: Purchase Orders description: Get and modify purchase orders - name: Receiving Reports description: Manage receiving reports - name: Payment Obligations description: Manage payment obligations for purchase orders - name: Sales Orders description: Manage sales orders and sales order shipments - name: Purgatory description: >- Inspect and resolve non-posted sales orders in the purgatory staging workflow - name: PickFlow Shipping description: >- Provider-agnostic shipping rates, services, packages, and label purchase for PickFlow - name: Cycle Counts description: >- Create, drive, and post PickFlow cycle counts — batches, per-warehouse sessions, and CSV import/export - name: Print Stations description: List paired print stations and enqueue print jobs to them - name: Invoices description: Get and manage invoices - name: Work Orders description: >- Manage work orders — production lifecycle, steps, materials, links, shipments, and comments - name: Production Batches description: Group and manage work orders as production batches - name: Bills description: >- Accounts payable bill management, payments, attachments, allocations, and variance - name: Prepayments description: Manage vendor prepayments and applications - name: Vendor Credits description: Manage vendor credits and applications - name: Vendor Returns description: Manage vendor returns and credit generation - name: Customer Returns description: Manage customer returns (sales returns), receiving, and restock behavior - name: Stock Snapshot description: Point-in-time stock snapshots with export support - name: Consumption description: Consumption reports and exports - name: Inventory Aging description: Cost-layer-based inventory aging reports - name: Bills Reports description: Accounts payable bills aging reports - name: Forecast description: Materialized forecast data - name: Reports description: Close the books, inventory discrepancy, transaction COGS, and EDI reports - name: Tags description: Add/remove tags across various resources - name: Custom Fields description: Get and set custom fields across various resources - name: Currency description: Currency configuration, exchange rates, and conversion - name: Integration Mappings description: Manage integration mappings for external systems - name: Integration Field Mappings description: Manage field-level mappings between Luminous and external systems paths: /inventory/stocks: get: tags: - Inventory summary: Inventory stock description: > Get a paginated list of inventory stock levels with various filter options. For detailed information about the filtering system and available operators, refer to the [Filter System Documentation](/filters). ## ⚠️ Important: Default Sorting and Pagination **By default, results are sorted by `updated_at` in descending order.** This field changes frequently as stock levels are updated, which can cause issues when paginating through results: - Items may be skipped or duplicated between pages - The same item may appear on multiple pages - Some items may never appear if they're updated while you're paginating **Recommendation:** When pulling all stocks or paginating through large datasets, use a more stable sort field such as: - `product.id:asc` - Sort by product ID (most stable) - `product.sku:asc` - Sort by product SKU - `product.name:asc` - Sort by product name Example: `?sort=product.id:asc&per_page=100` ## Available Sort Fields - `product.id` - Sort by product ID - `product.sku` - Sort by product SKU - `product.name` - Sort by product name - `updated_at` - Sort by last stock update date (default: `updated_at:desc`) Sort format: `field:direction` where direction is `asc` (ascending) or `desc` (descending). Examples: - `?sort=product.id:asc` - Sort by product ID ascending - `?sort=product.sku:desc` - Sort by product SKU descending - `?sort=product.name:asc` - Sort by product name ascending - `?sort=updated_at:asc` - Sort by update date ascending (overrides default) ## Available Filters ### Inventory Filters - `location`: Filter by location ID - `warehouse_ids`: Filter by warehouse ID(s), comma-separated - `warehouse_group_ids`: Filter by warehouse group ID(s), comma-separated - `qty_onhand`: Filter by quantity on hand - `qty_pending`: Filter by pending quantity - `qty_available`: Filter by available quantity - `qty_incoming`: Filter by incoming quantity - `qty_backordered`: Filter by quantity backordered - `qty_available_via_assembly`: Filter by quantity available via assembly - `qty_recoverable_via_disassembly`: Filter by quantity recoverable via disassembly - `qty_outstanding`: Filter by quantity outstanding - `updated_at`: Filter by last stock update date - `discontinued`: Filter by discontinued status (0 = not discontinued, 1 = discontinued, 2+ = all) - `sku`: Filter by SKU (searches product name, internal SKU, UPC, and alternate SKUs) - `product_name`: Filter by product name - `category_id`: Filter by category ID(s), comma-separated - `subcategory_ids`: Filter by subcategory ID(s), comma-separated ### Product String Filters - `product.name`: Product name - `product.description`: Product description - `product.sku`: Product SKU (searches both internal SKU and alternate SKUs) - `product.upc`: Product UPC/Barcode - `product.tag`: Product tags - `product.q`: General search matches name OR upc OR sku - `product.category.name`: Filter by category name - `product.sub_category.name`: Filter by sub-category name - `product.supplier.name`: Filter by supplier name ### Product Integer Filters - `product.id`: Filter by product ID - `product.category.id`: Filter by category ID - `product.sub_category.id`: Filter by sub-category ID - `product.supplier.id`: Filter by supplier ID - `product_type_id`: Filter by product type ID ### Product String Filters (Product Type) - `product_type`: Filter by product type ### Product Float Filters - `product.retail_price`: Product retail price - `product.wholesale_price`: Product wholesale price - `product.product_weight`: Product weight - `product.product_length`: Product length (in inches) - `product.product_width`: Product width (in inches) - `product.product_height`: Product height (in inches) - `product.box_length`: Box length (in inches) - `product.box_width`: Box width (in inches) - `product.box_height`: Box height (in inches) - `product.carton_length`: Carton length (in inches) - `product.carton_width`: Carton width (in inches) - `product.carton_height`: Carton height (in inches) - `product.shipping_length`: Shipping length (in inches) - `product.shipping_width`: Shipping width (in inches) - `product.shipping_height`: Shipping height (in inches) - `product.pallet_length`: Pallet length (in inches) - `product.pallet_width`: Pallet width (in inches) - `product.pallet_height`: Pallet height (in inches) ### Product String Filters (Dimension Weights) - `product.box_weight`: Box weight - `product.carton_weight`: Carton weight - `product.shipping_weight`: Shipping weight - `product.pallet_weight`: Pallet weight ### Product Boolean Filters - `product.sellable`: If the product is sellable or not - `product.discontinued`: If the product is discontinued ### Product DateTime Filters - `product.created_at`: When the product was created - `product.updated_at`: When the product was last updated ## Examples ``` # Find stock for products by SKU ?product.sku[eq]=SKU-001 # Find stock for products by multiple SKUs ?product.sku[in]=SKU-001,SKU-002,SKU-003 # Find stock for specific product by ID ?product.id[eq]=12345 # Find stock for multiple products by ID ?product.id[in]=12345,67890,11111 # Find stock for products in specific price range ?product.retail_price[gte]=50.00&product.retail_price[lte]=100.00 # Find stock for recently updated products ?product.updated_at[gte]=2024-01-01 00:00:00 # Find stock for products where name contains "Partial text" ?product.name[contains]=Partial text # Find stock for products in specific category and location ?product.category.name[eq]=Electronics&location=123 # Find stock for products from specific supplier in certain warehouses ?product.supplier.name[contains]=Acme&warehouse_ids=1,2,3 # Find stock with specific quantity levels ?qty_onhand[gte]=100&qty_available[gt]=0 # Find stock with low inventory ?qty_onhand[lte]=10 # Find stock with pending quantities ?qty_pending[gt]=0 # Find stock with incoming inventory ?qty_incoming[gte]=50 # Find stock with backordered quantities ?qty_backordered[gt]=0 # Find stock with assembly availability ?qty_available_via_assembly[gte]=10 # Find stock recoverable via disassembly ?qty_recoverable_via_disassembly[gt]=5 # Find stock with outstanding quantities ?qty_outstanding[gt]=0 # Find stock updated after a specific date ?updated_at[gte]=2024-01-01 00:00:00 # Find stock by product type ?product_type[eq]=KIT # Find stock by product type ID ?product_type_id[eq]=1 # Find stock for sellable products only ?product.sellable=1 # Find stock for discontinued products ?product.discontinued=1 # Search across multiple product fields ?product.q[contains]=laptop # Sort examples (recommended for pagination) # Sort by product ID for stable pagination ?sort=product.id:asc&per_page=100 # Sort by product SKU ?sort=product.sku:asc # Sort by product name ?sort=product.name:asc # Sort by update date ascending (overrides default DESC) ?sort=updated_at:asc # Combine sorting with filters ?product.category.id[eq]=5&sort=product.name:asc&per_page=50 ``` operationId: getInventoryStocks parameters: - in: query name: page schema: type: integer default: 1 description: Page number for pagination - in: query name: per_page schema: type: integer default: 100 description: Number of items per page - in: query name: sort schema: type: string default: updated_at:desc description: > Sort results by field and direction. Format: `field:direction` **⚠️ Warning:** Default sorting by `updated_at` changes frequently and can cause pagination issues. For stable pagination, use `product.id:asc`, `product.sku:asc`, or `product.name:asc`. Available sort fields: - `product.id` - Product ID - `product.sku` - Product SKU - `product.name` - Product name - `updated_at` - Last stock update date (default) Examples: - `product.id:asc` - Sort by product ID ascending - `product.sku:desc` - Sort by product SKU descending - `product.name:asc` - Sort by product name ascending - `updated_at:asc` - Sort by update date ascending - in: query name: location schema: type: integer description: Filter by location ID - in: query name: warehouse_ids schema: type: string description: Filter by warehouse ID(s), comma-separated - in: query name: warehouse_group_ids schema: type: string description: Filter by warehouse group ID(s), comma-separated - in: query name: qty_onhand schema: type: integer description: Filter by quantity on hand - in: query name: qty_pending schema: type: integer description: Filter by pending quantity - in: query name: qty_available schema: type: integer description: Filter by available quantity - in: query name: qty_incoming schema: type: integer description: Filter by incoming quantity - in: query name: qty_backordered schema: type: number format: float description: Filter by quantity backordered - in: query name: qty_available_via_assembly schema: type: number format: float description: Filter by quantity available via assembly - in: query name: qty_recoverable_via_disassembly schema: type: number format: float description: Filter by quantity recoverable via disassembly - in: query name: qty_outstanding schema: type: number format: float description: Filter by quantity outstanding - in: query name: updated_at schema: type: string format: date-time description: Filter by last stock update date - in: query name: discontinued schema: type: integer description: >- Filter by discontinued status (0 = not discontinued, 1 = discontinued, 2+ = all) - in: query name: sku schema: type: string description: >- Filter by SKU (searches product name, internal SKU, UPC, and alternate SKUs) - in: query name: product_name schema: type: string description: Filter by product name - in: query name: category_id schema: type: string description: Filter by category ID(s), comma-separated - in: query name: subcategory_ids schema: type: string description: Filter by subcategory ID(s), comma-separated - in: query name: product_type schema: type: string description: Filter by product type - in: query name: product_type_id schema: type: integer description: Filter by product type ID - in: query name: product.q schema: type: string description: Filter by name OR upc OR sku - in: query name: product.id schema: type: integer description: Filter by product ID - in: query name: product.name schema: type: string description: Filter by product name - in: query name: product.description schema: type: string description: Filter by product description - in: query name: product.sku schema: type: string description: Filter by SKU (searches both internal and alternate SKUs) - in: query name: product.upc schema: type: string description: Filter by UPC/Barcode - in: query name: product.sellable schema: type: boolean description: Filter by sellable status - in: query name: product.discontinued schema: type: boolean description: Filter by whether the product is discontinued - in: query name: product.retail_price schema: type: number format: float description: Filter by retail price - in: query name: product.wholesale_price schema: type: number format: float description: Filter by wholesale price - in: query name: product.created_at schema: type: string format: date-time description: Filter by creation date - in: query name: product.updated_at schema: type: string format: date-time description: Filter by last update date - in: query name: product.tag schema: type: string description: Filter by product tags - in: query name: product.category.id schema: type: integer description: Filter by category ID - in: query name: product.category.name schema: type: string description: Filter by category name - in: query name: product.sub_category.id schema: type: integer description: Filter by sub-category ID - in: query name: product.sub_category.name schema: type: string description: Filter by sub-category name - in: query name: product.supplier.id schema: type: integer description: Filter by supplier ID - in: query name: product.supplier.name schema: type: string description: Filter by supplier name responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string description: Product ID sku: type: string description: Product SKU name: type: string description: Name of the product type: type: string description: Type of the product qty_onhand: type: number format: float description: Total quantity on hand across all locations qty_pending: type: number format: float description: Total quantity pending across all locations qty_available: type: number format: float description: Total quantity available across all locations qty_incoming: type: number format: float description: Total quantity incoming across all locations qty_backordered: type: number format: float description: Total quantity backordered across all locations qty_available_via_assembly: type: number format: float description: >- Total quantity available via assembly across all locations qty_recoverable_via_disassembly: type: number format: float description: >- Total quantity recoverable via disassembly across all locations qty_outstanding: type: number format: float description: Total quantity outstanding across all locations current_landed_unit_cost: type: number format: float nullable: true description: > Current landed unit cost from the oldest active cost layer with remaining quantity across all warehouses. The cost is derived from cost layers using FIFO (First-In, First-Out) logic, selecting the oldest cost layer that has a remaining quantity greater than zero. Returns null if no active cost layer exists. updated_at: type: string format: date-time nullable: true description: Last update timestamp for the stock category_id: type: integer description: ID of the product category sub_category_id: type: integer description: ID of the product subcategory category_name: type: string description: Name of the product category sub_category_name: type: string description: Name of the product subcategory location_stocks: type: array items: type: object properties: id: type: integer nullable: true description: >- Stock location ID (null for virtual locations with no stock) warehouse: type: object properties: id: type: integer status: type: string name: type: string parent_id: type: integer nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time location: type: object properties: id: type: integer status: type: string name: type: string parent_id: type: integer nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time qty_onhand: type: number format: float description: Quantity on hand at location qty_pending: type: number format: float description: Quantity pending at location qty_available: type: number format: float description: Quantity available at location qty_incoming: type: number format: float description: Quantity incoming at location qty_available_via_assembly: type: number format: float description: Quantity available via assembly at location qty_recoverable_via_disassembly: type: number format: float description: >- Quantity recoverable via disassembly at location current_landed_unit_cost: type: number format: float nullable: true description: > Current landed unit cost from the oldest active cost layer with remaining quantity for this specific warehouse. The cost is derived from cost layers using FIFO (First-In, First-Out) logic, selecting the oldest cost layer that has a remaining quantity greater than zero. Returns null if no active cost layer exists. lot_stocks: type: array description: >- Per-lot stock breakdown at this location. Only populated for products with lot tracking enabled (and when lot data is loaded); otherwise an empty array. items: type: object properties: lot_id: type: integer description: Lot ID. lot_number: type: string nullable: true description: Lot number. manufacturer_code: type: string nullable: true description: Manufacturer code recorded on the lot. production_date: type: string format: date nullable: true description: Lot production date. expiry_date: type: string format: date nullable: true description: Lot expiry date. location_id: type: integer description: >- ID of the location holding this lot's stock. qty_onhand: type: number format: float description: >- Quantity on hand for this lot at the location. non_lot_stocks: type: array description: >- Per-bin breakdown of non-lot stock (stock rows with no lot) at this warehouse. Returned for all products, not just lot-tracked ones. The warehouse-level `location_stocks` rollup nets non-lot and lot layers together, so a non-lot layer offsetting a lot layer can be invisible in the rollup; this array surfaces each non-lot bin row individually. Empty for virtual (zero-stock) warehouse rows that have no stock-location data. items: type: object properties: location_id: type: integer description: >- ID of the bin (location) holding this non-lot stock. qty_onhand: type: number format: float description: >- Quantity on hand for this non-lot row at the bin. description: List of stock entries across all locations meta: type: object properties: current_page: type: integer description: The current page number example: 1 from: type: integer description: The starting index of the paginated results example: 1 last_page: type: integer description: The last page number example: 5 per_page: type: integer description: Number of items per page example: 10 to: type: integer description: The ending index of the paginated results example: 10 total: type: integer description: Total number of items across all pages example: 50 '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: >- Authenticate using a bearer token. To create a token, navigate to /settings/api-tokens and click Create API Token. ````