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

# List products

> Returns a paginated list of the store's products (the ecommerce catalog), newest first, with shop, currency and category populated.

Returns a paginated list of the store's products (the ecommerce catalog), newest first, with shop, currency and category populated. Supports filtering by category, free-text search, exact barcode and stock status. Requires the `READ_INVENTORY` scope.


## OpenAPI

````yaml GET /products
openapi: 3.1.0
info:
  title: Salesive Store API
  description: >-
    REST interface for querying products, categories, and merchandising banners
    exposed by Salesive storefronts.
  version: 1.0.0
servers:
  - description: Production
    url: https://store.salesive.com/api/v1
security:
  - BearerAuth: []
    ShopIdHeader: []
paths:
  /products:
    get:
      summary: List products
      description: Retrieve a paginated list of products with optional search filtering.
      parameters:
        - $ref: '#/components/parameters/XShopIdHeader'
        - name: page
          in: query
          description: Page number to return (defaults to 1).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Maximum number of products per page (defaults to 10).
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: q
          in: query
          description: Optional search phrase applied to product names or descriptions.
          schema:
            type: string
      responses:
        '200':
          description: Paginated products response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCollection'
components:
  parameters:
    XShopIdHeader:
      name: x-shop-id
      in: header
      description: >-
        Optional identifier that scopes responses to a specific storefront when
        the referer cannot be inferred.
      required: false
      schema:
        type: string
  schemas:
    ProductCollection:
      type: object
      required:
        - products
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        foods:
          type: array
          items:
            $ref: '#/components/schemas/Product'
          description: Compatibility alias returned for food storefronts.
        catalogType:
          type: string
          enum:
            - product
            - food
            - service
        pagination:
          type: object
          properties:
            total:
              type: integer
              minimum: 0
            page:
              type: integer
              minimum: 1
            limit:
              type: integer
              minimum: 1
            pages:
              type: integer
              minimum: 1
            hasNext:
              type: boolean
            hasPrev:
              type: boolean
            nextPage:
              type:
                - integer
                - 'null'
            prevPage:
              type:
                - integer
                - 'null'
    Product:
      type: object
      required:
        - id
        - name
        - price
      properties:
        id:
          type: string
          description: Unique product identifier.
        itemType:
          type: string
          enum:
            - product
            - food
            - service
          description: Catalog item type.
        catalogType:
          type: string
          enum:
            - product
            - food
            - service
          description: Catalog response type for the current storefront.
        name:
          type: string
          description: Display name of the product.
        description:
          type: string
          description: Rich description of the product.
        price:
          type: number
          format: float
          description: Unit price for the product.
        currency:
          type: string
          description: ISO currency code for the product price.
        category:
          type: string
          description: Identifier of the category the product belongs to.
        status:
          type: string
          description: Derived status such as active or archived.
        images:
          type: array
          items:
            type: string
            format: uri
          description: Optional list of image URLs for the product.
        addons:
          type: array
          items:
            $ref: '#/components/schemas/FoodAddon'
          description: Available add-ons for food catalog items.
        variants:
          type: array
          items:
            type: object
            properties:
              sku:
                type: string
              options:
                type: object
                additionalProperties:
                  type: string
              stock:
                type: integer
                minimum: 0
          description: Optional list of variant definitions for the product.
    FoodAddon:
      type: object
      required:
        - name
        - price
        - maxQuantity
        - available
      properties:
        _id:
          type: string
        name:
          type: string
        description:
          type: string
          description: >-
            Optional helper text shown in the UI and returned by add-on
            endpoints.
        price:
          type: number
        maxQuantity:
          type: integer
          minimum: 1
        image:
          type:
            - string
            - 'null'
          format: uri
        available:
          type: boolean
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued by the Salesive Store API for authenticated shoppers.
    ShopIdHeader:
      type: apiKey
      in: header
      name: x-shop-id
      description: >-
        Optional storefront identifier sent as a header to scope responses to a
        specific shop. Try It requests remember this value once provided.

````