> ## 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 sales lines (sales transactions / sell-through) > Returns a paginated list of individual sales lines — the line-item sales transactions (what sold), each carrying quantity sold, unit price, revenue, discounts, cost (COGS) and margin, plus the shop, brand, product, variant and size it belongs to. Use this to analyse sales history and sell-through, compute revenue or units sold, or drill into discounting and margin, filtered by shop, brand, product, variant, line type, and date range. This is the granular fact table; for per-product roll-ups (best-sellers, totals) use GET /products, and for forward demand use GET /forecasts. ## OpenAPI ````yaml /openapi.json get /api/sales-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/sales-lines: get: tags: - Sales Lines summary: List sales lines (sales transactions / sell-through) description: >- Returns a paginated list of individual sales lines — the line-item sales transactions (what sold), each carrying quantity sold, unit price, revenue, discounts, cost (COGS) and margin, plus the shop, brand, product, variant and size it belongs to. Use this to analyse sales history and sell-through, compute revenue or units sold, or drill into discounting and margin, filtered by shop, brand, product, variant, line type, and date range. This is the granular fact table; for per-product roll-ups (best-sellers, totals) use GET /products, and for forward demand use GET /forecasts. operationId: listSalesLines 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: brandId required: false schema: description: Filter by brand UUID type: string - in: query name: productId required: false schema: description: Filter by product UUID type: string - in: query name: variantId required: false schema: description: Filter by variant UUID type: string - in: query name: lineType required: false schema: description: >- Filter by line type. Enum (lowercase, matching stored values): 'sale' (regular sale), 'return' (returned item) enum: - sale - return type: string - in: query name: dateFrom required: false schema: description: >- Return lines where saleDate >= 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 saleDate column. type: string - in: query name: dateTo required: false schema: description: >- Return lines where saleDate <= 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 saleDate column. type: string - in: query name: sortBy required: false schema: description: >- Column to sort by. Allowed: 'saleDate', 'quantity', 'price'. Defaults to 'saleDate'. type: string - in: query name: sortOrder required: false schema: description: >- Sort direction: 'asc' or 'desc'. Default order is saleDate descending (most recent first). enum: - asc - desc type: string responses: '200': content: application/json: examples: sample: summary: >- One sales line returned on the first page (full denormalized fact_sales_lines row) value: data: - brandCode: maje brandId: demo-brand-a57dc5b8 brandImageUrl: >- https://solyastagingwedataplatfs.blob.core.windows.net/brand-images/brands/maje/logo.png brandIsActive: true brandMainBrandTypeTaxonomyFullPath: null brandMainBrandTypeTaxonomyId: null brandName: Maje code: null cost: 82.43 costPurchasePrice: 82.43 costPurchasePriceExclTax: 68.69 costWeightedAverage: 82.43 createdAt: '2026-06-13T03:40:41.912898+00:00' discountArticleAmountExclTax: 0 discountArticleAmountInclTax: 0 discountGlobalAmountExclTax: 0 discountTotalAmountExclTax: 0 discountTotalAmountInclTax: 0 inventoryItemCode: INV-000096 inventoryItemFullName: Robe bohème à fleurs - Beige - XS inventoryItemId: demo-inv-item-65e30fb4 inventoryItemSku: SKU-000096 lineType: sale margin: 201.5 organizationId: demo price: 183.18 productCode: robe-boheme-a-fleurs productFamilyMainTaxonomyFullPath: Vêtements/Robes/Robes/Robes trapèze productFamilyMainTaxonomyId: solya_family_fr_1ed879c0 productGenderTaxonomyFullPath: Femme productGenderTaxonomyId: solya_gender_fr_43c65bcc productId: demo-product-e95a1ecd productImageUrl: >- https://solyastagingwedataplatfs.blob.core.windows.net/product-images/products/maje/robe_boheme_a_fleurs/image_0.jpeg productIsActive: true productName: Robe bohème à fleurs quantity: 2 saleCode: S-00019188 saleDate: '2026-05-08' saleDateKey: 20260508 saleDayName: friday saleDayOfMonth: 8 saleDayOfWeek: 5 saleDayOfYear: 128 saleHolidayName: victory_day_2026 saleId: 280f71de-9910-4064-8c37-3880a21d928f saleIsHoliday: true saleIsWeekend: false saleLineId: 00001750-0ce3-4486-917d-0466cbfbf52b saleMonthName: may saleMonthOfYear: 5 saleQuarter: 2 saleSeason: spring_summer saleTrimester: 2 saleWeekOfMonth: 2 saleWeekOfYear: 19 saleYear: 2026 shopCity: Marseille shopCode: boutique-marseille-vieux-port shopCountry: 66b26b04-1ae1-4c22-8b67-2175b9859797 shopCountryId: 66b26b04-1ae1-4c22-8b67-2175b9859797 shopId: demo-shop-06490461 shopIsActive: true shopName: Boutique Marseille - Vieux Port shopRegion: Provence-Alpes-Côte d'Azur sizeTaxonomyFullPath: XS sizeTaxonomyId: solya_size_fr_6e9ce024 sizeTaxonomyLanguage: fr tax: 36.64 updatedAt: '2026-06-13T03:40:41.912898+00:00' variantCode: robe-boheme-a-fleurs-beige variantCollectionId: null variantCollectionName: null variantColorTaxonomyFullPath: Couleurs Neutres/Neutre/Beige/Phantom variantDisplayName: Beige variantFullName: Robe bohème à fleurs - Beige variantGenderTaxonomyFullPath: null variantId: demo-variant-dbb3f455 variantIsActive: true variantName: Robe bohème à fleurs - Beige variantSecondaryColorTaxonomyFullPath: null page: 1 pageSize: 20 total: 214803 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 sold 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 associated with the sold variant nullable: true type: string code: description: >- Reference code of the sale line from the POS system nullable: true type: string cost: description: Total cost of goods sold for this line nullable: true type: number costPurchasePrice: description: >- Purchase price component of the cost for this line nullable: true type: number costPurchasePriceExclTax: description: >- Purchase price component of the cost, excluding tax nullable: true type: number costWeightedAverage: description: Weighted-average cost used for this line nullable: true type: number createdAt: description: >- ISO 8601 datetime when the sales line record was created (format: date-time; 'T' separator, '+00:00' offset) nullable: true type: string discountArticleAmountExclTax: description: >- Article-level (line-specific) discount, excluding tax nullable: true type: number discountArticleAmountInclTax: description: >- Article-level (line-specific) discount, including tax nullable: true type: number discountGlobalAmountExclTax: description: >- Global (transaction-level) discount allocated to this line, excluding tax nullable: true type: number discountTotalAmountExclTax: description: >- Total discount amount applied to this line, excluding tax nullable: true type: number discountTotalAmountInclTax: description: >- Total discount amount applied to this line, including tax nullable: true type: number 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 lineType: description: >- Type of line. Stored lowercase. Known values: 'sale' (regular sale), 'return' (returned item) nullable: true type: string margin: description: >- Gross margin amount for this line (price minus cost) nullable: true type: number organizationId: description: >- UUID of the organization that owns this sales line type: string price: description: Total selling price for this line including tax nullable: true type: number 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/Robes/Robes/Robes trapèze') 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 sold 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 sold variant nullable: true type: string quantity: description: Number of units sold; negative for returns nullable: true type: number saleCode: description: Reference code of the parent sale transaction nullable: true type: string saleDate: description: >- Date the sale was recorded (ISO 8601 date 'YYYY-MM-DD') nullable: true type: string saleDateKey: description: Integer date key for the sale date (YYYYMMDD) nullable: true type: number saleDayName: description: >- Day-of-week name of the sale date (e.g. 'friday') nullable: true type: string saleDayOfMonth: description: Day of month of the sale date (1-31) nullable: true type: number saleDayOfWeek: description: >- Day of week of the sale date (1=Monday … 7=Sunday) nullable: true type: number saleDayOfYear: description: Day of year of the sale date (1-366) nullable: true type: number saleHolidayName: description: >- Name of the holiday, if the sale date is a holiday nullable: true type: string saleId: description: >- UUID of the parent sale transaction this line belongs to nullable: true type: string saleIsHoliday: description: Whether the sale date is a holiday nullable: true type: boolean saleIsWeekend: description: Whether the sale date falls on a weekend nullable: true type: boolean saleLineId: description: Unique identifier of the sale line (UUID) type: string saleMonthName: description: Month name of the sale date (e.g. 'may') nullable: true type: string saleMonthOfYear: description: Month of year of the sale date (1-12) nullable: true type: number saleQuarter: description: Calendar quarter of the sale date (1-4) nullable: true type: number saleSeason: description: >- Retail season of the sale date (e.g. 'spring_summer', 'fall_winter') nullable: true type: string saleTrimester: description: Trimester of the sale date (1-3) nullable: true type: number saleWeekOfMonth: description: Week of month of the sale date nullable: true type: number saleWeekOfYear: description: ISO week of year of the sale date (1-53) nullable: true type: number saleYear: description: Calendar year of the sale date 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 sale was made 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 sale was made 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. 'XS') 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 tax: description: >- Tax amount included in the selling price for this line nullable: true type: number updatedAt: description: >- ISO 8601 datetime of the last update to this sales 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/Beige/Phantom') 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 sold 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: - saleLineId - saleId - organizationId - code - quantity - price - tax - discountTotalAmountExclTax - discountTotalAmountInclTax - discountGlobalAmountExclTax - discountArticleAmountExclTax - discountArticleAmountInclTax - cost - costPurchasePrice - costPurchasePriceExclTax - costWeightedAverage - margin - saleDate - saleCode - lineType - saleDateKey - saleDayName - saleDayOfWeek - saleDayOfMonth - saleDayOfYear - saleWeekOfYear - saleWeekOfMonth - saleMonthName - saleMonthOfYear - saleQuarter - saleTrimester - saleSeason - saleYear - saleIsWeekend - saleIsHoliday - saleHolidayName - 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 - brandIsActive - 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 ````