> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scango.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# List Products

> List or search products in your organization

Without the `q` query parameter, the endpoint returns products from the database up to **`limit`** (1–5000, default 100). With `q` set to a non-empty search string, results come from full-text search (for example on name and barcode); the same `limit` applies, but search **caps** the effective page size at **250** (see `meta.limit`). Use **`offset`** (0–10000, default 0) only with `q` for pagination. **`store`** applies only when searching with `q` and limits hits to products allowed for that store.

Responses include **`meta`** (`total`, `returned`, `limit`, and when using `q`, `offset`). See [Introduction](/api-reference/en/introduction#list-responses-meta).


## OpenAPI

````yaml GET /products
openapi: 3.0.1
info:
  title: Scango API
  description: >-
    API documentation for Scango's dashboard services.


    **List endpoints** (`GET /products`, `GET /orders`, `GET /suppliers`, `GET
    /categories`) return `data` plus `meta` with `total`, `returned`, and
    `limit` (applied page size; default **100**, maximum **5000** unless noted).
    Product search with `q` also includes `offset` and caps the effective page
    size at **250**. See schema `ListMeta`.
  version: 1.0.0
servers:
  - url: https://dashboard.scango.ch/api/v1
security:
  - bearerAuth: []
tags:
  - name: Products
    description: 'Product catalog: list, search, create, update, and delete.'
  - name: Orders
    description: Orders within a time range and single-order details.
  - name: Suppliers
    description: Supplier directory for your organization.
  - name: Categories
    description: Product categories.
paths:
  /products:
    get:
      tags:
        - Products
      summary: List or search products
      description: >-
        Returns products for your organization. With no `q` parameter (or an
        empty value after trimming), returns products from the database up to
        the requested `limit` (default 100, max 5000). When `q` is a non-empty
        string, returns products matching the query using full-text search (for
        example name and barcode); the same `limit` applies, but the search
        service **caps** the effective page size at **250** (see `meta.limit` in
        the response). Use `offset` (with `q` only) for pagination. The `store`
        parameter applies only when searching with `q`. Every successful list
        response includes `meta` with hit counts, `limit`, and when using `q`,
        `offset`.
      operationId: listProducts
      parameters:
        - name: q
          in: query
          required: false
          description: Search text. If omitted or empty, all products are returned.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: >-
            Maximum number of products in this response. Must be between 1 and
            5000. Default is 100. Applies with or without `q`; when using `q`,
            search caps the effective value at 250.
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 100
        - name: offset
          in: query
          required: false
          description: >-
            When using `q`, number of search hits to skip (pagination). Must be
            between 0 and 10000. Default is 0.
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
        - name: store
          in: query
          required: false
          description: When using `q`, only include products allowed for this store ID.
          schema:
            type: string
      responses:
        '200':
          description: >-
            List of products. When `q` is used, results come from search and
            field set may differ slightly from the non-search response. The
            response always includes `meta` with `limit` (and `offset` when
            searching); see `ListMeta`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              examples:
                fullCatalog:
                  summary: Full catalog (no search)
                  value:
                    data:
                      - id: a1b2c3
                        name: Mineral water 50cl
                        price: 120
                        barcode: '7610800001234'
                        taxCategory: '2.6'
                        category: cat_01
                        supplier: sup_01
                    meta:
                      total: 1
                      returned: 1
                      limit: 100
                searchResults:
                  summary: Search with q
                  value:
                    data:
                      - id: a1b2c3
                        name: Mineral water 50cl
                        price: 120
                        barcode: '7610800001234'
                        taxCategory: '2.6'
                        category: cat_01
                        supplier: sup_01
                    meta:
                      total: 42
                      returned: 20
                      limit: 20
                      offset: 0
        '400':
          description: Invalid query parameters (for example `limit` out of range)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                error:
                  formErrors: []
                  fieldErrors:
                    limit:
                      - Number must be less than or equal to 5000
        '403':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Forbidden
        '503':
          description: >-
            Product search is temporarily unavailable or the search request
            failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Product search is temporarily unavailable
      security:
        - bearerAuth: []
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
          description: Firestore document id (present in list and get responses)
        name:
          type: string
          description: Name of the product
        price:
          type: integer
          description: Price in cents
        supplier:
          type: string
          description: Supplier of the product
        taxCategory:
          type: string
          enum:
            - '8.1'
            - '2.6'
            - '3.8'
            - '0'
          description: Tax category
        category:
          type: string
          description: Category ID of the product
        declarations:
          type: string
          description: Product declarations
        barcode:
          type: string
          description: Product barcode
        depositProduct:
          type: integer
          description: Deposit amount in cents
        description:
          type: string
          description: Product description
        salePrice:
          type: integer
          description: Sale price in cents
        salePercentage:
          type: number
          description: Sale percentage
        salePriceDateFrom:
          type: string
          format: date
          description: Sale start date
        salePriceDateTo:
          type: string
          format: date
          description: Sale end date
        costPrice:
          type: integer
          description: Cost price in cents
        margin:
          type: number
          description: Product margin
        showOnHomescreen:
          type: boolean
          description: Show on homescreen
        showOnScreen:
          type: boolean
          description: Show on screen
        ageRestriction:
          type: boolean
          description: Age restriction
        showOnScale:
          type: boolean
          description: Show on scale
        saleStop:
          type: boolean
          description: Sale stop
        index:
          type: integer
          description: Product index
    ListMeta:
      type: object
      required:
        - total
        - returned
      description: >-
        Included on every list response. `returned` is the length of `data`. For
        Firestore-backed lists (`/products` without `q`, `/orders`,
        `/suppliers`, `/categories`), `total` equals `returned` for that
        response (the API does not return a separate full match count). For
        product search with `q`, `total` is the search index’s estimated number
        of matching documents. `limit` is the applied page size (query default
        **100**, maximum **5000**; search with `q` caps the effective page size
        at **250**). `offset` is only used for product search with `q`.
      properties:
        total:
          type: integer
          description: >-
            For product search with `q`, the search engine’s estimated total
            hits (may be approximate). For other list endpoints, the number of
            items in this response (same as `returned`).
        returned:
          type: integer
          description: Number of items in the `data` array in this response.
        limit:
          type: integer
          description: >-
            Applied `limit` from the request (default 100, max 5000). With `GET
            /products` and `q`, the effective value is at most 250.
        offset:
          type: integer
          description: >-
            Only when using `GET /products` with `q`: number of search hits
            skipped (pagination).
    ValidationErrorResponse:
      type: object
      description: >-
        Returned when query or body validation fails on some endpoints (e.g.
        invalid query parameters on GET /products). The `error` property holds a
        Zod flatten object.
      properties:
        error:
          $ref: '#/components/schemas/ValidationError'
    Error:
      type: object
      description: >-
        Most error responses use a string `error` field. Some responses may
        include `message` instead. Prefer reading `error` when present.
      properties:
        error:
          type: string
          description: Human-readable error (most common)
        message:
          type: string
          description: Alternative message field on some errors
    ValidationError:
      type: object
      description: >-
        Zod `flatten()` output: top-level `formErrors` and per-field
        `fieldErrors`.
      properties:
        formErrors:
          type: array
          items:
            type: string
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````