> ## Documentation Index > Fetch the complete documentation index at: https://docs.solya.app/llms.txt > Use this file to discover all available pages before exploring further. # List inventory movement lines (stock movements / transfers / receipts / adjustments) > Returns a paginated list of inventory movement lines — the stock movement events that change on-hand quantity: goods receipts (deliveries / receiving), transfers between shops, returns, and adjustments. Use this to trace stock flow and movement history. Filter by shop, product, brand, variant, inventory item, movement type, and date range. (For point-in-time stock levels use GET /inventory/stock; for the full ledger of stock transactions use GET /stock-ledger.) ## OpenAPI ````yaml /openapi.json get /api/movement-lines openapi: 3.0.3 info: contact: email: dev@solya.io name: Solya Team description: >- # Solya API Solya is a fashion retail inventory management platform for buyers and merchandisers. This API exposes all capabilities needed to manage the inventory lifecycle: catalog browsing, risk detection, plan creation (Restock / Markdown / Rebalance), analytics queries, and data-platform operations. ## Authentication Three authentication schemes are supported: | Scheme | Header | Use case | |---|---|---| | **BearerAuth** | `Authorization: Bearer ` | Human users via the Solya web app (NextAuth session) | | **InternalBearerAuth** | `Authorization: Bearer ` | Internal jobs and cron tasks (static token per service) | | **ServiceAccountToken** | `Authorization: Bearer solya_sa_*` | LLM agents and programmatic clients (opaque token created via Settings) | All endpoints except `GET /api/health` require one of the above. See [Agent authentication guide](/docs/api/AGENT_AUTH.md) for the Service Account token flow. ## Response format Every endpoint returns an `ActionResponse` envelope: **Success:** ```json { "success": true, "data": { ... } } ``` **Error:** ```json { "success": false, "errorCode": "PLAN_NOT_FOUND", "error": "Human-readable message" } ``` The `errorCode` is a stable machine-readable string (see common error codes below). The `error` field is for human display only and may change between versions. ## Pagination List endpoints accept `page` (1-indexed, default 1) and `pageSize` (default 20, max 100). Responses include a `total` field with the total number of matching records. ``` GET /api/shops?page=2&pageSize=50 → { "success": true, "data": { "data": [...], "total": 120, "page": 2, "pageSize": 50 } } ``` ## Common error codes | HTTP status | errorCode | Meaning | |---|---|---| | 401 | `UNAUTHORIZED` | Token missing, expired, or invalid | | 403 | `FORBIDDEN` | Token valid but lacks the required permission or scope | | 404 | `NOT_FOUND` | Requested resource does not exist | | 409 | `BUSINESS_RULE_VIOLATION` | Business rule blocked the operation (see response details) | | 422 | `VALIDATION_ERROR` | Input failed Zod schema validation | | 429 | `RATE_LIMIT_EXCEEDED` | Rate limit hit (100 req/min per token) | | 500 | `INTERNAL_ERROR` | Unexpected server error | ## Rate limiting Default limit: **100 requests per minute** per authentication token. When the limit is exceeded the API returns HTTP 429 with `errorCode: "RATE_LIMIT_EXCEEDED"`. Agents should implement exponential back-off and respect the `Retry-After` header when present. ## Further reading See the [Agent guide](/docs/api/AGENT_GUIDE.md) for end-to-end workflows, call-chaining patterns, and anti-patterns to avoid. license: name: Proprietary url: https://solya.app/terms title: Solya API version: 1.0.0 x-ai-context: >- Solya is a fashion retail inventory management platform for retailers. Core concepts: - **Organization** (tenant): every endpoint is scoped by organizationId extracted from the token. - **Shop**: a physical point of sale belonging to the organization. - **ProductVariant**: a SKU — a product variant with size and color. - **Plan**: a Restock / Markdown / Rebalance grouping PlanItems to orchestrate inventory decisions. Typical agent workflow: 1. List the organization's shops — GET /api/shops 2. List variants at risk (stockout, overstock, slow-mover) — GET /api/inventory/risks 3. Create a plan — POST /api/restock-plans, /api/markdown-plans, or /api/rebalance-plans 4. Add items to the plan — POST /api/restock-plans/{planId}/items (or equivalent for other plan types) 5. Validate / submit the plan via the corresponding action endpoint Auth: use a Service Account token (see /docs/api/AGENT_AUTH.md). The token is created by an org admin via Settings and has the format solya_sa_<43 base64url chars>. All responses follow the ActionResponse envelope: - Success: { success: true, data: T } - Error: { success: false, errorCode: string, error: string } Use the errorCode field to drive retry logic or surface user-facing messages. servers: - description: Current environment url: https://app.solya.app security: - BearerAuth: [] tags: - description: >- Health and liveness endpoints. Use GET /api/health to verify the service is reachable before starting a workflow. No authentication required. name: System - description: >- Physical points of sale belonging to the organization. Supports listing, creation, update, and deactivation. Shops are referenced by all Plan types (Restock, Markdown, Rebalance) and by every inventory analytics endpoint. name: Shops - description: >- Product brands configured for the organization. Brands are used to filter catalog queries and analytics. Supports CRUD operations. name: Brands - description: >- The product catalog: style-level entities grouping one or more ProductVariants. Supports listing with rich filter options (brand, family, gender, season) and individual retrieval. name: Products - description: >- SKU-level product entities (a Product with a specific size and color). Variants are the atomic unit referenced by PlanItems, inventory risk alerts, and analytics queries. name: Variants - description: >- Curated product groupings used for seasonal assortment management. A Collection groups Variants and can be referenced when creating or filtering Plans. name: Collections - description: >- Current on-hand stock records per Variant per Shop. Used to understand the live inventory position before creating a restock or rebalance plan. name: Inventory Items - description: >- AI-detected inventory risk signals: stockout risk, overstock, slow-movers, and displaced stock. The primary input for agents building recommendation-driven plans. Supports filtering by shop, brand, risk type, and severity. name: Inventory Risks - description: >- AI-generated restock quantity recommendations per Variant per Shop. Consumed by agents to pre-populate Restock plan items. Based on sales velocity, stock coverage, and lead time. name: Recommendations - Restock - description: >- AI-generated markdown discount recommendations for slow-moving or overstock Variants. Consumed by agents to pre-populate Markdown plan items. Includes recommended discount rate and expected clearance timeline. name: Recommendations - Markdown - description: >- AI-generated stock transfer recommendations between shops to balance supply with demand. Consumed by agents to pre-populate Rebalance plan items. name: Recommendations - Rebalance - description: >- Historical sales transaction lines at the Variant + Shop + date level. Used by analytics and by the AI recommendation engine. Supports date-range and multi-dimensional filtering. name: Sales Lines - description: >- Purchase order lines tracking inbound stock from suppliers. Combined with stock and sales data to compute forward coverage and restock needs. name: Order Lines - description: >- Inventory movement records (transfers, returns, adjustments). Used to reconcile the stock ledger and audit stock changes between shops. name: Movement Lines - description: >- Running stock balance log per Variant per Shop. Provides a point-in-time view of stock levels and is the source of truth for coverage computations. name: Stock Ledger - description: >- Rebalance plans orchestrate stock transfers between shops. Supports creating plans, adding Variant items with proposed transfer quantities, reviewing, and submitting. Business rules are evaluated on item addition. name: Plans - Rebalance - description: >- Restock plans (order plans) orchestrate purchase orders to suppliers. Supports creating sessions, adding Variant items with proposed order quantities, reviewing totals, and submitting. Integrates with the order plan workflow. name: Plans - Restock - description: >- Autocomplete and typeahead search endpoints for catalog dimensions: products, brands, shops, sizes, families, genders, and more. Designed for fast UI search (low latency, small result sets). Use catalog list endpoints for full paginated access. name: Search - description: >- Manage file-based data ingestion: upload CSV/XLSX files, poll ingestion status, list historical ingestion runs, and trigger batch reprocessing. Used by the data team to import POS data and catalog updates. name: Data Platform - File Ingestions - description: >- Organization-level configuration for the data platform: data source connections, POS integration settings, and ingestion schedules. Requires elevated permissions. name: Data Platform - Settings - description: >- Configuration of automated inventory alerts: threshold-based rules that monitor stock levels, sales velocity, and coverage gaps. Supports CRUD for alert definitions; alert evaluation runs are triggered by the data platform scheduler. name: Data Platform - Alerts - description: >- Endpoints designed for LLM agents and programmatic clients. These endpoints expose agent-optimized response shapes. Authenticate with a Service Account token (format: solya_sa_*) created via Settings → API Tokens. name: Agent externalDocs: description: >- Complete guide for LLM agents and programmatic clients: authentication, pagination patterns, ActionResponse interpretation, call chaining, business rule error handling. url: /docs/api/AGENT_GUIDE.md paths: /api/movement-lines: get: tags: - Movement Lines summary: >- List inventory movement lines (stock movements / transfers / receipts / adjustments) description: >- Returns a paginated list of inventory movement lines — the stock movement events that change on-hand quantity: goods receipts (deliveries / receiving), transfers between shops, returns, and adjustments. Use this to trace stock flow and movement history. Filter by shop, product, brand, variant, inventory item, movement type, and date range. (For point-in-time stock levels use GET /inventory/stock; for the full ledger of stock transactions use GET /stock-ledger.) operationId: listMovementLines parameters: - in: query name: page required: false schema: default: 1 description: 'Page number, 1-indexed (default: 1)' maximum: 9007199254740991 minimum: 1 type: integer - in: query name: pageSize required: false schema: default: 20 description: 'Number of items per page, max 100 (default: 20)' maximum: 100 minimum: 1 type: integer - in: query name: shopId required: false schema: description: Filter by shop UUID type: string - in: query name: productId required: false schema: description: Filter by product UUID type: string - in: query name: brandId required: false schema: description: Filter by brand UUID type: string - in: query name: variantId required: false schema: description: Filter by variant UUID type: string - in: query name: inventoryItemId required: false schema: description: Filter by inventory item UUID type: string - in: query name: movementType required: false schema: description: >- Movement type filter. NOTE: currently inactive — the underlying movement-type taxonomy column (movementInventoryMovementTypeTaxonomyId) is unpopulated (null) in this dataset, so this filter is ignored. Use variantId or inventoryItemId for reliable filtering, or the stock-ledger endpoint's movementType/movementCategory filters. type: string - in: query name: dateFrom required: false schema: description: >- Return lines where movementDate >= this value (inclusive). ISO 8601 date 'YYYY-MM-DD' (e.g. '2026-01-01') or datetime 'YYYY-MM-DDTHH:mm:ssZ' — both accepted. Filters on the movementDate column. type: string - in: query name: dateTo required: false schema: description: >- Return lines where movementDate <= this value (inclusive). ISO 8601 date 'YYYY-MM-DD' (e.g. '2026-12-31') or datetime 'YYYY-MM-DDTHH:mm:ssZ' — both accepted. Filters on the movementDate column. type: string - in: query name: sortBy required: false schema: description: >- Column to sort by. Allowed: 'movementDate', 'quantity', 'movementCost'. Defaults to 'movementDate'. type: string - in: query name: sortOrder required: false schema: description: >- Sort direction: 'asc' or 'desc'. Default order is movementDate descending (most recent first). enum: - asc - desc type: string responses: '200': content: application/json: examples: sample: summary: >- One movement line returned on the first page (full denormalized fact_movement_lines row) value: data: - brandCode: sandro brandId: demo-brand-8a771633 brandImageUrl: null brandMainBrandTypeTaxonomyFullPath: null brandMainBrandTypeTaxonomyId: null brandName: Sandro code: null createdAt: '2026-06-23T12:26:47.06048+00:00' inventoryItemCode: INV-001859 inventoryItemFullName: Pantalon de tailleur en laine froide - Noir - M inventoryItemId: demo-inv-item-ef722283 inventoryItemSku: SKU-001859 movementCode: MVT-RECV-00001385 movementCost: 554.2199999999998 movementDate: '2025-11-23' movementDateKey: 20251123 movementDayName: sunday movementDayOfMonth: 23 movementDayOfWeek: 7 movementDayOfYear: 327 movementDescription: Receipt for 2025-11-23 movementHolidayName: null movementId: 465f16fc-bf10-4abd-a899-04d93b9c9c21 movementInventoryMovementTypeTaxonomyFullPath: null movementInventoryMovementTypeTaxonomyId: null movementInventoryMovementTypeTaxonomyLanguage: null movementIsHoliday: false movementIsWeekend: true movementLineId: 000003de-afef-4913-a0ff-b9fdd4cce3eb movementMonthName: november movementMonthOfYear: 11 movementQuarter: 4 movementSeason: fall_winter movementTrimester: 4 movementWeekOfMonth: 4 movementWeekOfYear: 47 movementYear: 2025 organizationId: demo productCode: pantalon-de-tailleur-en-laine-froide productFamilyMainTaxonomyFullPath: Vêtements/Bas/Pantalons/Jeans (skinny, droits) productFamilyMainTaxonomyId: solya_family_fr_13cbee4d productGenderTaxonomyFullPath: Femme productGenderTaxonomyId: solya_gender_fr_43c65bcc productId: demo-product-d4b55f08 productImageUrl: null productIsActive: true productName: Pantalon de tailleur en laine froide quantity: 6 shopCity: Marseille shopCode: boutique-marseille-vieux-port shopCountry: bcbbd48b-f69c-4e02-85f5-90b919b1270b shopCountryId: bcbbd48b-f69c-4e02-85f5-90b919b1270b shopId: demo-shop-06490461 shopIsActive: true shopName: Boutique Marseille - Vieux Port shopRegion: Provence-Alpes-Côte d'Azur sizeTaxonomyFullPath: M sizeTaxonomyId: solya_size_fr_d0f2a7f5 sizeTaxonomyLanguage: fr unitCost: 92.36999999999996 updatedAt: '2026-06-23T12:26:47.06048+00:00' variantCode: pantalon-de-tailleur-en-laine-froide-noir variantCollectionId: demo-collection-ecd2effe variantCollectionName: Autumn/Winter 2025 variantColorTaxonomyFullPath: Couleurs Neutres/Neutre/Noirs/Noir variantDisplayName: Noir variantFullName: Pantalon de tailleur en laine froide - Noir variantGenderTaxonomyFullPath: null variantId: demo-variant-908e6e33 variantIsActive: true variantName: Pantalon de tailleur en laine froide - Noir variantSecondaryColorTaxonomyFullPath: null page: 1 pageSize: 20 total: 240568 schema: properties: data: properties: data: items: properties: brandCode: description: Reference code of the brand nullable: true type: string brandId: description: >- UUID of the brand associated with the moved variant nullable: true type: string brandImageUrl: description: URL of the brand logo image nullable: true type: string brandMainBrandTypeTaxonomyFullPath: description: >- Full taxonomy path of the brand's main brand-type classification nullable: true type: string brandMainBrandTypeTaxonomyId: description: >- UUID of the brand's main brand-type taxonomy node nullable: true type: string brandName: description: >- Display name of the brand associated with the moved variant nullable: true type: string code: description: >- Reference code of the movement line from the POS system nullable: true type: string createdAt: description: >- ISO 8601 datetime when the movement line record was created (format: date-time; 'T' separator, '+00:00' offset) nullable: true type: string inventoryItemCode: description: Reference code of the inventory item nullable: true type: string inventoryItemFullName: description: Full name of the inventory item (variant + size) nullable: true type: string inventoryItemId: description: >- UUID of the inventory item entry for this variant and shop nullable: true type: string inventoryItemSku: description: >- SKU of the inventory item as recorded in the POS system nullable: true type: string movementCode: description: Reference code of the parent movement document nullable: true type: string movementCost: description: >- Total cost of the movement (quantity × unit cost) nullable: true type: number movementDate: description: >- Date the movement occurred (ISO 8601 date 'YYYY-MM-DD') nullable: true type: string movementDateKey: description: >- Integer date key for the movement date (YYYYMMDD) nullable: true type: number movementDayName: description: >- Day-of-week name of the movement date (e.g. 'sunday') nullable: true type: string movementDayOfMonth: description: Day of month of the movement date (1-31) nullable: true type: number movementDayOfWeek: description: >- Day of week of the movement date (1=Monday … 7=Sunday) nullable: true type: number movementDayOfYear: description: Day of year of the movement date (1-366) nullable: true type: number movementDescription: description: >- Human-readable description of the movement (e.g. 'Receipt for 2025-11-23') nullable: true type: string movementHolidayName: description: >- Name of the holiday, if the movement date is a holiday nullable: true type: string movementId: description: >- UUID of the parent movement record this line belongs to nullable: true type: string movementInventoryMovementTypeTaxonomyFullPath: description: >- Full taxonomy path of the movement type. NOTE: unpopulated (null) in the current dataset nullable: true type: string movementInventoryMovementTypeTaxonomyId: description: >- UUID of the movement-type taxonomy node. NOTE: unpopulated (null) in the current dataset nullable: true type: string movementInventoryMovementTypeTaxonomyLanguage: description: >- Language of the movement-type taxonomy labels. NOTE: unpopulated (null) in the current dataset nullable: true type: string movementIsHoliday: description: Whether the movement date is a holiday nullable: true type: boolean movementIsWeekend: description: Whether the movement date falls on a weekend nullable: true type: boolean movementLineId: description: Unique identifier of the movement line (UUID) type: string movementMonthName: description: >- Month name of the movement date (e.g. 'november') nullable: true type: string movementMonthOfYear: description: Month of year of the movement date (1-12) nullable: true type: number movementQuarter: description: Calendar quarter of the movement date (1-4) nullable: true type: number movementSeason: description: >- Retail season of the movement date (e.g. 'fall_winter') nullable: true type: string movementTrimester: description: Trimester of the movement date (1-3) nullable: true type: number movementWeekOfMonth: description: Week of month of the movement date nullable: true type: number movementWeekOfYear: description: ISO week of year of the movement date (1-53) nullable: true type: number movementYear: description: Calendar year of the movement date nullable: true type: number organizationId: description: >- UUID of the organization that owns this movement line type: string productCode: description: Reference code of the product nullable: true type: string productFamilyMainTaxonomyFullPath: description: >- Full taxonomy path of the product's main family (e.g. 'Vêtements/Bas/Pantalons/Jeans (skinny, droits)') nullable: true type: string productFamilyMainTaxonomyId: description: UUID of the product's main family taxonomy node nullable: true type: string productGenderTaxonomyFullPath: description: >- Full taxonomy path of the product's gender classification (e.g. 'Femme') nullable: true type: string productGenderTaxonomyId: description: UUID of the product's gender taxonomy node nullable: true type: string productId: description: >- UUID of the product associated with the moved variant nullable: true type: string productImageUrl: description: URL of the product image nullable: true type: string productIsActive: description: Whether the product is currently active nullable: true type: boolean productName: description: >- Display name of the product associated with the moved variant nullable: true type: string quantity: description: >- Number of units moved; negative for outflows (e.g. sales) nullable: true type: number shopCity: description: City of the shop nullable: true type: string shopCode: description: Reference code of the shop nullable: true type: string shopCountry: description: Country identifier of the shop nullable: true type: string shopCountryId: description: UUID of the shop's country nullable: true type: string shopId: description: UUID of the shop where the movement occurred nullable: true type: string shopIsActive: description: Whether the shop is currently active nullable: true type: boolean shopName: description: >- Display name of the shop where the movement occurred nullable: true type: string shopRegion: description: >- Region of the shop (e.g. "Provence-Alpes-Côte d'Azur") nullable: true type: string sizeTaxonomyFullPath: description: Full path of the size taxonomy (e.g. 'M') nullable: true type: string sizeTaxonomyId: description: UUID of the size taxonomy node nullable: true type: string sizeTaxonomyLanguage: description: Language of the size taxonomy labels (e.g. 'fr') nullable: true type: string unitCost: description: Cost per unit at the time of the movement nullable: true type: number updatedAt: description: >- ISO 8601 datetime of the last update to this movement line record (format: date-time; 'T' separator, '+00:00' offset) nullable: true type: string variantCode: description: >- Reference code of the variant from the POS system nullable: true type: string variantCollectionId: description: UUID of the collection the variant belongs to nullable: true type: string variantCollectionName: description: >- Display name of the collection the variant belongs to nullable: true type: string variantColorTaxonomyFullPath: description: >- Full taxonomy path of the variant's primary color (e.g. 'Couleurs Neutres/Neutre/Noirs/Noir') nullable: true type: string variantDisplayName: description: >- Short display name of the variant (e.g. the colorway) nullable: true type: string variantFullName: description: >- Full descriptive name of the variant (e.g. product + colorway) nullable: true type: string variantGenderTaxonomyFullPath: description: >- Full taxonomy path of the variant's gender, if set nullable: true type: string variantId: description: UUID of the product variant that was moved nullable: true type: string variantIsActive: description: Whether the variant is currently active nullable: true type: boolean variantName: description: >- Display name of the variant (e.g. colorway or size label) nullable: true type: string variantSecondaryColorTaxonomyFullPath: description: >- Full taxonomy path of the variant's secondary color, if any nullable: true type: string required: - movementLineId - code - movementId - organizationId - quantity - movementDate - movementCode - movementDescription - movementInventoryMovementTypeTaxonomyId - unitCost - movementCost - movementDateKey - movementDayName - movementDayOfWeek - movementDayOfMonth - movementDayOfYear - movementWeekOfYear - movementWeekOfMonth - movementMonthName - movementMonthOfYear - movementQuarter - movementTrimester - movementSeason - movementYear - movementIsWeekend - movementIsHoliday - movementHolidayName - shopId - shopName - shopCode - shopCountryId - shopCountry - shopRegion - shopCity - shopIsActive - brandId - brandName - brandCode - brandImageUrl - brandMainBrandTypeTaxonomyId - brandMainBrandTypeTaxonomyFullPath - variantId - variantFullName - variantDisplayName - variantName - variantCode - variantIsActive - variantCollectionId - variantCollectionName - productId - productName - productCode - productImageUrl - productFamilyMainTaxonomyId - productFamilyMainTaxonomyFullPath - productGenderTaxonomyId - productGenderTaxonomyFullPath - productIsActive - inventoryItemId - inventoryItemFullName - inventoryItemSku - inventoryItemCode - sizeTaxonomyId - sizeTaxonomyFullPath - sizeTaxonomyLanguage - variantColorTaxonomyFullPath - variantSecondaryColorTaxonomyFullPath - variantGenderTaxonomyFullPath - movementInventoryMovementTypeTaxonomyFullPath - movementInventoryMovementTypeTaxonomyLanguage - createdAt - updatedAt type: object type: array page: type: number pageSize: type: number total: type: number required: - data - total - page - pageSize type: object success: enum: - true type: boolean required: - success - data type: object description: Successful response '400': description: Validation error '401': description: Unauthorized '500': description: Internal server error security: - BearerAuth: [] components: securitySchemes: BearerAuth: bearerFormat: JWT description: >- User session token issued by NextAuth. For human users accessing Solya via the web application. scheme: bearer type: http ````