> ## 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 stock ledger entries (inventory transaction history) > Returns a paginated list of stock ledger entries — the chronological ledger of inventory transactions (receipts, sales, transfers, returns, adjustments) that explain how stock levels changed over time. Filter by shop, variant, movement category, movement type, and date range. Use this for an audit trail of stock movements. No get-by-ID endpoint as the table has no single primary key. ## OpenAPI ````yaml /openapi.json get /api/stock-ledger 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/stock-ledger: get: tags: - Stock Ledger summary: List stock ledger entries (inventory transaction history) description: >- Returns a paginated list of stock ledger entries — the chronological ledger of inventory transactions (receipts, sales, transfers, returns, adjustments) that explain how stock levels changed over time. Filter by shop, variant, movement category, movement type, and date range. Use this for an audit trail of stock movements. No get-by-ID endpoint as the table has no single primary key. operationId: listStockLedger 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: variantId required: false schema: description: Filter by variant UUID type: string - in: query name: movementCategory required: false schema: description: >- Filter by movement category. Values are title case as stored in the gold layer (NOT uppercase). Known values: 'Stock Out', 'Stock In', 'Correction'. Example: 'Stock Out'. type: string - in: query name: movementType required: false schema: description: >- Filter by movement type. Values are title case as stored in the gold layer (NOT uppercase). Known values: 'Sale', 'Receipt', 'Transfer', 'Return'. Example: 'Sale'. type: string - in: query name: dateFrom required: false schema: description: >- Return entries where movementTime >= 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 movementTime ledger timestamp, NOT saleDate. type: string - in: query name: dateTo required: false schema: description: >- Return entries where movementTime <= 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 movementTime ledger timestamp, NOT saleDate. type: string - in: query name: sortBy required: false schema: description: >- Column to sort by. Allowed: 'movementTime', 'quantityChange', 'stockAfter'. Defaults to 'movementTime'. type: string - in: query name: sortOrder required: false schema: description: >- Sort direction: 'asc' or 'desc'. Default order is movementTime descending (most recent first). enum: - asc - desc type: string responses: '200': content: application/json: examples: sample: summary: >- One stock-ledger entry returned on the first page (full denormalized stock_ledger row; title-case movementCategory/movementType) value: data: - averageCostOfIndividualInventoryItem: 51.92000000000004 brandCity: Paris brandCode: jonak brandCreatedAt: '2026-06-22T10:39:14.241Z' brandDeactivatedAt: null brandDescription: >- Chausseur parisien alliant tendance et savoir-faire cuir. brandId: demo-brand-1933d9b5 brandImageUrl: null brandIsActive: true brandMainBrandTypeTaxonomyFullPath: null brandMainBrandTypeTaxonomyId: null brandName: Jonak brandStyle: classique brandUpdatedAt: '2026-06-22T13:30:19.661Z' costOfStock: 51.92000000000004 createdAt: '2026-06-22T13:33:37.680Z' movementCategory: Stock Out movementCode: null movementId: null movementTime: '2026-06-22T00:00:00.000Z' movementType: Sale movementTypeId: null organizationId: demo polarisFlagType: null productClassificationCode: chaussures productClassificationName: Chaussures productCode: baskets-retro-en-cuir-et-suede productCreatedAt: '2026-06-22T10:39:23.372Z' productDeactivatedAt: null productExtraInformation: null productFamilyCode: chaussures productFamilyMainTaxonomyFullPath: >- Chaussures/Autres catégories unisexes/Chaussures techniques/Chaussures de marche (trail, trekking) productFamilyMainTaxonomyId: solya_family_fr_01fc3185 productFamilyName: Chaussures productGenderTaxonomyFullPath: Femme productGenderTaxonomyId: solya_gender_fr_43c65bcc productId: demo-product-f3aaf2c6 productImageUrl: null productIsActive: true productLongDescription: null productName: Baskets rétro en cuir et suède productShortDescription: >- Baskets d'inspiration vintage mêlant cuir et suède avec semelle gomme. Un confort décontracté au look nostalgique. productUpdatedAt: '2026-06-22T13:30:24.709Z' quantityChange: -1 saleCode: S-00018731 saleDate: '2026-06-22' saleId: e835b9c2-c530-4d7e-8d38-6488bb7447a0 shopAddress: 3 Passage Pommeraye, 44000 Nantes shopCity: Nantes shopCode: boutique-nantes-passage-pommeraye shopCountry: bcbbd48b-f69c-4e02-85f5-90b919b1270b shopCountryId: bcbbd48b-f69c-4e02-85f5-90b919b1270b shopCreatedAt: '2026-06-22T10:39:04.345Z' shopDeactivatedAt: null shopDescription: Boutique Nantes shopId: demo-shop-6fde3675 shopIsActive: true shopKind: STORE shopLat: '47.2184' shopLng: '-1.5536' shopName: Boutique Nantes - Passage Pommeraye shopRegion: Pays de la Loire shopStatus: ACTIVE shopSystem: demo shopUpdatedAt: '2026-06-22T13:30:14.027Z' sizeTaxonomyFullPath: '38' sizeTaxonomyId: solya_size_fr_73bc6288 sizeTaxonomyLanguage: fr stockAfter: 0 updatedAt: '2026-06-22T13:33:37.680Z' variantCode: baskets-retro-en-cuir-et-suede-marine variantCollectionId: demo-collection-787b0177 variantColorFullPath1: Couleurs Froides/Primaires/Bleu/Marine variantColorFullPath2: null variantColorFullPath3: null variantColorId1: solya_color_fr_31058a6a variantColorId2: null variantColorId3: null variantCreatedAt: '2026-06-22T10:39:35.359Z' variantDeactivatedAt: null variantDescription: null variantDisplayName: Marine variantFullName: Baskets rétro en cuir et suède - Marine variantId: demo-variant-00df093a variantIsActive: true variantName: Baskets rétro en cuir et suède - Marine variantUpdatedAt: '2026-06-22T13:30:30.155Z' page: 1 pageSize: 20 total: 98417 schema: properties: data: properties: data: items: properties: averageCostOfIndividualInventoryItem: description: >- Average cost of an individual inventory item for this variant+shop nullable: true type: number brandCity: description: City of the brand nullable: true type: string brandCode: description: Reference code of the brand nullable: true type: string brandCreatedAt: description: >- ISO 8601 timestamp when the brand record was created nullable: true type: string brandDeactivatedAt: description: >- ISO 8601 timestamp when the brand was deactivated, if any nullable: true type: string brandDescription: description: Description of the brand nullable: true type: string brandId: description: UUID of the brand associated with this variant nullable: true type: string brandImageUrl: description: URL of the brand logo image nullable: true type: string brandIsActive: description: Whether the brand is currently active nullable: true type: boolean 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 nullable: true type: string brandStyle: description: Style descriptor of the brand (e.g. 'classique') nullable: true type: string brandUpdatedAt: description: >- ISO 8601 timestamp of the last update to the brand record nullable: true type: string costOfStock: description: >- Cost of stock on hand for this variant+shop after the movement nullable: true type: number createdAt: description: >- ISO 8601 timestamp when the ledger row was created nullable: true type: string movementCategory: description: >- High-level category of the movement, title case (e.g. 'Stock Out', 'Stock In', 'Correction') nullable: true type: string movementCode: description: Reference code of the movement document nullable: true type: string movementId: description: >- UUID of the movement or sale that caused this entry nullable: true type: string movementTime: description: >- ISO 8601 timestamp of when the stock movement occurred nullable: true type: string movementType: description: >- Specific type of the movement, title case (e.g. 'Sale', 'Receipt', 'Transfer', 'Return') nullable: true type: string movementTypeId: description: UUID of the movement-type entity, if set nullable: true type: string organizationId: description: >- UUID of the organization that owns this ledger entry type: string polarisFlagType: description: Polaris-specific movement flag type, if set nullable: true type: string productClassificationCode: description: >- Classification code of the product (e.g. 'chaussures') nullable: true type: string productClassificationName: description: >- Classification name of the product (e.g. 'Chaussures') nullable: true type: string productCode: description: Reference code of the product nullable: true type: string productCreatedAt: description: >- ISO 8601 timestamp when the product record was created nullable: true type: string productDeactivatedAt: description: >- ISO 8601 timestamp when the product was deactivated, if any nullable: true type: string productExtraInformation: description: Extra information about the product nullable: true type: string productFamilyCode: description: Family code of the product nullable: true type: string productFamilyMainTaxonomyFullPath: description: Full taxonomy path of the product's main family nullable: true type: string productFamilyMainTaxonomyId: description: UUID of the product's main family taxonomy node nullable: true type: string productFamilyName: description: Family name of the product 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 this 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 productLongDescription: description: Long description of the product nullable: true type: string productName: description: Display name of the product nullable: true type: string productShortDescription: description: Short description of the product nullable: true type: string productUpdatedAt: description: >- ISO 8601 timestamp of the last update to the product record nullable: true type: string quantityChange: description: >- Net quantity change; negative for outflows (e.g. -1 for a sale) nullable: true type: number saleCode: description: >- Reference code of the associated sale; populated only for sale-type movements nullable: true type: string saleDate: description: >- Date of the associated sale; populated only for sale-type movements nullable: true type: string saleId: description: >- UUID of the associated sale; populated only for sale-type movements nullable: true type: string shopAddress: description: Street address of the shop nullable: true type: string shopCity: description: City of the shop nullable: true type: string shopCode: description: Short 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 shopCreatedAt: description: >- ISO 8601 timestamp when the shop record was created nullable: true type: string shopDeactivatedAt: description: >- ISO 8601 timestamp when the shop was deactivated, if any nullable: true type: string shopDescription: description: Description of the shop nullable: true type: string shopId: description: >- UUID of the shop where the stock movement occurred type: string shopIsActive: description: Whether the shop is currently active nullable: true type: boolean shopKind: description: Kind of shop (e.g. 'STORE', 'WAREHOUSE') nullable: true type: string shopLat: description: Latitude of the shop nullable: true type: string shopLng: description: Longitude of the shop nullable: true type: string shopName: description: Display name of the shop nullable: true type: string shopRegion: description: Region of the shop (e.g. 'Pays de la Loire') nullable: true type: string shopStatus: description: Status of the shop (e.g. 'ACTIVE') nullable: true type: string shopSystem: description: Source system identifier of the shop nullable: true type: string shopUpdatedAt: description: >- ISO 8601 timestamp of the last update to the shop record nullable: true type: string sizeTaxonomyFullPath: description: Full path of the size taxonomy (e.g. '38') nullable: true type: string sizeTaxonomyId: description: UUID of the size taxonomy entry for the variant nullable: true type: string sizeTaxonomyLanguage: description: Language of the size taxonomy labels (e.g. 'fr') nullable: true type: string stockAfter: description: >- Total stock on hand for this variant+shop after the movement nullable: true type: number updatedAt: description: >- ISO 8601 timestamp of the last update to this ledger row 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 variantColorFullPath1: description: >- Full taxonomy path of the variant's primary color (e.g. 'Couleurs Froides/Primaires/Bleu/Marine') nullable: true type: string variantColorFullPath2: description: >- Full taxonomy path of the variant's secondary color nullable: true type: string variantColorFullPath3: description: >- Full taxonomy path of the variant's tertiary color nullable: true type: string variantColorId1: description: >- UUID of the variant's primary color taxonomy node nullable: true type: string variantColorId2: description: >- UUID of the variant's secondary color taxonomy node nullable: true type: string variantColorId3: description: >- UUID of the variant's tertiary color taxonomy node nullable: true type: string variantCreatedAt: description: >- ISO 8601 timestamp when the variant record was created nullable: true type: string variantDeactivatedAt: description: >- ISO 8601 timestamp when the variant was deactivated, if any nullable: true type: string variantDescription: description: Description of the variant 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 variantId: description: >- UUID of the product variant for this ledger entry type: string variantIsActive: description: Whether the variant is currently active nullable: true type: boolean variantName: description: >- Display name of the variant (e.g. colorway label) nullable: true type: string variantUpdatedAt: description: >- ISO 8601 timestamp of the last update to the variant record nullable: true type: string required: - organizationId - variantId - shopId - sizeTaxonomyId - movementTime - movementCode - movementId - quantityChange - stockAfter - movementCategory - movementType - saleId - saleDate - saleCode - shopName - shopCode - shopCountryId - shopCountry - shopRegion - shopCity - shopIsActive - shopDescription - shopAddress - shopLat - shopLng - shopKind - shopStatus - shopSystem - shopDeactivatedAt - shopCreatedAt - shopUpdatedAt - variantFullName - variantDisplayName - variantName - variantCode - variantIsActive - variantDescription - variantCollectionId - variantDeactivatedAt - variantCreatedAt - variantUpdatedAt - productId - productName - productCode - productImageUrl - productFamilyMainTaxonomyId - productFamilyMainTaxonomyFullPath - productGenderTaxonomyId - productGenderTaxonomyFullPath - productIsActive - productShortDescription - productLongDescription - productExtraInformation - productClassificationCode - productClassificationName - productFamilyCode - productFamilyName - productDeactivatedAt - productCreatedAt - productUpdatedAt - brandId - brandName - brandCode - brandImageUrl - brandMainBrandTypeTaxonomyId - brandMainBrandTypeTaxonomyFullPath - brandDescription - brandCity - brandStyle - brandIsActive - brandDeactivatedAt - brandCreatedAt - brandUpdatedAt - sizeTaxonomyFullPath - sizeTaxonomyLanguage - variantColorId1 - variantColorFullPath1 - variantColorId2 - variantColorFullPath2 - variantColorId3 - variantColorFullPath3 - movementTypeId - polarisFlagType - averageCostOfIndividualInventoryItem - costOfStock - 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 ````